Builtin tool

.github/workflows/ci.yml

@@ -140,6 +140,7 @@ jobs:
     env:
       UV_PYTHON: ${{ matrix.python-version }}
       CI: true
+      COVERAGE_PROCESS_START: ./pyproject.toml
     steps:
       - uses: actions/checkout@v4
 
@@ -151,20 +152,20 @@ jobs:
         with:
           deno-version: v2.x
 
-      - run: mkdir coverage
+      - run: mkdir .coverage
 
       # run tests with just `pydantic-ai-slim` dependencies
-      - run: uv run --package pydantic-ai-slim coverage run -m pytest
+      - run: uv run --package pydantic-ai-slim coverage run -m pytest -n auto --dist=loadgroup
         env:
-          COVERAGE_FILE: coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-slim
+          COVERAGE_FILE: .coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-slim
 
-      - run: uv run coverage run -m pytest
+      - run: uv run coverage run -m pytest -n auto --dist=loadgroup
         env:
-          COVERAGE_FILE: coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-standard
+          COVERAGE_FILE: .coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-standard
 
-      - run: uv run --all-extras coverage run -m pytest
+      - run: uv run --all-extras coverage run -m pytest -n auto --dist=loadgroup
         env:
-          COVERAGE_FILE: coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-all-extras
+          COVERAGE_FILE: .coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-all-extras
 
       - run: uv run --all-extras python tests/import_examples.py
 
@@ -173,15 +174,15 @@ jobs:
         if: matrix.python-version != '3.9'
         run: |
           unset UV_FROZEN
-          uv run --all-extras --resolution lowest-direct coverage run -m pytest
+          uv run --all-extras --resolution lowest-direct coverage run -m pytest -n auto --dist=loadgroup
         env:
-          COVERAGE_FILE: coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-lowest-versions
+          COVERAGE_FILE: .coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-lowest-versions
 
       - name: store coverage files
         uses: actions/upload-artifact@v4
         with:
           name: coverage-${{ matrix.python-version }}
-          path: coverage
+          path: .coverage
           include-hidden-files: true
 
   coverage:
@@ -197,15 +198,15 @@ jobs:
         uses: actions/download-artifact@v4
         with:
           merge-multiple: true
-          path: coverage
+          path: .coverage
 
       - uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true
 
       - run: uv sync --package pydantic-ai-slim --only-dev
-      - run: rm coverage/.coverage.*-py3.9-* # Exclude 3.9 coverage as it gets the wrong line numbers, causing invalid failures.
-      - run: uv run coverage combine coverage
+      - run: rm .coverage/.coverage.*-py3.9-* # Exclude 3.9 coverage as it gets the wrong line numbers, causing invalid failures.
+      - run: uv run coverage combine
 
       - run: uv run coverage html --show-contexts --title "Pydantic AI coverage for ${{ github.sha }}"
 
@@ -228,7 +229,10 @@ jobs:
 
       - run: uv run coverage report --fail-under 100
       - run: uv run diff-cover coverage.xml --fail-under 100
+
       - run: uv run strict-no-cover
+        env:
+          COVERAGE_FILE: .coverage/.coverage
 
   test-mcp-run-python:
     runs-on: ubuntu-latest

.github/workflows/claude.yml

@@ -0,0 +1,58 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+env:
+  UV_PYTHON: 3.13
+  UV_FROZEN: "1"
+
+jobs:
+  claude-code-action:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - run: uv tool install pre-commit
+
+      - run: make install
+
+      - name: Run Claude PR Action
+        uses: anthropics/claude-code-action@beta
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          timeout_minutes: "60"
+          additional_permissions: |
+            actions: read
+          allowed_tools: |
+            Bash(make:*)
+            Bash(uv:*)

.gitignore

@@ -15,8 +15,8 @@ examples/pydantic_ai_examples/.chat_app_messages.sqlite
 .vscode/
 /question_graph_history.json
 /docs-site/.wrangler/
-/CLAUDE.md
 node_modules/
 **.idea/
 .coverage*
 /test_tmp/
+.mcp.json

CLAUDE.md

