pydantic / pydantic-ai · Architecture

The analyzer's summary counts 4,082 analyzed files, and GitHub metadata records Python as the primary language. Recorded top-level directory sizes: tests 2,501, src 498, pydantic_ai_slim 426, docs 351, .github 136, examples 63, pydantic_evals 33, pydantic_graph 18, scripts 10, clai 6, agent_docs 6, .agents 7, .claude 12. The analyzer treats docs, src and tests as subsystem candidates; its maturity signals also count 2,514 test-like files, so test code dominates the inventory. Dependency records reference pyproject.toml manifests at the repository root and inside pydantic_evals and pydantic_graph, so at least those packages declare their own dependencies. README.md, pyproject.toml and LICENSE are flagged as project-level important files. The GitHub description describes agents, realtime voice, image generation and embeddings with end-to-end typing; the packet marks that author-claimed, and it is orientation, not analyzer evidence.

The reconstruction reports 65 entrypoints and 580 bounded execution paths. Verified __main__ guards are spread widely: CI and maintenance scripts (.github/scripts/agent_provider_health.py, .github/scripts/agent_spend_report.py, scripts/check_cassettes.py), package __main__ modules (pydantic_ai_slim/pydantic_ai/__main__.py calling cli_exit(), clai/clai/__main__.py calling _cli.cli_exit('clai'), src/pydantic_clai2/pydantic_clai2/__main__.py), and an examples runner (examples/pydantic_ai_examples/__main__.py calling cli()). Three further entrypoints — .github/scripts/pydantic_ai_gh_aw_shim/cli.py, examples/pydantic_ai_examples/slack_lead_qualifier/app.py and pydantic_ai_slim/pydantic_ai/ui/_web/app.py — rest only on a filename heuristic. The analyzer's summary names .claude/skills/testing-skill/parse_cassette.py the main starting place; that is an inference tied to this skill script, not evidence that the library packages start there. Of the 580 paths, the ten itemized ones all begin at that script's __main__ guard: module level calls main, main builds an argparse parser, checks args.cassette.exists and calls parse_cassette, which reaches Cassette and cassette.load. Each of the ten ends at an unresolved external target (argparse calls, print, sys.exit, Cassette, cassette.load) with terminal reason 'unresolved_boundary'; none is truncated and none shows a cycle.

Each role record states its evidence basis as static resolved cross-module call degree and entrypoint membership — these roles are inferences from call counts, not runtime observations. Highest incoming degree: tests/clai2/menu_script.py (569 incoming, 0 outgoing; leaf/data-boundary candidate), pydantic_ai/exceptions.py (421 in, 0 out; leaf candidate) and pydantic_ai/messages.py (403 in, 70 out; service/core candidate); tests/_inline_snapshot.py (357 in) and pydantic_ai/_utils.py (253 in, 6 out) are also reached often. pydantic_ai/agent/__init__.py is the mirror image: 4 incoming, 203 outgoing — a hub calling outward — with models/openai.py (8 in, 151 out), models/google.py (8 in, 78 out), models/__init__.py (113 in, 52 out) and _agent_graph.py (24 in, 100 out) nearby. Seven records with 0 incoming and high outgoing are labeled orchestration candidates: tests/durable_exec/test_dbos.py (148 out), tests/durable_exec/test_prefect.py (88), pydantic_ai/realtime/_session.py (128 out), pydantic_ai/models/anthropic.py (105 out), pydantic_ai/durable_exec/_base.py (92 out), pydantic_ai/ui/vercel_ai/_adapter.py (92 out) and pydantic_ai/realtime/openai_live.py (75 out).

Static control stops at the analyzer's resolution limit, and the packet quantifies it: of 150,000 recorded relations, 125,702 are external_or_unresolved and 24,298 local (124,623 calls, 25,377 imports). The ten itemized paths show the pattern: each terminates with reason 'unresolved_boundary' at a non-local target — argparse construction and parsing, args.cassette.exists, print, sys.exit, Cassette, cassette.load. The analyzer documents that reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring and dynamic dispatch are not resolved, so plugin-style or dispatched calls would appear as unresolved targets rather than local edges. The absence of local edges into such code is therefore not evidence that the code does not exist.

Manifest records provide the cross-part facts in this packet. pydantic_graph's pyproject.toml records runtime dependencies on anyio, logfire-api, pydantic and typing-inspection; pydantic_evals' manifest records logfire as optional. The root pyproject.toml's dev records span a large toolchain — pytest, pytest-mock, pytest-xdist, coverage, mypy, pyright and ruff — plus packages such as redis, azure-identity, boto3-stubs, fastmcp and mcp-types. All 45 dependency records in the packet come from pyproject.toml manifests, with version constraints recorded as written; setup.py, setup.cfg, Pipfile and lock files are not parsed. On resolved code relations, the packet supports only a bounded statement: with 125,702 external/unresolved versus 24,298 local edges, and dynamic wiring out of scope, a complete map of which parts depend on which is not established. What the packet does show locally is the call-degree structure summarized above.

The analyzer documents what it cannot see. Static analysis does not resolve reflection, runtime dependency injection, dynamic imports, monkey-patching, generated code, framework runtime wiring or dynamic dispatch, so runtime wiring between packages is out of view. Install/run/build inference is partial and installation commands are not verified, so this asset states no run instructions. Bounded analysis inventories but does not parse files over 400 kB, minified bundles and vendored directories, and caps relation extraction at 2,500 per file and 150,000 per repository; the repository cap was reached (with 0 per-file truncations), and five files were inventoried but not parsed. README-derived text remains author_claimed at best, since extraction is line-based. Three entrypoint paths have no statically detected call steps.

A workable order from the packet: first README.md, pyproject.toml and LICENSE, all flagged as project-level important files; the analyzer's learning-path claim also recommends starting with manifests and important symbols, then tracing the bounded execution path and inspecting unresolved boundaries. Second, walk the package trees — pydantic_ai_slim (426 files), pydantic_evals (33), pydantic_graph (18) and src (498) — and, inside the main package, begin at the call-degree hotspots: agent/__init__.py, messages.py and models/__init__.py. Third, see how examples launch via examples/pydantic_ai_examples/__main__.py. Finally, follow one recorded path end to end, noting each unresolved boundary, before changing code.