> ## Documentation Index
> Fetch the complete documentation index at: https://powercontext.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pydantic AI Agent adapter (Preview)

> Review the future-facing Capability and Toolset API; neither PyPI nor Git subdirectory installation currently works.

> [!WARNING]
>
> Preview and not installable by ordinary users: `powercontext-pydantic-ai` is not on PyPI. Its source metadata requires final `powercontext[client]>=0.0.3`, while the repository is still pre-0.0.3. A Git subdirectory install therefore fails dependency resolution too. There is no working standalone install command to run today.

The API is available for review and future use. Repository contributors can exercise it through the root development environment, but that is not a supported consumer installation path. Real provider calls and durable-execution hosts were not validated in this verification.

## Choose the integration surface

### `PowerContext` Capability

The following is future-facing API, not a working installation tutorial:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from pydantic_ai import Agent
from powercontext_pydantic_ai import PowerContext


agent = Agent(
    "openai:gpt-5.2",
    capabilities=[PowerContext(scope_id="project:powercontext-101")],
)
```

`PowerContext` combines three model tools with once-per-run recall. It can also capture agent events, flush after capture checkpoints, and make a final catch-up flush after the run. Capture is off by default.

### `PowerContextToolset`

This future-facing form installs only the same three tools:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from pydantic_ai import Agent
from powercontext_pydantic_ai import PowerContextToolset


agent = Agent(
    "openai:gpt-5.2",
    toolsets=[PowerContextToolset(scope_id="project:powercontext-101")],
)
```

It has no automatic recall, capture, checkpoint flush, or final flush.

| Behavior | `PowerContext` | `PowerContextToolset` |
| - | -: | -: |
| `powercontext_search` | Yes | Yes |
| `powercontext_remember` | Yes | Yes |
| `powercontext_context` | Yes | Yes |
| Once-per-run automatic recall | Yes | No |
| Optional event capture | Yes; default `false` | No |
| Checkpoint and final catch-up flush | Yes, when capture is enabled | No |

The tools preserve the full public Client response as JSON, including statuses, Citations, and revision fields. They do not return an empty success when the Client fails.

This is a preview interface, not a package you can install today. The examples explain the intended Capability, Toolset, and Scope binding. To complete an integration now, use LangGraph, LangChain, or MCP. The outcome here is an accurate boundary assessment, not a successful installation of an unpublished package.

## Follow one bound run

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Agent binds the Capability or Toolset
→ resolve Scope once and open one async Client
→ Capability captures the initial prompt when enabled
→ Capability prepares and injects untrusted recall once
→ model may call one of three explicit tools
→ Capability captures visible model/tool events when enabled
→ successful capture checkpoints may flush
→ Capability makes a final catch-up flush
→ Client closes with the run
```

Automatic recall takes the latest textual user prompt and limits the query to 8192 characters. It prepends one system request labeled `untrusted historical evidence`. When old `message_history` is reused, recognized PowerContext blocks are removed before the current run's block is added. Recalled evidence is replaced, not accumulated as durable Agent history.

> [!WARNING]
>
> Recalled content is evidence, not instruction authority. Verify it against current files, APIs, capabilities, and authorization before acting on it.

## Understand the three tools

Each tool has a deliberately bounded input. The limit constrains what reaches PowerContext; it does not grant the model permission to persist that content.

| Tool | Purpose | Input bounds |
| - | - | - |
| `powercontext_search(query, limit=10, mode="auto")` | Search durable Memory and return exact response metadata | query 1–8192 chars; limit 1–50 |
| `powercontext_remember(text, kind="agent-note", reason=None)` | Make an explicit durable Memory write | text 1–8192 chars; kind 1–128; reason at most 512 |
| `powercontext_context(query)` | Prepare a fresh bounded context packet | query 1–8192 chars; context uses configured byte budget |

The configured `MAX_BYTES` and `CAPTURE_MAX_BYTES` ranges are 512–32768 UTF-8 bytes. Character limits and byte limits are different; non-ASCII content can reach the byte cap first.

## Resolve Scope once per run

A constructor string or callback has highest precedence:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from pydantic_ai import RunContext
from powercontext_pydantic_ai import PowerContext


def tenant_scope(ctx: RunContext[dict[str, str]]) -> str:
    return f"tenant:{ctx.deps['tenant_id']}"


capability = PowerContext(scope_id=tenant_scope)
```

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
constructor string/callback
→ POWERCONTEXT_PYDANTIC_AI_SCOPE_ID
→ normalized Git origin
→ local project path hash
```

The callback runs once while binding the run, so every automatic action and tool uses the same Scope. An explicit Scope that exceeds the shared limit is replaced with `sha256:<digest>`; a long derived Git Scope uses `git:sha256:<digest>`. Scope chooses data. It is not authentication or permission.

Callback exceptions, missing dependencies, and an empty result occur before the automatic HTTP fail-open boundary and can stop run binding. Test the resolver separately.

## Configure transport safely

These are future adapter settings, not installation commands:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export POWERCONTEXT_PYDANTIC_AI_BASE_URL=http://127.0.0.1:8000
export POWERCONTEXT_PYDANTIC_AI_TOKEN=opaque-server-token
export POWERCONTEXT_PYDANTIC_AI_SCOPE_ID=project:powercontext-101
export POWERCONTEXT_PYDANTIC_AI_MAX_BYTES=8000
export POWERCONTEXT_PYDANTIC_AI_CAPTURE_EVENTS=false
```

| Setting | Default | Accepted range or rule |
| - | -: | - |
| `TIMEOUT` | `10` seconds | Positive |
| `MAX_BYTES` | `8000` | 512–32768 |
| `CAPTURE_EVENTS` | `false` | Boolean |
| `CAPTURE_CHECKPOINT_EVERY` | `5` | 1–100 |
| `CAPTURE_MAX_BYTES` | `8192` | 512–32768 |

`TOKEN` must be a bare printable ASCII token with no whitespace. Do not include `Bearer `. The base URL must be HTTP or HTTPS, cannot contain credentials, a query, or a fragment, and is still subject to the Client's restriction on plaintext non-loopback HTTP.

## Decide what capture may send

With capture enabled, the adapter can send:

* the initial textual prompt;
* visible model text and tool calls;
* completed tool arguments and results.

Thinking and reasoning parts are excluded. Credential-shaped keys, known credential environment values, and configured auth values are redacted before Source capture. Sensitive code, prompts, business data, or tool results can remain. Redaction is not a DLP boundary.

Captured events use:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
powercontext.pydantic-ai-capture-event/v1
```

Capture creates Sources, not approved Memory. A successful checkpoint or final flush may run extraction if the Server has generation configured, but generated durable knowledge still follows PowerContext's domain and Review rules.

## Distinguish automatic and explicit failures

The same transport error has different user-visible consequences depending on who requested the operation. Use the table to preserve that distinction.

| Path | Failure behavior |
| - | - |
| Automatic recall | Client error fails open; the model request continues without injected context |
| Automatic capture | Client or serialization error fails open; the Agent run continues |
| Checkpoint/final flush | Client error, timeout, or no cursor progress fails open |
| Explicit tool | `ClientError` becomes `ModelRetry`; it is never reported as an empty success |
| Scope/configuration during binding | Propagates before the automatic HTTP boundary |
| First 401/403 | Emits one bounded warning without token or content |

Recall, capture, and flush are independent helper paths. Their failure does not prove the Scope is empty, and fail-open does not bypass URL or token validation.

## Use MCP when the adapter is unavailable

PowerContext MCP does not need the Pydantic AI-specific package. It can expose explicit operations to an Agent, but it does not reproduce this Capability's automatic `prepare_context`, transient history replacement, event capture, or checkpoint/final flush.

## Currently unsupported or not validated

| Item | Status |
| - | - |
| Public PyPI installation | **Unsupported** today |
| Git subdirectory installation from the current repository | **Unsupported** today because of the final `>=0.0.3` dependency |
| Handoff operations | **Unsupported** by this adapter |
| Candidate Review operations | **Unsupported** by this adapter |
| Direct Experience or Skill operations | **Unsupported** by this adapter |
| Temporal, DBOS, Prefect, and similar durable execution | **Not validated** |
| Real provider calls on a supported consumer install | **Not validated** because no such install path exists |
| Recalled evidence persisted as trusted Agent history | **Unsupported**; it is untrusted and replaced for each run |

## Completion check

Before adopting a future compatible release, confirm that:

* both the adapter and a compatible final `powercontext[client]` package can actually be installed;
* you chose `PowerContext` for lifecycle behavior or `PowerContextToolset` for tools only;
* capture remains off unless its privacy boundary has been reviewed;
* the Scope callback is deterministic, tenant-safe, and tested outside fail-open handling;
* the token is bare printable ASCII and the Server URL passes transport restrictions;
* query, tool limit, and context-byte bounds are enforced;
* automatic failures continue the run while explicit tool failures remain visible;
* recalled evidence is treated as temporary untrusted history;
* unsupported Handoff, Review, Experience, and Skill operations are provided through another approved surface if needed.

Continue with [LangGraph](https://powercontext.mintlify.site/en/frameworks/langgraph.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.