@@ -0,0 +1,127 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Core Development Tasks
+- **Install dependencies**: `make install` (requires uv, pre-commit, and deno)
+- **Run all checks**: `make` (format, lint, typecheck, test with coverage)
+- **Format code**: `make format`
+- **Lint code**: `make lint`
+- **Type checking**: `make typecheck` (uses pyright) or `make typecheck-both` (pyright + mypy)
+- **Run tests**: `make test` (with coverage)
+- **Build docs**: `make docs` or `make docs-serve` (local development)
+
+### Single Test Commands
+- **Run specific test**: `uv run pytest tests/test_agent.py::test_function_name -v`
+- **Run test file**: `uv run pytest tests/test_agent.py -v`
+- **Run with debug**: `uv run pytest tests/test_agent.py -v -s`
+
+### Multi-Python Testing
+- **Install all Python versions**: `make install-all-python`
+- **Test all Python versions**: `make test-all-python`
+
+## Project Architecture
+
+### Core Components
+
+**Agent System (`pydantic_ai_slim/pydantic_ai/agent.py`)**
+- `Agent[AgentDepsT, OutputDataT]`: Main orchestrator class with generic types for dependency injection and output validation
+- Entry points: `run()`, `run_sync()`, `run_stream()` methods
+- Handles tool management, system prompts, and model interaction
+
+**Model Integration (`pydantic_ai_slim/pydantic_ai/models/`)**
+- Unified interface across providers: OpenAI, Anthropic, Google, Groq, Cohere, Mistral, Bedrock, HuggingFace
+- Model strings: `"openai:gpt-4o"`, `"anthropic:claude-3-5-sonnet"`, `"google:gemini-1.5-pro"`
+- `ModelRequestParameters` for configuration, `StreamedResponse` for streaming
+
+**Graph-based Execution (`pydantic_graph/` + `_agent_graph.py`)**
+- State machine execution through: `UserPromptNode` → `ModelRequestNode` → `CallToolsNode`
+- `GraphAgentState` maintains message history and usage tracking
+- `GraphRunContext` provides execution context
+
+**Tool System (`tools.py`, `toolsets/`)**
+- `@agent.tool` decorator for function registration
+- `RunContext[AgentDepsT]` provides dependency injection in tools
+- Support for sync/async functions with automatic schema generation
+
+**Output Handling**
+- `TextOutput`: Plain text responses
+- `ToolOutput`: Structured data via tool calls
+- `NativeOutput`: Provider-specific structured output
+- `PromptedOutput`: Prompt-based structured extraction
+
+### Key Design Patterns
+
+**Dependency Injection**
+```python
+@dataclass
+class MyDeps:
+    database: DatabaseConn
+
+agent = Agent('openai:gpt-4o', deps_type=MyDeps)
+
+@agent.tool
+async def get_data(ctx: RunContext[MyDeps]) -> str:
+    return await ctx.deps.database.fetch_data()
+```
+
+**Type-Safe Agents**
+```python
+class OutputModel(BaseModel):
+    result: str
+    confidence: float
+
+agent: Agent[MyDeps, OutputModel] = Agent(
+    'openai:gpt-4o',
+    deps_type=MyDeps,
+    output_type=OutputModel
+)
+```
+
+## Workspace Structure
+
+This is a uv workspace with multiple packages:
+- **`pydantic_ai_slim/`**: Core framework (minimal dependencies)
+- **`pydantic_evals/`**: Evaluation system
+- **`pydantic_graph/`**: Graph execution engine
+- **`examples/`**: Example applications
+- **`clai/`**: CLI tool
+- **`mcp-run-python/`**: MCP server implementation (Deno/TypeScript)
+
+## Testing Strategy
+
+- **Unit tests**: `tests/` directory with comprehensive model and component coverage
+- **VCR cassettes**: `tests/cassettes/` for recorded LLM API interactions
+- **Test models**: Use `TestModel` for deterministic testing
+- **Examples testing**: `tests/test_examples.py` validates all documentation examples
+- **Multi-version testing**: Python 3.9-3.13 support
+
+## Key Configuration Files
+
+- **`pyproject.toml`**: Main workspace configuration with dependency groups
+- **`pydantic_ai_slim/pyproject.toml`**: Core package with model optional dependencies
+- **`Makefile`**: Development task automation
+- **`uv.lock`**: Locked dependencies for reproducible builds
+
+## Important Implementation Notes
+
+- **Model Provider Integration**: Each provider in `models/` directory implements the `Model` abstract base class
+- **Message System**: Vendor-agnostic message format in `messages.py` with rich content type support
+- **Streaming Architecture**: Real-time response processing with validation during streaming
+- **Error Handling**: Specific exception types with retry mechanisms at multiple levels
+- **OpenTelemetry Integration**: Built-in observability support
+
+## Documentation Development
+
+- **Local docs**: `make docs-serve` (serves at http://localhost:8000)
+- **Docs source**: `docs/` directory (MkDocs with Material theme)
+- **API reference**: Auto-generated from docstrings using mkdocstrings
+
+## Dependencies Management
+
+- **Package manager**: uv (fast Python package manager)
+- **Lock file**: `uv.lock` (commit this file)
+- **Sync command**: `make sync` to update dependencies
+- **Optional extras**: Define groups in `pyproject.toml` optional-dependencies

Makefile

@@ -60,13 +60,10 @@ typecheck-both: typecheck-pyright typecheck-mypy
 
 .PHONY: test
 test: ## Run tests and collect coverage data
-	uv run coverage run -m pytest
+	COVERAGE_PROCESS_START=./pyproject.toml uv run coverage run -m pytest -n auto --dist=loadgroup
+	@uv run coverage combine
 	@uv run coverage report
 
-.PHONY: test-fast
-test-fast: ## Same as test except no coverage and 4x faster depending on hardware
-	uv run pytest -n auto --dist=loadgroup
-
 .PHONY: test-all-python
 test-all-python: ## Run tests on Python 3.9 to 3.13
 	UV_PROJECT_ENVIRONMENT=.venv39 uv run --python 3.9 --all-extras --all-packages coverage run -p -m pytest