# `HuggingfaceClient.Inference.ProviderMapping`
[🔗](https://github.com/huggingface/huggingface_client/blob/v0.1.0/lib/huggingface_client/inference/provider_mapping.ex#L1)

ETS-backed GenServer that caches `inferenceProviderMapping` data fetched
from the HuggingFace Hub API (`GET /api/models/:model_id`).

## Responsibilities

- Normalises both array-of-objects and legacy map-of-objects API formats.
- Caches results in an ETS table so repeated calls for the same model skip
  the network round-trip.
- Provides `resolve_provider/3` to determine the effective provider string
  before a request is dispatched.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `clear_cache`

```elixir
@spec clear_cache() :: :ok
```

Clears the entire ETS cache.

# `get_mapping`

```elixir
@spec get_mapping(String.t(), String.t()) :: {:ok, map()} | {:error, term()}
```

Returns the provider mapping entry for `{model_id, provider}`.

For `provider == "auto"` returns a synthetic mapping immediately without
hitting the network.  For other providers, checks the ETS cache first,
then would fetch from the Hub (stubbed here — real fetch via `Hub.Client`
is wired in `HuggingfaceClient.Inference`).

# `normalise_mapping`

```elixir
@spec normalise_mapping(term(), String.t()) :: [map()]
```

Normalises a raw `inferenceProviderMapping` API value into a flat list of maps,
each containing at least `"provider"`, `"hf_model_id"`, and `"provider_id"`.

Handles:
- `nil` / missing → `[]`
- Array format: `[%{"provider" => "groq", ...}]`
- Legacy map format: `%{"groq" => %{"providerId" => ...}, ...}`

# `resolve_provider`

```elixir
@spec resolve_provider(String.t() | nil, String.t() | nil, String.t() | nil) ::
  {:ok, String.t()} | {:error, HuggingfaceClient.Error.InputError.t()}
```

Resolves the effective provider string given the user-supplied `provider`,
`model_id`, and optional `endpoint_url`.

Decision matrix:
- `endpoint_url` present → always `"hf-inference"` (direct endpoint, no routing)
- explicit provider string (not `"auto"`) → pass through unchanged
- `nil` → `"auto"`
- `"auto"` with no model → `{:error, InputError}`
- `"auto"` with model → `"auto"` (caller resolves later via `get_mapping/2`)

# `start_link`

# `store_mappings`

```elixir
@spec store_mappings([map()]) :: :ok
```

Stores a list of normalised mapping entries into the ETS cache.

---

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