Behaviour that every inference provider module must implement.
Provider modules are discovered and dispatched through HuggingfaceClient.ProviderRegistry.
Each module typically use HuggingfaceClient.Provider to inherit default implementations
and may override any callback.
Minimal provider example
defmodule HuggingfaceClient.Provider.MyProvider do
use HuggingfaceClient.Provider
@impl true
def provider_id, do: "my-provider"
@impl true
def make_route(%{model: model}), do: "v1/models/#{model}/completions"
endSummary
Callbacks
Returns true if this provider requires client-side model resolution (i.e.
the caller must supply the provider's own model ID, and HF routing is not used).
Post-processes the raw decoded response.
Returns the base API URL for auth_method (:hf_token | :provider_key).
Builds the URL path/route for a given request params map.
Builds the full request URL given a params map (includes base + route).
Prepares the request headers map. binary_payload? omits Content-Type.
Prepares the JSON payload map / binary body for the request.
Returns the canonical provider ID string, e.g. "groq".
Callbacks
@callback client_side_routing_only?() :: boolean()
Returns true if this provider requires client-side model resolution (i.e.
the caller must supply the provider's own model ID, and HF routing is not used).
@callback get_response(term(), map()) :: {:ok, term()} | {:error, HuggingfaceClient.Error.ProviderOutputError.t()}
Post-processes the raw decoded response.
Returns {:ok, result} or {:error, ProviderOutputError.t()}.
Returns the base API URL for auth_method (:hf_token | :provider_key).
Builds the URL path/route for a given request params map.
Builds the full request URL given a params map (includes base + route).
Prepares the request headers map. binary_payload? omits Content-Type.
Prepares the JSON payload map / binary body for the request.
@callback provider_id() :: String.t()
Returns the canonical provider ID string, e.g. "groq".