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 ¶
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:
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:
-
InvalidConfigurationError–When
nameorprovideris empty.
model_settings
property
¶
The defaults every model of this platform carries.
is_offline
property
¶
Whether the platform runs in process, with no key and no network.
provider_instance ¶
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 ¶
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:
-
PlatformUnavailableError–When the provider cannot be built, or refuses the model.
aclose
async
¶
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.
model ¶
Return the model model_name of this platform.
Asked for again, the same model is returned, so every run shares its client.
Raises:
-
PlatformUnavailableError–When the platform cannot build it.
aclose
async
¶
Release what the platform opened, such as its HTTP client.
The platform stays usable: a later model opens what it needs again.
PlatformRegistry ¶
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.
of
classmethod
¶
Return a registry over platforms already made.
get
async
¶
Return the platform name.
Raises:
-
PlatformUnavailableError–When no platform has that name, or
lookupcould not build it.
model
async
¶
Return the model <platform>:<model>, or None when no platform has the prefix.
Raises:
-
PlatformUnavailableError–When the platform cannot be built.
resolve
async
¶
The resolver ResolveModelId calls: :meth:model, ignoring the context.
platform_of ¶
Return the name of the platform that built model, or None for any other model.
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.
get
async
¶
Return the platform name.
Raises:
-
PlatformUnavailableError–When no platform has that name, or it cannot be built.
model
async
¶
Return the model <platform>:<model>, or None when no platform has the prefix.
Raises:
-
PlatformUnavailableError–When the platform cannot be built.
resolve
async
¶
The resolver ResolveModelId calls: :meth:model, ignoring the context.
platform_of ¶
Return the name of the platform that built model, or None for any other model.
RunClock
dataclass
¶
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)
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
¶
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: