feat(integrations): support pydantic-ai integrate

[thunguo]

Which issue or RFC does this PR close?

Closes #1269 .

Rationale for this change

Pydantic AI users currently lack a native PowerContext integration that follows Pydantic AI’s toolset and capability lifecycles.

This PR adds an independent adapter that provides Memory tools, automatic context preparation, optional event capture, and checkpoint flushing through the public PowerContext Python Client.

What changes are included in this PR?

• Add the independently distributable powercontext-pydantic-ai package.
• Export the following public APIs:
  • PowerContextSettings
  • PowerContextToolset
  • PowerContext
• Add per-run PowerContextClient lifecycle management and the following tools:
  • powercontext_search
  • powercontext_remember
  • powercontext_context
• Add automatic context preparation from the latest user prompt.
  • Context is injected once per run as untrusted historical evidence.
  • Reusing history in a new run prepares context again.
  • Empty context is not injected.
• Add deterministic scope resolution using:
  1. Constructor value or callback
  2. POWERCONTEXT_PYDANTIC_AI_SCOPE_ID
  3. Normalized Git origin
  4. A deterministic local hash
• Convert tool-side client errors into Pydantic AI ModelRetry errors.
• Keep context recall, capture, and flush operations fail-open when the PowerContext server is unavailable.
• Add optional event capture for user prompts, visible model output, tool calls, arguments, and results.
  • Thinking content is excluded.
  • Capture is disabled by default.
  • Captured JSON is bounded and credentials are redacted.
  • Source IDs are deterministic and idempotent.
  • Checkpoint and final-run flushing are supported.
• Extract shared capture sanitization and bounded JSON rendering into powercontext.client.capture, and reuse it in the Bub integration.
• Add English and Chinese configuration documentation and update the documentation navigation and interface reference.
• Add adapter unit tests and an end-to-end test using FunctionModel, the real server lifecycle, and SQLite.
• Update root type-checking and test import paths for the new integration.

This PR does not modify the server API, OpenAPI schema, or MCP allow-list.

Are there any user-facing changes?

Yes. Users can install the new package and attach PowerContext directly to a Pydantic AI agent.

The integration introduces new POWERCONTEXT_PYDANTIC_AI_* configuration variables. The token setting expects a raw token; users should not include the Bearer prefix.

Capture is opt-in and disabled by default because enabling it may persist prompts, visible model output, tool calls, and tool results. Sensitive values are redacted before capture, but users should still review the associated data-retention risk.

There are no breaking changes to existing public APIs or persisted formats, and no migration is required. Durable execution frameworks such as Temporal, DBOS, and Prefect have not been validated in this initial release.

How was this change tested?

The following validation was completed:

• Adapter unit and end-to-end tests: 25 passed
• Full test suite via make test: 631 passed, 12 skipped
• Bub capture sanitization regression test: 1 passed
• make check
• make docs-test
• uv build --project integrations/pydantic-ai
• tox across Python 3.11, 3.12, 3.13, and 3.14
• Explicit type checking of integrations/pydantic-ai/src
• Manual inspection of the generated wheel metadata and contents, including verification that no entry point is registered

The end-to-end test verifies the complete flow:

1. A tool result is captured.
2. The capture checkpoint is flushed.
3. The next model step recalls the prepared context.
4. A final PowerContext search returns the stored result with its citation.

An initial Python 3.12 tox run encountered an existing readiness-test timeout; both the isolated test and the complete Python 3.12 environment passed on rerun.

AI usage statement

[Copilot]

Pull request overview

Adds a first-class Pydantic AI integration for PowerContext as an independently distributable package under integrations/, aligning PowerContext’s memory/tooling with Pydantic AI’s run lifecycle (context prep, optional capture, flushing) via the public Python client.

Changes:

• Introduces powercontext-pydantic-ai with public APIs (PowerContext, PowerContextToolset, PowerContextSettings), memory tools, deterministic scope resolution, and per-run client lifecycle.
• Adds optional bounded, redacted trajectory capture + checkpoint/final flushing, and factors shared capture rendering/redaction into powercontext.client.capture (reused by Bub).
• Adds adapter unit tests, an e2e chain test, and updates docs/navigation and repo test/type-check import paths for the new integration.

Reviewed changes

Copilot reviewed 23 out of 24 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
zensical.toml	Adds Pydantic AI docs pages into EN/ZH navigation.
pyproject.toml	Updates type-check/test import paths to include the integration source during repo tests.
src/powercontext/client/capture.py	New shared bounded/redacted JSON rendering utilities for capture events.
integrations/pydantic-ai/pyproject.toml	Declares the independently distributable powercontext-pydantic-ai package metadata/deps.
integrations/pydantic-ai/README.md	Provides installation, configuration, and behavior documentation for the adapter package.
integrations/pydantic-ai/src/powercontext_pydantic_ai/init.py	Exposes the adapter’s public API surface.
integrations/pydantic-ai/src/powercontext_pydantic_ai/settings.py	Adds validated settings loading via pydantic-settings env prefix.
integrations/pydantic-ai/src/powercontext_pydantic_ai/scope.py	Implements deterministic scope resolution (constructor/env/git/local hash).
integrations/pydantic-ai/src/powercontext_pydantic_ai/toolset.py	Implements the toolset (search/remember/context) with per-run client management and ModelRetry mapping.
integrations/pydantic-ai/src/powercontext_pydantic_ai/capability.py	Implements automatic context prep, optional capture, and flush hooks in the Pydantic AI capability lifecycle.
integrations/bub/src/powercontext_bub/plugin.py	Switches Bub capture rendering to the shared capture helper.
integrations/bub/pyproject.toml	Bumps Bub integration dependency to powercontext[client]>=0.0.2.
e2e/bub/uv.lock	Updates lockfile to reflect the powercontext[client]>=0.0.2 requirement.
docs/en/docs/reference/interfaces.md	Documents the new Pydantic AI adapter as a supported interface.
docs/zh/docs/reference/interfaces.md	Documents the new Pydantic AI adapter as a supported interface (ZH).
docs/en/docs/how-to/configure-pydantic-ai.md	Adds end-user setup/configuration documentation (EN).
docs/zh/docs/how-to/configure-pydantic-ai.md	Adds end-user setup/configuration documentation (ZH).
tests/pydantic_ai_adapter/init.py	Adds a dedicated test package for the adapter tests.
tests/pydantic_ai_adapter/fakes.py	Adds a recording PowerContext client test double for adapter-boundary assertions.
tests/pydantic_ai_adapter/test_toolset.py	Validates tool schemas/instructions/mapping, retry conversion, and per-run client lifecycle.
tests/pydantic_ai_adapter/test_settings_scope.py	Validates settings/env behavior and scope derivation precedence/bounding.
tests/pydantic_ai_adapter/test_capability.py	Validates per-run context injection rules and fail-open recall behavior.
tests/pydantic_ai_adapter/test_capture.py	Validates capture opt-in, bounding/redaction, checkpoint flushing, and fail-open capture/flush behavior.
tests/e2e/test_pydantic_ai_chain.py	Adds an end-to-end chain test using a real server lifecycle + SQLite to validate capture→flush→recall→search.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.