Status (updated 2026-05-28)
Decision: pivot to pydantic-ai-only. chinchill-api is our only consumer of chat/ai and uses pydantic-ai exclusively. This collapses the original 3-SDK shared-core design into a single pydantic-ai-native implementation.
Revised design
Pydantic is a hard dep of pydantic-ai, so we can use Pydantic models directly instead of hand-rolling JSON Schema dicts — simpler code, native pydantic-ai integration, less drift risk.
chat_sdk/ai/messages.py — existing to_ai_messages (moved from ai.py)chat_sdk/ai/tools.py — 17 tool factories as async callables. Each takes a Chat and returns a pydantic-ai Tool (or our own thin wrapper that produces one). Input schemas as Pydantic v2 models.chat_sdk/ai/orchestrator.py — create_chat_tools(chat, preset=None, require_approval=True, overrides=None). Presets (reader / messenger / moderator), per-tool overrides with whitelist.chat_sdk/ai/__init__.py — re-exports to_ai_messages, create_chat_tools, individual tool factories. Deprecation shim at old chat_sdk.ai import path.- Optional extra:
chat-sdk-python[ai] adds pydantic-ai>=0.0.X. Lazy-import inside the module.
Dropped from original design: bespoke Anthropic + OpenAI adapter modules (~120 LOC + 250 LOC tests + the cross-SDK schema-shape parity test). pydantic-ai itself handles routing to Anthropic / OpenAI / Bedrock / etc. via its model layer.
Revised effort estimate (3 PRs, ~5 days)
| PR |
Scope |
LOC src / test |
Days |
| 1 |
Move ai.py → ai/messages.py; chat_sdk/ai/__init__.py re-exports with deprecation shims |
~100 / ~50 |
0.5 |
| 2 |
Core: ai/tools.py (17 factories with Pydantic input schemas), ai/types.py, ai/orchestrator.py (presets, override whitelist) |
~600 / ~700 |
3.5 |
| 3 |
Docs + 1 example script (chinchill-api-style usage with pydantic-ai) |
— |
1 |
Open questions (resolved)
-
Anthropic-first vs OpenAI-first vs both → pydantic-ai only.
-
JSON Schema dicts vs Pydantic → Pydantic v2 (already a transitive dep via pydantic-ai).
-
Approval flow contract. Still open. pydantic-ai's Tool doesn't have a native "needs approval" concept. Options:
- (a) Expose
needs_approval as Tool.metadata["needs_approval"]; caller intercepts.
- (b) Wrap
execute in a HumanApprovalWrapper that raises ApprovalRequired when not approved.
- (c) Integrate with chinchill-api's tool runner directly (out of scope for this lib).
Recommend (a): simplest, no behavior change for callers who ignore approval, callers who care can read the metadata. Matches upstream's "needs_approval is just a flag" semantics. Defer (b) / (c) until a concrete consumer asks.
Implementation order
PR 1 first (uncontroversial path setup with deprecation shim). PR 2 is the meat. PR 3 docs to confirm the API shape against a real pydantic-ai integration before merging.
References
Status (updated 2026-05-28)
Decision: pivot to pydantic-ai-only. chinchill-api is our only consumer of
chat/aiand uses pydantic-ai exclusively. This collapses the original 3-SDK shared-core design into a single pydantic-ai-native implementation.Revised design
Pydantic is a hard dep of pydantic-ai, so we can use Pydantic models directly instead of hand-rolling JSON Schema dicts — simpler code, native pydantic-ai integration, less drift risk.
chat_sdk/ai/messages.py— existingto_ai_messages(moved fromai.py)chat_sdk/ai/tools.py— 17 tool factories as async callables. Each takes aChatand returns a pydantic-aiTool(or our own thin wrapper that produces one). Input schemas as Pydantic v2 models.chat_sdk/ai/orchestrator.py—create_chat_tools(chat, preset=None, require_approval=True, overrides=None). Presets (reader/messenger/moderator), per-tool overrides with whitelist.chat_sdk/ai/__init__.py— re-exportsto_ai_messages,create_chat_tools, individual tool factories. Deprecation shim at oldchat_sdk.aiimport path.chat-sdk-python[ai]addspydantic-ai>=0.0.X. Lazy-import inside the module.Dropped from original design: bespoke Anthropic + OpenAI adapter modules (~120 LOC + 250 LOC tests + the cross-SDK schema-shape parity test). pydantic-ai itself handles routing to Anthropic / OpenAI / Bedrock / etc. via its model layer.
Revised effort estimate (3 PRs, ~5 days)
ai.py→ai/messages.py;chat_sdk/ai/__init__.pyre-exports with deprecation shimsai/tools.py(17 factories with Pydantic input schemas),ai/types.py,ai/orchestrator.py(presets, override whitelist)Open questions (resolved)
Anthropic-first vs OpenAI-first vs both→ pydantic-ai only.JSON Schema dicts vs Pydantic→ Pydantic v2 (already a transitive dep via pydantic-ai).Approval flow contract. Still open. pydantic-ai's
Tooldoesn't have a native "needs approval" concept. Options:needs_approvalasTool.metadata["needs_approval"]; caller intercepts.executein aHumanApprovalWrapperthat raisesApprovalRequiredwhennot approved.Recommend (a): simplest, no behavior change for callers who ignore approval, callers who care can read the metadata. Matches upstream's "needs_approval is just a flag" semantics. Defer (b) / (c) until a concrete consumer asks.
Implementation order
PR 1 first (uncontroversial path setup with deprecation shim). PR 2 is the meat. PR 3 docs to confirm the API shape against a real pydantic-ai integration before merging.
References
packages/chat/src/ai/(inchat@4.29.0)to_ai_messages:src/chat_sdk/ai.py+tests/test_ai.py