Add a Pydantic-AI toolset bridge so ChainWeaver flows register as Pydantic-AI tools

[dgenio]

Summary

Add an optional integration module (mirroring the existing LangChain/LlamaIndex bridges) that wraps registered ChainWeaver flows as a Pydantic-AI toolset, so Pydantic-AI agents can call governed, compiled flows as ordinary tools.

Why this matters

Pydantic-AI shares ChainWeaver's foundation (Pydantic v2, typed schemas) and has an explicit toolset abstraction for wrapping external tools, making it a natural, low-friction integration. ChainWeaver currently ships bridges for LangChain, LlamaIndex, LangGraph, and OpenAI Agents; adding Pydantic-AI broadens ecosystem reach to a fast-growing, type-first audience with minimal impedance mismatch.

Current evidence

• chainweaver/integrations/ contains langchain.py, llamaindex.py, plus LangGraph/OpenAI-Agents recipes (per pyproject.toml extras langgraph, openai-agents) — no pydantic_ai.py.
• pyproject.toml already models per-framework optional extras with offline-by-default recipes, so the pattern and packaging convention exist.
• Open issue distribution: get ChainWeaver listed in LangGraph & OpenAI Agents SDK ecosystem/integration directories #231 targets ecosystem directory listings and First-class OpenAI Agents SDK integration (#315) #321 first-class OpenAI Agents integration — this is a distinct framework not covered by either.

External context

Pydantic-AI exposes an AbstractToolset / toolset model for wrapping external tools; both libraries build on Pydantic v2, so schema translation is direct.

Proposed implementation

1. Add chainweaver/integrations/pydantic_ai.py exposing a function/class that turns a FlowExecutor + flow name (or a whole registry) into Pydantic-AI tool(s), translating input/output schemas.
2. Add a pydantic-ai optional extra in pyproject.toml with a lower-bound-only specifier (per the dependency-constraint policy), and a lazy import guard.
3. Add a runnable, offline example (examples/integrations/) and a cookbook page mirroring the LangGraph/OpenAI recipes.
4. Decide async handling: MCP-adapted async flows must route through execute_flow_async — document the sync/async tool variants.

AI-agent execution notes

Inspect chainweaver/integrations/langchain.py and llamaindex.py for the established adapter shape, chainweaver/export/_schema.py for schema translation helpers, pyproject.toml extras, docs/cookbook/. Keep the import lazy and the recipe offline (no API key). Preserve the rule that integrations are optional extras never imported by core. Add tests under tests/ guarded by an import skip when the extra is absent.

Acceptance criteria

• A flow can be registered as a Pydantic-AI tool and invoked, producing the flow's validated output.
• The integration imports lazily and is absent-tolerant when the extra is not installed.
• A runnable offline example and cookbook page exist.

Test plan

Skip-if-missing integration tests (sync and async flow), schema-translation unit test, example smoke test in the notebook/integration CI lane.

Documentation plan

New cookbook page, README ## Integrations table, pyproject.toml extras comment, CHANGELOG.

Migration and compatibility notes

Not expected to require migration (new optional module + extra).

Risks and tradeoffs

Another framework dependency to track against Pydantic-version drift (mitigated by lower-bound-only specifier and the existing floor-deps CI lane). Pydantic-AI APIs are evolving — pin a tested floor and document the supported range.

Suggested labels

integrations, ecosystem, developer-experience