Migrating Pi To Pydantic AI

Migrate Pi to Pydantic AI

Preserve observable behavior, not Pi's TypeScript API. Migrate the smallest complete caller path and keep product/host infrastructure in the application.

Trace the source before choosing a target

1. Read repository instructions, package.json, Pi settings, tests, extension/package manifests, and runtime entrypoints. Record the installed Pi, Pydantic AI, and Harness versions.
2. Trace one real request from the Pi CLI, RPC boundary, or createAgentSession().prompt() through resource discovery, system instructions, tools, extensions, model requests, messages, compaction/retry, events, session entries, UI/RPC output, and side effects. Establish a focused baseline or characterization test.
3. Inventory every active extension factory and package resource. For each pi.on(...), registerTool, registerCommand, provider registration, renderer/UI contribution, skill, prompt, and persisted entry, record its firing point, trusted inputs, mutations, output, state owner, and caller-visible effect.
4. Separate these contracts when present:
   • model messages, append-only session entries/tree branches, compaction summaries, and extension state;
   • model-chosen tool input, trusted host context, project trust, approval, authorization, and OS isolation;
   • token deltas, tool lifecycle, Pi extension events, capability events, RPC events, and terminal rendering;
   • agent-loop behavior, CLI/TUI host behavior, provider transport, package distribution, and external side effects.
5. Record each observed contract, its owner, semantic difference, and executable proof. An installed but inactive Pi package feature is not migration scope.

Read Research and concept mapping for the detected features. Read Verification and cutover before implementation.

Treat extensions as capability candidates

A Pi extension is the closest source concept to a Pydantic AI capability, but it is broader. An extension can combine agent behavior with terminal UI, commands, provider registration, resource discovery, and host lifecycle. Port responsibilities, not the extension file:

1. Map reusable model-facing behavior—tools, instructions, model settings, history/event processing, guardrails, and agent-loop hooks—to an existing Core or Harness capability when its lifecycle matches.
2. Bundle related instructions and tools in core Capability; subclass AbstractCapability only for reusable behavior that needs lifecycle hooks, adaptive models/settings, native tools, or typed capability events.
3. Keep CLI commands, flags, keyboard shortcuts, TUI renderers/dialogs, session selection, project trust, package installation, and provider credential setup in the Python application or interface adapter. They are not agent capabilities merely because a Pi extension owns them.
4. Split mixed extensions at that seam. A permission extension may become a ToolGuardrail or approval capability plus an application-owned approver UI; a coding package may become Coder plus host configuration; a provider extension remains a model/provider integration.
5. Preserve order only where evidence shows it matters. Pi handler load order and Pydantic AI capability/hook ordering are different contracts.

Choose the smallest target

• Core: use pydantic_ai.Agent for the agent loop, typed dependencies, tools/toolsets, outputs, normalized messages, capabilities/hooks, streaming, approvals, usage limits, instrumentation, MCP, and provider/model integration.
• Harness: use Coder for Pi's ordinary coding tools only when its exact composition fits. Add focused capabilities such as FileSystem, Shell, Skills, Planning, SubAgents, guardrails, compaction, tool-output limits, or step persistence only for observed behavior.
• Application/interface: retain or replace CLI/TUI/RPC, auth, project trust, settings, provider login/catalogs, session browsing, package management, deployment, and transport deliberately.
• Graph: use plain async Python or pydantic_graph for deterministic workflows; do not encode them in prompts or subagents.
• Gap: name behavior with no supported public seam, explain its impact, and test a bounded adapter. Do not clone Pi's extension bus or JSONL format just to claim parity.

The normal embedded migration is one reusable Agent, Coder or a smaller capability composition, application services in typed dependencies, an application-owned message/session store, and a thin adapter at the existing RPC or UI boundary.