# grksharma/pydantic-ai architecture

> Architecture diagram of the GitHub repository grksharma/pydantic-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grksharma/pydantic-ai
- Repository: https://github.com/grksharma/pydantic-ai

## Overview

##### Project Type and Purpose
- This is a monorepo for an open-source Python agent framework (“PydanticAI”) plus related tools and plugins.
- Its core purpose is to provide a type-safe, Pydantic-driven interface for building LLM-powered agents, with CLI utilities, evaluation tools, graph support, sample apps, documentation, and CI/CD.

##### High-Level File-Structure Analysis
- Top-level “packages”:
- clai – CLI tool
- pydantic_ai_slim – core agent library (slim build)
- pydantic_evals – evaluation framework plugin
- pydantic_graph – graph-building plugin
- fasta2a – separate agent for FASTA processing
- mcp-run-python – Deno-based microserver for executing Python code
- Documentation:
- docs/ – markdown source for API/reference/site
- docs-site/ – frontend code (TypeScript, wrangler.toml) for the live docs site
- Examples: examples/ and tests/ demonstrate usage and validate behavior.
- CI/CD: .github/workflows (ci, deploy docs, stale), Makefile, pre-commit, mkdocs.yml.

##### Relationships and Data Flows
- Developer → clai or import Agent → core library
- Agent constructs prompts & tools → provider modules → external LLM APIs → returns streamed/text responses
- Core library validates with Pydantic → structured output → optional plugin flows:
- → pydantic_graph to build or persist graphs
- → pydantic_evals to evaluate and report results (OTEL traces → reports)
- Tools may call mcp-run-python service (e.g., runCode.ts in Deno)
- Telemetry & logging via Pydantic Logfire → external dashboard/service

