Pydantic AI

community · experimental

The adapter connects a Pydantic AI Agent to a running PowerContext Server. It provides Memory tools, automatic context preparation, and optional event capture. Its API and behavior are experimental.

Install from source

Add the Client and adapter from the same ref to your application environment. The examples use OpenAI:

uv add "powercontext[client] @ git+https://github.com/oceanbase/powercontext.git@master"
uv add "powercontext-pydantic-ai @ git+https://github.com/oceanbase/powercontext.git@master#subdirectory=integrations/pydantic-ai"
uv add "pydantic-ai-slim[openai]>=2.29,<3"

Start a separate Server from the same ref using Install and run. The adapter requires powercontext[client]>=0.0.3; use the matching current source for these examples. For another provider, replace the openai extra and model string.

Attach the preview capability

The example below uses OpenAI. For another provider, install the matching pydantic-ai-slim provider extra and change the model string.

Attach the capability to an Agent:

from pydantic_ai import Agent
from powercontext_pydantic_ai import PowerContext

agent = Agent(
    "openai:gpt-5.2",
    capabilities=[PowerContext()],
)

The capability adds powercontext_search, powercontext_remember, and powercontext_context. It also requests prepare_context from the latest textual user prompt and prepends at most one untrusted evidence block per run. A new run prepares context again even when it starts from the previous run's message history.

Use only the toolset when automatic preparation and capture are not wanted:

from pydantic_ai import Agent
from powercontext_pydantic_ai import PowerContextToolset

agent = Agent("openai:gpt-5.2", toolsets=[PowerContextToolset()])

Set environment configuration

export POWERCONTEXT_PYDANTIC_AI_BASE_URL=http://127.0.0.1:8000
export POWERCONTEXT_PYDANTIC_AI_TOKEN=opaque-server-token

Unlike the Codex and Claude Code plugin settings that accept a complete authorization value, this adapter accepts a bare token. Do not include Bearer or pass a complete Authorization header; the public Client adds the scheme.

Both PowerContext and PowerContextToolset accept a PowerContextSettings instance, a stable id (default powercontext), and a fixed or callable scope_id:

from pydantic_ai import RunContext
from powercontext_pydantic_ai import PowerContext, PowerContextSettings

settings = PowerContextSettings(timeout=5, max_bytes=4096)


def tenant_scope(ctx: RunContext[dict[str, str]]) -> str:
    return ctx.deps["powercontext_scope_id"]


capability = PowerContext(settings=settings, scope_id=tenant_scope)

The callback runs once per Agent run. Scope precedence is constructor string or callback, then environment SCOPE_ID. The adapter sends that explicit ID, or None, to resolve_scope_binding once per run and reuses the returned Scope ID for every recall, capture, flush, and tool call in that run. Explicit IDs must identify existing Server Scopes; when no ID is configured, the Server default is selected. The adapter does not inspect cwd, Git metadata, or paths to create Scope IDs.

Decide whether to capture events

Capture is off by default. Set POWERCONTEXT_PYDANTIC_AI_CAPTURE_EVENTS=true only when sending the initial user text, visible model text and tool calls, and completed tool arguments and results to the configured scope is acceptable. Thinking/reasoning content is excluded. Events are redacted for credential-like keys and known environment/Codex credentials, rendered within the configured byte limit, and stored under powercontext.pydantic-ai-capture-event/v1.

Every successful Capture advances the run-local Source position. A checkpoint Flush runs after the configured number of captures, and after_run flushes any remaining Source. Parallel tool results receive unique sequence numbers under a run-local lock. Recall, Capture, and Flush fail open during Server failures; explicit tool failures become ModelRetry. The first HTTP 401 or 403 logs one credential-free configuration warning.

Captured project content can remain sensitive after credential redaction. Protect the Server, scope, database, and logs accordingly.

Compare the MCP fallback

Connecting PowerContext MCP requires no adapter package, but it is a lower-capability option for Pydantic AI. MCP provides explicit tools; it does not automatically call prepare_context, capture trajectory events, or Flush at checkpoints and run completion.

The preview supports ordinary Pydantic AI runs. Durable execution through Temporal, DBOS, Prefect, or similar systems is not yet validated. Handoff, Candidate Review, Experience, and Skill operations are not included.