pydantic_ai.models.fallback

ResponseRejected

Bases: Exception

Raised within a FallbackExceptionGroup when model responses are rejected by a response handler.

FallbackModel

Bases: Model

A model that uses one or more fallback models upon failure.

Apart from __init__, all methods are private or match those of the base class.

Attributes

model_name

The model name.

Type: str

model_id

The fully qualified model identifier, combining the wrapped models’ IDs.

Type: str

Methods

init

def __init__(
    default_model: Model | KnownModelName | str,
    fallback_models: Model | KnownModelName | str = (),
    fallback_on: FallbackOn = (ModelAPIError,),
)

Initialize a fallback model instance.

Parameters

default_model : Model | KnownModelName | str

The name or instance of the default model to use.

fallback_models : Model | KnownModelName | str Default: ()

The names or instances of the fallback models to use upon failure.

fallback_on : FallbackOn Default: (ModelAPIError,)

Conditions that trigger fallback to the next model. Accepts:

A tuple of exception types: (ModelAPIError, RateLimitError)
An exception handler (sync or async): lambda exc: isinstance(exc, MyError)
A response handler (sync or async): def check(r: ModelResponse) -> bool
A sequence mixing all of the above: [ModelAPIError, exc_handler, response_handler]

Handler type is auto-detected by inspecting type hints on the first parameter. If the first parameter is hinted as ModelResponse, it’s a response handler. Otherwise (including untyped handlers and lambdas), it’s an exception handler.

request

@async

def request(
    messages: list[ModelMessage],
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
) -> ModelResponse

Try each model in sequence until one succeeds.

In case of failure, raise a FallbackExceptionGroup with all exceptions.

Returns

ModelResponse

request_stream

@async

def request_stream(
    messages: list[ModelMessage],
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
    run_context: RunContext[Any] | None = None,
) -> AsyncIterator[StreamedResponse]

Try each model in sequence until one succeeds.

Returns

AsyncIterator[StreamedResponse]

ExceptionHandler

A sync or async callable that decides whether an exception should trigger fallback.

Default: Callable[[Exception], Awaitable[bool]] | Callable[[Exception], bool]

ResponseHandler

A sync or async callable that decides whether a model response should trigger fallback.

Default: Callable[[ModelResponse], Awaitable[bool]] | Callable[[ModelResponse], bool]

FallbackOn

The type of the fallback_on parameter to FallbackModel.