##### Architectural Patterns & Principles
- Plugin architecture: core agent ↔ plugins (graph, evals)
- Dependency injection: type-safe injection of services/tools into prompts
- Modular provider pattern: separate modules per LLM provider, unified Agent interface
- Streaming & retry loops: built-in control flow for tool calls and streaming outputs
- Monorepo polyglot: Python packages + Deno/TypeScript microservice + static site

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Interfaces
    subgraph "Developer Interfaces"
        Developer["Developer"]
        CLI["CLI: clai/__main__.py"]:::core
        PythonAPI["Python API: import pydantic_ai_slim"]:::core
        Examples["Examples/Scripts"]:::core
    end

    %% Core Library
    subgraph "Core Library (pydantic_ai_slim)" 
        direction TB
        Agent["Agent (agent.py)"]:::core
        RunContext["RunContext (_run_context.py)"]:::core
        DI["Dependency Injection (_parts_manager.py)"]:::core
        Tools["Tool Registration & Execution (tools.py, _mcp.py)"]:::core
        OutputVal["Structured Output Validation (_output.py, output.py)"]:::core
        Thinking["Streaming & Thinking (_thinking_part.py)"]:::core
        Extensions["Extensions (ext/)"]:::core
        CommonTools["Common Tools (common_tools/)"]:::core
        Providers["Provider Modules (providers/)"]:::core
        Models["Model Schemas (models/)"]:::core
    end

    %% Plugins
    subgraph "Plugin Modules"
        direction TB
        Eval["Evaluation Plugin (pydantic_evals/)"]:::plugin
        Dataset["Dataset API (dataset.py)"]:::plugin
        Evaluators["Evaluators (evaluators/)"]:::plugin
        OTEL["OTEL Tracing (otel/)"]:::plugin
        Reporting["Reporting (reporting/)"]:::plugin
        Graph["Graph Plugin (pydantic_graph/)"]:::plugin
        GraphDef["Graph Definitions (graph.py)"]:::plugin
        Nodes["Graph Nodes (nodes.py)"]:::plugin
        MermaidExp["Mermaid Export (mermaid.py)"]:::plugin
        Persistence["Persistence (persistence/)"]:::plugin
    end

    %% Auxiliary Services
    subgraph "Auxiliary Services"
        direction TB
        LLM["External LLM Providers"]:::external
        Logfire["Pydantic Logfire (Telemetry)"]:::external
        Microserver["mcp-run-python Service"]:::external
        ServerEntry["main.ts"]:::external
        RunCode["runCode.ts"]:::external
    end

    %% Documentation & CI/CD
    subgraph "Documentation & CI/CD"
        direction TB
        Docs["Markdown Docs (docs/)"]:::ops
        LiveSite["Live Docs Site (docs-site/)"]:::ops
        CI["GitHub Workflows (.github/workflows/)"]:::ops
        MkDocs["MkDocs Config (mkdocs.yml)"]:::ops
        MakefileNode["Makefile"]:::ops
    end

    %% Relations
    Developer -->|uses| CLI
    Developer -->|imports| PythonAPI
    Developer -->|views| Examples

    CLI -->|invokes| Agent
    PythonAPI -->|calls| Agent
    Examples -->|demo| Agent

    Agent -->|constructs prompts| Providers
    Agent -->|injects dependencies| DI
    DI -->|provides parts| Agent
    Agent -->|calls tools| Tools
    Tools -->|may call| Microserver
    Microserver -->|executes code| RunCode
    Microserver -->|entrypoint| ServerEntry
    Agent -->|validates output| OutputVal
    Agent -->|streams| Thinking

    Agent -->|hooks into| Eval
    Eval -->|uses| Dataset
    Eval -->|runs| Evaluators
    Evaluators -->|traces| OTEL
    OTEL -->|reports| Reporting

    Agent -->|hooks into| Graph
    Graph -->|defines| GraphDef
    GraphDef -->|creates| Nodes
    Graph -->|exports| MermaidExp
    Graph -->|persists| Persistence

    Providers -->|API calls| LLM
    Agent -->|sends telemetry| Logfire

    Docs -->|source for| LiveSite
    LiveSite -->|deployed via| CI
    CI -->|uses| MkDocs
    CI -->|runs| MakefileNode

    %% Click Events
    click CLI "https://github.com/grksharma/pydantic-ai/blob/main/clai/clai/__main__.py"
    click Agent "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/agent.py"
    click RunContext "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_run_context.py"
    click DI "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_parts_manager.py"
    click Tools "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/tools.py"
    click Tools "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_mcp.py"
    click OutputVal "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_output.py"
    click OutputVal "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/output.py"
    click Thinking "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/_thinking_part.py"
    click Extensions "https://github.com/grksharma/pydantic-ai/tree/main/pydantic_ai_slim/pydantic_ai/ext/"
    click CommonTools "https://github.com/grksharma/pydantic-ai/tree/main/pydantic_ai_slim/pydantic_ai/common_tools/"
    click Providers "https://github.com/grksharma/pydantic-ai/tree/main/pydantic_ai_slim/pydantic_ai/providers/"
    click Models "https://github.com/grksharma/pydantic-ai/tree/main/pydantic_ai_slim/pydantic_ai/models/"
    click Eval "https://github.com/grksharma/pydantic-ai/tree/main/pydantic_evals/pydantic_evals/"
    click Dataset "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_evals/pydantic_evals/dataset.py"
    click Evaluators "https://github.com/grksharma/pydantic-ai/tree/main/pydantic_evals/pydantic_evals/evaluators/"
    click OTEL "https://github.com/grksharma/pydantic-ai/tree/main/pydantic_evals/pydantic_evals/otel/"
    click Reporting "https://github.com/grksharma/pydantic-ai/tree/main/pydantic_evals/pydantic_evals/reporting/"
    click Graph "https://github.com/grksharma/pydantic-ai/tree/main/pydantic_graph/pydantic_graph/"
    click GraphDef "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_graph/pydantic_graph/graph.py"
    click Nodes "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_graph/pydantic_graph/nodes.py"
    click MermaidExp "https://github.com/grksharma/pydantic-ai/blob/main/pydantic_graph/pydantic_graph/mermaid.py"
    click Persistence "https://github.com/grksharma/pydantic-ai/tree/main/pydantic_graph/pydantic_graph/persistence/"
    click Microserver "https://github.com/grksharma/pydantic-ai/tree/main/mcp-run-python/src/"
    click ServerEntry "https://github.com/grksharma/pydantic-ai/blob/main/mcp-run-python/src/main.ts"
    click RunCode "https://github.com/grksharma/pydantic-ai/blob/main/mcp-run-python/src/runCode.ts"
    click Docs "https://github.com/grksharma/pydantic-ai/tree/main/docs/"
    click LiveSite "https://github.com/grksharma/pydantic-ai/tree/main/docs-site/"
    click CI "https://github.com/grksharma/pydantic-ai/tree/main/ .github/workflows/"
    click MakefileNode "https://github.com/grksharma/pydantic-ai/tree/main/Makefile"
    click MkDocs "https://github.com/grksharma/pydantic-ai/blob/main/mkdocs.yml"

    %% Styles
    classDef core fill:#E3F2FD,stroke:#2196F3,stroke-width:2px
    classDef plugin fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px
    classDef external fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px
    classDef ops fill:#ECEFF1,stroke:#607D8B,stroke-width:2px
```
