Nous.Fallback (nous v0.13.3)

View Source

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.

Summary

Functions

build_model_chain(primary, fallbacks)

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

fallback_eligible?(arg1)

Returns true if the error is eligible for fallback retry.

parse_fallback_models(models, opts \\ [])

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

with_fallback(models, request_fn, opts \\ [])

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

Functions

build_model_chain(primary, fallbacks)

@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?(arg1)

@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(models, opts \\ [])

@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(models, request_fn, opts \\ [])

@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])