# `Nous.Fallback`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/fallback.ex#L1)

Fallback model chain support.

Provides automatic failover to alternative models when a primary model
request fails with a `ProviderError` or `ModelError`.

## Usage

    # Build a model chain and try each in order
    models = Fallback.build_model_chain(primary, fallbacks)
    Fallback.with_fallback(models, fn model -> dispatch(model) end)

Only provider/model-level errors trigger fallback. Errors like
`ValidationError`, `MaxIterationsExceeded`, `ExecutionCancelled`, and
`ToolError` are returned immediately since retrying with a different
model would not help.

# `build_model_chain`

```elixir
@spec build_model_chain(Nous.Model.t(), [Nous.Model.t()]) :: [Nous.Model.t()]
```

Build the full model chain: primary model followed by fallback models.

# `fallback_eligible?`

```elixir
@spec fallback_eligible?(term()) :: boolean()
```

Returns `true` if the error is eligible for fallback retry.

Eligible errors (infrastructure/provider failures):
- `ProviderError` — API call failed (rate limit, server error, timeout, auth)
- `ModelError` — model-level failure from the provider

Non-eligible errors (application-level, retrying won't help):
- `ValidationError` — structured output failed validation
- `MaxIterationsExceeded` — agent loop limit hit
- `ExecutionCancelled` — explicitly cancelled
- `ToolError` / `ToolTimeout` — tool execution failed
- `UsageLimitExceeded` — usage budget exhausted
- `ConfigurationError` — misconfiguration

# `parse_fallback_models`

```elixir
@spec parse_fallback_models(
  [String.t() | Nous.Model.t()],
  keyword()
) :: [Nous.Model.t()]
```

Parse a mixed list of model strings and `Model.t()` structs into `[Model.t()]`.

# `with_fallback`

```elixir
@spec with_fallback(
  [Nous.Model.t()],
  (Nous.Model.t() -> {:ok, term()} | {:error, term()}),
  keyword()
) ::
  {:ok, term()} | {:error, term()}
```

Try each model in the chain until one succeeds or all fail.

The `request_fn` receives a `Model.t()` and must return
`{:ok, result}` or `{:error, reason}`.

On fallback-eligible errors, emits telemetry and tries the next model.
On non-eligible errors, returns immediately.

## Options

- `:telemetry_prefix` — prefix for telemetry events (default: `[:nous, :fallback]`)

---

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