# `HuggingfaceClient.Provider`
[🔗](https://github.com/huggingface/huggingface_client/blob/v0.1.0/lib/huggingface_client/provider.ex#L1)

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"
    end

# `client_side_routing_only?`

```elixir
@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).

# `get_response`

```elixir
@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()}`.

# `make_base_url`

```elixir
@callback make_base_url(map()) :: String.t()
```

Returns the base API URL for `auth_method` (:hf_token | :provider_key).

# `make_route`

```elixir
@callback make_route(map()) :: String.t() | nil
```

Builds the URL path/route for a given request params map.

# `make_url`

```elixir
@callback make_url(map()) :: String.t()
```

Builds the full request URL given a params map (includes base + route).

# `prepare_headers`

```elixir
@callback prepare_headers(map(), boolean()) :: map()
```

Prepares the request headers map.  `binary_payload?` omits Content-Type.

# `prepare_payload`

```elixir
@callback prepare_payload(map()) :: map() | binary()
```

Prepares the JSON payload map / binary body for the request.

# `provider_id`

```elixir
@callback provider_id() :: String.t()
```

Returns the canonical provider ID string, e.g. `"groq"`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*