Skip to content

xtr_ai

Named language-model platforms and agents built on pydantic-ai.

A platform is one configured provider — its key, its endpoint, its options — built the first time a run needs it. An agent's model id is <platform>:<model>, resolved through the platforms, so a model is chosen per environment without a code change. Run control reports what a run is doing and cancels it from another process.

Applications keep working with pydantic-ai's own types: an AbstractAgent, a ConversationStore. Everything here can be built by hand; the container integration lives in :mod:xtr_ai.bundle.

AiError

Bases: Exception

Base class for every error raised by this library.

Catch this to handle anything the integration can go wrong with; catch a subclass to handle one cause. Each subclass carries what a caller needs as typed attributes and composes its own message from them.

InvalidConfigurationError

Bases: AiError, ValueError

A platform, agent or conversation store configuration that cannot be used.

Raised while the container builds, or when a class is built by hand with a value it cannot use. The message names the entry at fault.

PlatformUnavailableError

PlatformUnavailableError(platform: str, reason: str)

Bases: AiError

A platform that is not configured, or cannot be built.

Raised the first time a run needs the platform — never while the container builds — so the console runs without any key. The message names the platform and, where one is missing, the environment variable or the package extra; it never carries a secret's value.

Attributes:

  • platform (str) –

    The platform asked for.

  • reason (str) –

    Why it cannot be used.

Name the platform and why it cannot be used.

Platform

Platform(name: str, provider: str, *, api_key: str | None = None, base_url: str | None = None, options: Mapping[str, Any] = _NO_OPTIONS, model_settings: ModelSettings | None = None)

Bases: PlatformInterface

A named provider: which one, its key, its endpoint and its other options.

Nothing is imported or built when a platform is made. The provider — and with it the provider's SDK and HTTP client — is built the first time a model is asked for, once per platform, so an application whose keys are not set still builds, boots and runs its console.

provider is any provider name pydantic-ai knows (openai, anthropic, azure, bedrock, google, ollama, …), so a provider pydantic-ai adds needs nothing here. Two more are served in process: test builds pydantic-ai's TestModel from options, and function builds a FunctionModel from options["function"] and/or options["stream_function"].

model_settings are this platform's defaults: every model it builds carries them, under the agent's settings and the run's.

Describe the platform; build nothing yet.

Raises:

name property

name: str

What the platform is known by: the prefix of its model ids.

provider property

provider: str

The provider name, as pydantic-ai knows it.

model_settings property

model_settings: ModelSettings | None

The defaults every model of this platform carries.

is_offline property

is_offline: bool

Whether the platform runs in process, with no key and no network.

provider_instance

provider_instance() -> Provider[Any]

Return the platform's provider, building it on first use.

Raises:

  • PlatformUnavailableError –

    When the provider is unknown, its package extra is not installed, or it refuses the configuration.

model

model(model_name: str) -> Model

Return the model model_name of this platform, building it on first use.

The same model object is returned every time it is asked for, so its provider's HTTP client is shared by every run.

Raises:

built

built(model: object) -> bool

Whether model is one this platform built.

aclose async

aclose() -> None

Close the provider's HTTP client, if the platform built one.

The platform stays usable: a later run opens a client again.

PlatformInterface

Bases: Protocol

A named source of models: one provider, reached one way.

Depend on this rather than on :class:~xtr_ai.platform.Platform, and a platform of the application's own — models from a client it already holds, a gateway, a recorded double — goes wherever a configured one does: into :class:~xtr_ai.platform_registry.PlatformRegistry, or registered in the container under this interface, qualified by its name.

name property

name: str

What the platform is known by: the prefix of its model ids.

provider property

provider: str

The provider the platform reaches, as pydantic-ai names it.

model

model(model_name: str) -> Model

Return the model model_name of this platform.

Asked for again, the same model is returned, so every run shares its client.

Raises:

built

built(model: object) -> bool

Whether model is one this platform returned from :meth:model.

aclose async

aclose() -> None

Release what the platform opened, such as its HTTP client.

The platform stays usable: a later model opens what it needs again.

PlatformRegistry

PlatformRegistry(names: Iterable[str], lookup: Callable[[str], Awaitable[PlatformInterface]])

Bases: PlatformRegistryInterface

Resolves <platform>:<model> ids through the configured platforms.

