Skip to content

xtr_ai.bundle

The container integration: one bundle, configured by :class:AiConfig.

AI_CHANNEL module-attribute

AI_CHANNEL: Final = 'ai'

The log channel runs are logged on, when the logging bundle is active.

TOOL_TAG module-attribute

TOOL_TAG: Final = 'ai.tool'

The tag on the toolset built from a class's @as_tool methods for one agent.

DEFAULT_STORE module-attribute

DEFAULT_STORE: Final = 'default'

The conversation store also injected without a name.

CapabilityEntry

CapabilityEntry = str | Mapping[str, Any] | AbstractCapability[Any] | type[AbstractCapability[Any]]

A capability: pydantic-ai's declarative form ("Thinking", {"Thinking": {...}}), a capability itself (Thinking(effort="low")), or a capability class the container builds, with injection.

ConversationStoreEntry

ConversationStoreEntry = InMemoryConversationStoreConfig | OrmConversationStoreConfig | ServiceConversationStoreConfig

What AiConfig.conversation_stores maps a name to.

ToolsetEntry

ToolsetEntry = ToolsetRef | AgentToolRef

What an agent's toolsets holds.

AgentConfig dataclass

AgentConfig(platform: str, model: str, fallbacks: tuple[ModelRef, ...] = (), instructions: str | None = None, instructions_file: str | None = None, model_settings: Mapping[str, Any] = dict[str, Any](), retries: int | None = None, end_strategy: Literal['early', 'graceful', 'exhaustive'] = 'graceful', tool_timeout: float | None = None, metadata: Mapping[str, Any] = dict[str, Any](), deps_type: type[Any] = NoneType, output_type: Any = str, capabilities: tuple[CapabilityEntry, ...] = (), toolsets: tuple[ToolsetEntry, ...] = (), usage_limits: UsageLimits | None = None, timeout: float | None = None)

An agent: its model, its instructions, its capabilities and tools, and run defaults.

Attributes:

  • platform (str) –

    The platform its model runs on; may be env("…") to choose per environment.

  • model (str) –

    The model's name on that platform; may be env("…") too.

  • fallbacks (tuple[ModelRef, ...]) –

    Models tried in order when the model fails.

  • instructions (str | None) –

    The instructions, inline.

  • instructions_file (str | None) –

    A file holding them instead, read when the agent is first built. %kernel.project_dir% may start the path.

  • model_settings (Mapping[str, Any]) –

    pydantic-ai model settings for every run.

  • retries (int | None) –

    Tool and output retry budget.

  • end_strategy (Literal['early', 'graceful', 'exhaustive']) –

    pydantic-ai's end strategy.

  • tool_timeout (float | None) –

    Default timeout of a tool call, in seconds.

  • metadata (Mapping[str, Any]) –

    Stored with every run.

  • deps_type (type[Any]) –

    The type of the dependencies a run is given.

  • output_type (Any) –

    What a run returns.

  • capabilities (tuple[CapabilityEntry, ...]) –

    Capabilities: declarative, built already, or classes the container builds.

  • toolsets (tuple[ToolsetEntry, ...]) –

    Toolsets the container builds, and agents called as tools.

  • usage_limits (UsageLimits | None) –

    Default usage limits of a run; a call passing its own wins.

  • timeout (float | None) –

    Default timeout of a run, in seconds; a call passing its own wins.

model_id property

model_id: str

The id the agent's model is resolved by: <platform>:<model>.

AiBundle

AiBundle()

Bases: Bundle[AiConfig]

Registers each configured platform, agent and conversation store.

Nothing is built, imported from a provider's SDK or read from the environment while the container builds or boots: an agent is built the first time it is injected, and its platform the first time a run needs a model. Agents are injected by name — Annotated[AbstractAgent, Target("chat")] — and all of them as Mapping[Hashable, AbstractAgent].

Hold no mapping passes and no agents yet.

build

build(builder: ContainerBuilder) -> None

Collect @as_tool methods, and ready the conversation tables when the orm is there.

prepend_extension

prepend_extension(builder: ContainerBuilder) -> None

Add the ai channel to the logging configuration, when logging is active.

load_extension

load_extension(config: AiConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None

Register what config names; build none of it.

Raises:

  • InvalidConfigurationError –

    When a literal reference names nothing configured, agents call each other in a cycle, or an orm adapter lacks its bridge package.

process

process(builder: ContainerBuilder) -> None

Register what agents are built from, and give each the toolsets its tools make.

A capability, toolset or tool class the application registered itself is used as registered; any other is registered as a singleton.

Raises:

  • InvalidConfigurationError –

    When a tool names an agent that is not configured, or a capability, toolset or tool class is not a singleton — an agent is one, and outlives any scope.

AiConfig dataclass

AiConfig(platforms: Mapping[str, PlatformConfig] = dict[str, PlatformConfig](), agents: Mapping[str, AgentConfig] = dict[str, AgentConfig](), conversation_stores: Mapping[str, ConversationStoreEntry] = dict[str, ConversationStoreEntry]())

Named platforms, named agents and named conversation stores.

Empty by default: nothing is registered that is not configured, and nothing configured is built before it is first used.

Attributes:

InMemoryConversationStoreConfig dataclass

InMemoryConversationStoreConfig()

pydantic-ai's in-memory store: this process only, gone when it stops.

OrmConversationStoreConfig dataclass

OrmConversationStoreConfig(connection: str = 'default', table_prefix: str = 'ai_')

Two tables on an xtr-orm connection; needs xtr-ai-orm-conversation-store and OrmBundle.

Attributes:

  • connection (str) –

    The orm connection whose primary keeps the tables.

  • table_prefix (str) –

    What both table names start with.

ServiceConversationStoreConfig dataclass

ServiceConversationStoreConfig(service: type[ConversationStore])

A ConversationStore the application registers itself, under its class.

ModelRef dataclass

ModelRef(platform: str, model: str)

The model model of the platform platform: <platform>:<model>.

model_id property

model_id: str

The id runs name the model by.

PlatformConfig dataclass

PlatformConfig(provider: str, api_key: str | None = None, base_url: str | None = None, options: Mapping[str, Any] = dict[str, Any](), model_settings: Mapping[str, Any] = dict[str, Any]())

A provider, its key, its endpoint and its other options, under one name.

Attributes:

  • provider (str) –

    Any provider name pydantic-ai knows (openai, anthropic, azure, bedrock, google, ollama, …), or test / function for pydantic-ai's in-process test models.

  • api_key (str | None) –

    The key, usually env("…"). Never shown in a report.

  • base_url (str | None) –

    The endpoint, for an OpenAI-compatible server or a proxy.

  • options (Mapping[str, Any]) –

    The provider's other constructor keywords, passed unchanged — api_version, region, project, …; for test, TestModel's; for function, function and/or stream_function.

  • model_settings (Mapping[str, Any]) –

    Defaults every model of this platform carries, under the agent's and the run's — timeout, max_tokens, …

Its repr names every option but shows none of their values, and masks the credentials a base_url carries: an option can hold a key under any name a provider gives it.

AgentToolRef dataclass

AgentToolRef(agent: str, name: str | None = None, description: str | None = None)

Another configured agent, called as a tool.

Attributes:

  • agent (str) –

    The agent to call.

  • name (str | None) –

    The tool's name; the agent's name when left out.

  • description (str | None) –

    What the calling model reads about the tool.

ToolsetRef dataclass

ToolsetRef(service: type[AbstractToolset[Any]])

A toolset the container builds: a pydantic-ai AbstractToolset subclass, with injection.

The class is registered as a singleton unless the application registers it itself.