Each platform is asked for only when a model of it is, through lookup, so a platform whose configuration reads the environment reads it then and not before. Pass :meth:resolve to pydantic-ai's ResolveModelId capability and every agent, fallback and per-run model= naming a platform resolves here; an id whose prefix names no platform is left to pydantic-ai's own inference.

Any :class:~xtr_ai.platform_interface.PlatformInterface serves, not only a :class:~xtr_ai.platform.Platform.

registry = PlatformRegistry.of(
    Platform("local", "openai", base_url="http://localhost:11434/v1")
)
agent = Agent("local:llama-3.3-70b", capabilities=[ResolveModelId(registry.resolve)])

Know the platforms by names; build each through lookup when first needed.

names property

names: tuple[str, ...]

Every platform's name, in the order given.

of classmethod

of(*platforms: PlatformInterface) -> PlatformRegistry

Return a registry over platforms already made.

has

has(name: str) -> bool

Whether a platform is configured under name.

get async

get(name: str) -> PlatformInterface

Return the platform name.

Raises:

model async

model(model_id: str) -> Model | None

Return the model <platform>:<model>, or None when no platform has the prefix.

Raises:

resolve async

resolve(ctx: ModelResolutionContext[Any], model_id: str) -> Model | None

The resolver ResolveModelId calls: :meth:model, ignoring the context.

platform_of

platform_of(model: AbstractModel) -> str | None

Return the name of the platform that built model, or None for any other model.

aclose async

aclose() -> None

Close every platform this registry built.

PlatformRegistryInterface

Bases: Protocol

Every configured platform by name, and the model resolver built on them.

Depend on this rather than on :class:~xtr_ai.platform_registry.PlatformRegistry. Building a registry, and closing what it built, is its owner's business — the container's, or whoever made it by hand — and not part of what its users see.

names property

names: tuple[str, ...]

Every platform's name, in the order given.

has

has(name: str) -> bool

Whether a platform is configured under name.

get async

get(name: str) -> PlatformInterface

Return the platform name.

Raises:

model async

model(model_id: str) -> Model | None

Return the model <platform>:<model>, or None when no platform has the prefix.

Raises:

resolve async

resolve(ctx: ModelResolutionContext[Any], model_id: str) -> Model | None

The resolver ResolveModelId calls: :meth:model, ignoring the context.

platform_of

platform_of(model: AbstractModel) -> str | None

Return the name of the platform that built model, or None for any other model.

RunClock dataclass

RunClock(clock: ClockInterface)

Bases: AbstractCapability[Any]

Measures a run's deadline against clock instead of the system clock.

pydantic-ai reads a run's start time, and the time left before its timeout, from this clock — also for a run started inside another, which inherits the outer deadline. Message timestamps are not affected: pydantic-ai stamps those from the system clock.

RunDefaultsAgent

RunDefaultsAgent(wrapped: AbstractAgent[Any, Any], *, usage_limits: UsageLimits | None = None, timeout: float | None = None)

Bases: WrapperAgent[Any, Any]

Runs wrapped with usage_limits and timeout unless a call passes its own.

pydantic-ai takes both per run only. This wrapper adds no method and changes nothing else: run, run_sync, run_stream and iter all reach the wrapped agent through iter, where a default fills an argument the caller left out or passed as None. Being a wrapper, it is an AbstractAgent but not an Agent.

Wrap wrapped with the defaults its runs get.

RunLogging dataclass

RunLogging(logger: LoggerInterface, registry: PlatformRegistryInterface | None = None)

Bases: AbstractCapability[Any]

Logs each model response and each run's end, with counts and ids only.

Every record carries the agent, the run and conversation ids and the model; a response adds its token counts and finish reason, a run's end its totals, a failure the error's type. No prompt, instruction, message part or output is ever logged, nor an error's message, which may quote them.

Pass registry to name the platform that served each response.

agent_toolset

agent_toolset(agent: AgentSource, *, name: str, description: str | None = None) -> FunctionToolset[Any]

Return a toolset of one tool, name, that runs agent on a prompt.

The delegated run receives the calling run's dependencies, adds its usage to the calling run's and runs under the calling run's usage limits, so one prompt's limits bound everything it sets off — the delegated agent's own limits do not apply. It also inherits the caller's deadline. Pass a function returning the agent to build it only when the tool is first called.

Parameters:

  • agent (AgentSource) –

    The agent to delegate to, or what returns it.

  • name (str) –

    The tool's name.

  • description (str | None, default: None ) –

    What the calling model reads about the tool.