Merge main

Author: dmontagu

.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(rg:*)",
+      "Bash(make:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run:*)",
+      "Bash(git push:*)",
+      "Bash(git checkout:*)",
+      "Bash(gh pr create:*)",
+      "Bash(gh pr view:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(gh pr comment:*)",
+      "Bash(gh pr checks:*)",
+      "Bash(gh run view:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh api:*)",
+      "Bash(pre-commit run:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(coverage:*)"
+    ],
+    "deny": []
+  }
+}

.github/ISSUE_TEMPLATE/config.yaml renamed to .github/ISSUE_TEMPLATE/config.yml

@@ -1,4 +1,4 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
 contact_links:
   - name: 💬 Join Slack
     url: 'https://logfire.pydantic.dev/docs/help/#slack'

.github/workflows/ci.yml

@@ -107,6 +107,7 @@ jobs:
         with:
           model: qwen2:0.5b
 
+      - run: uv sync --only-dev
       - run: >
           uv run
           --package pydantic-ai-slim
@@ -130,13 +131,20 @@ jobs:
           CO_API_KEY: ${{ secrets.COHERE_API_KEY }}
 
   test:
-    name: test on ${{ matrix.python-version }}
+    name: test on ${{ matrix.python-version }} (${{ matrix.install.name }})
     runs-on: ubuntu-latest
     timeout-minutes: 10
     strategy:
       fail-fast: false
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        install:
+          - name: pydantic-ai-slim
+            command: "--package pydantic-ai-slim"
+          - name: standard
+            command: ""
+          - name: all-extras
+            command: "--all-extras"
     env:
       UV_PYTHON: ${{ matrix.python-version }}
       CI: true
@@ -154,40 +162,86 @@ jobs:
 
       - run: mkdir .coverage
 
-      # run tests with just `pydantic-ai-slim` dependencies
-      - run: uv run --package pydantic-ai-slim coverage run -m pytest -n auto --dist=loadgroup
+      - run: uv sync --only-dev
+      - run: uv run ${{ matrix.install.command }} coverage run -m pytest --durations=100 -n auto --dist=loadgroup
         env:
-          COVERAGE_FILE: .coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-slim
+          COVERAGE_FILE: .coverage/.coverage.${{ matrix.python-version }}-${{ matrix.install.name }}
 
-      - run: uv run coverage run -m pytest -n auto --dist=loadgroup
-        env:
-          COVERAGE_FILE: .coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-standard
+      - name: store coverage files
+        uses: actions/upload-artifact@v4
+        if: matrix.python-version != '3.9'
+        with:
+          name: coverage-${{ matrix.python-version }}-${{ matrix.install.name }}
+          path: .coverage
+          include-hidden-files: true
 
-      - 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
+  test-lowest-versions:
+    name: test on ${{ matrix.python-version }} (lowest-versions)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+      CI: true
+      COVERAGE_PROCESS_START: ./pyproject.toml
+    steps:
+      - uses: actions/checkout@v4
 
-      - run: uv run --all-extras python tests/import_examples.py
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
 
-      # this must run last as it modifies the environment!
-      - name: test lowest versions
-        if: matrix.python-version != '3.9'
-        run: |
-          unset UV_FROZEN
-          uv run --all-extras --resolution lowest-direct coverage run -m pytest -n auto --dist=loadgroup
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - run: mkdir .coverage
+
+      - run: uv sync --group dev
+
+      - run: unset UV_FROZEN
+
+      - run: uv run --all-extras --resolution lowest-direct coverage run -m pytest --durations=100 -n auto --dist=loadgroup
         env:
-          COVERAGE_FILE: .coverage/.coverage.${{ runner.os }}-py${{ matrix.python-version }}-lowest-versions
+          COVERAGE_FILE: .coverage/.coverage.${{matrix.python-version}}-lowest-versions
 
       - name: store coverage files
         uses: actions/upload-artifact@v4
         with:
-          name: coverage-${{ matrix.python-version }}
+          name: coverage-${{ matrix.python-version }}-lowest-versions
           path: .coverage
           include-hidden-files: true
 
+  test-examples:
+    name: test examples on ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+      CI: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
+
+      - run: uv run --all-extras python tests/import_examples.py
+
   coverage:
     runs-on: ubuntu-latest
-    needs: [test]
+    needs: [test, test-lowest-versions]
     steps:
       - uses: actions/checkout@v4
         with:
@@ -204,31 +258,9 @@ jobs:
         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 sync --group dev
       - run: uv run coverage combine
-
-      - run: uv run coverage html --show-contexts --title "Pydantic AI coverage for ${{ github.sha }}"
-
-      - name: Store coverage html
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-html
-          path: htmlcov
-          include-hidden-files: true
-
-      - run: uv run coverage xml
-
-      - run: uv run diff-cover coverage.xml --html-report index.html
-
-      - name: Store diff coverage html
-        uses: actions/upload-artifact@v4
-        with:
-          name: diff-coverage-html
-          path: index.html
-
-      - run: uv run coverage report --fail-under 100
-      - run: uv run diff-cover coverage.xml --fail-under 100
+      - run: uv run coverage report
 
       - run: uv run strict-no-cover
         env:
@@ -260,7 +292,7 @@ jobs:
   # https://github.com/marketplace/actions/alls-green#why used for branch protection checks
   check:
     if: always()
-    needs: [lint, mypy, docs, test-live, test, coverage, test-mcp-run-python]
+    needs: [lint, mypy, docs, test-live, test, test-lowest-versions, test-examples, coverage, test-mcp-run-python]
     runs-on: ubuntu-latest
 
     steps:

.gitignore

@@ -19,3 +19,4 @@ node_modules/
 **.idea/
 .coverage*
 /test_tmp/
+.mcp.json

.hyperlint/config.yaml

@@ -5,28 +5,23 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## 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)
+- **Run all checks**: `pre-commit run --all-files`
+- **Run tests**: `make test`
 - **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 System (`pydantic_ai_slim/pydantic_ai/agent/`)**
 - `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
@@ -125,3 +120,43 @@ This is a uv workspace with multiple packages:
 - **Lock file**: `uv.lock` (commit this file)
 - **Sync command**: `make sync` to update dependencies
 - **Optional extras**: Define groups in `pyproject.toml` optional-dependencies
+
+## Best Practices
+
+This is the list of best practices for working with the codebase.
+
+### Rename a class
+
+When asked to rename a class, you need to rename the class in the code and add a deprecation warning to the old class.
+
+```python
+from typing_extensions import deprecated
+
+class NewClass: ...  # This class was renamed from OldClass.
+
+@deprecated("Use `NewClass` instead.")
+class OldClass(NewClass): ...
+```
+
+In the test suite, you MUST use the `NewClass` instead of the `OldClass`, and create a new test to verify the
+deprecation warning:
+
+```python
+def test_old_class_is_deprecated():
+    with pytest.warns(DeprecationWarning, match="Use `NewClass` instead."):
+        OldClass()
+```
+
+In the documentation, you should not have references to the old class, only the new class.
+
+### Writing documentation
+
+Always reference Python objects with the "`" (backticks) around them, and link to the API reference, for example:
+
+```markdown
+The [`Agent`][pydantic_ai.agent.Agent] class is the main entry point for creating and running agents.
+```
+
+### Coverage
+
+Every pull request MUST have 100% coverage. You can check the coverage by running `make test`.

CLAUDE.md

@@ -60,7 +60,7 @@ typecheck-both: typecheck-pyright typecheck-mypy
 
 .PHONY: test
 test: ## Run tests and collect coverage data
-	COVERAGE_PROCESS_START=./pyproject.toml uv run coverage run -m pytest -n auto --dist=loadgroup
+	uv run coverage run -m pytest -n auto --dist=loadgroup
 	@uv run coverage combine
 	@uv run coverage report
 

Makefile

@@ -49,6 +49,7 @@ Either way, running `clai` will start an interactive session where you can chat
 - `/exit`: Exit the session
 - `/markdown`: Show the last response in markdown format
 - `/multiline`: Toggle multiline input mode (use Ctrl+D to submit)
+- `/cp`: Copy the last response to clipboard
 
 ## Help
 
@@ -61,6 +62,7 @@ Special prompts:
 * `/exit` - exit the interactive mode (ctrl-c and ctrl-d also work)
 * `/markdown` - show the last markdown output of the last question
 * `/multiline` - toggle multiline mode
+* `/cp` - copy the last response to clipboard
 
 positional arguments:
   prompt                AI Prompt, if omitted fall into interactive mode

clai/README.md

@@ -35,7 +35,7 @@ There are three ways to run a Pydantic AI agent based on AG-UI run input with st
 
 1. [`run_ag_ui()`][pydantic_ai.ag_ui.run_ag_ui] takes an agent and an AG-UI [`RunAgentInput`](https://docs.ag-ui.com/sdk/python/core/types#runagentinput) object, and returns a stream of AG-UI events encoded as strings. It also takes optional [`Agent.iter()`][pydantic_ai.Agent.iter] arguments including `deps`. Use this if you're using a web framework not based on Starlette (e.g. Django or Flask) or want to modify the input or output some way.
 2. [`handle_ag_ui_request()`][pydantic_ai.ag_ui.handle_ag_ui_request] takes an agent and a Starlette request (e.g. from FastAPI) coming from an AG-UI frontend, and returns a streaming Starlette response of AG-UI events that you can return directly from your endpoint. It also takes optional [`Agent.iter()`][pydantic_ai.Agent.iter] arguments including `deps`, that you can vary for each request (e.g. based on the authenticated user).
-3. [`Agent.to_ag_ui()`][pydantic_ai.Agent.to_ag_ui] returns an ASGI application that handles every AG-UI request by running the agent. It also takes optional [`Agent.iter()`][pydantic_ai.Agent.iter] arguments including `deps`, but these will be the same for each request, with the exception of the AG-UI state that's injected as described under [state management](#state-management). This ASGI app can be [mounted](https://fastapi.tiangolo.com/advanced/sub-applications/) at a given path in an existing FastAPI app.
+3. [`Agent.to_ag_ui()`][pydantic_ai.agent.AbstractAgent.to_ag_ui] returns an ASGI application that handles every AG-UI request by running the agent. It also takes optional [`Agent.iter()`][pydantic_ai.Agent.iter] arguments including `deps`, but these will be the same for each request, with the exception of the AG-UI state that's injected as described under [state management](#state-management). This ASGI app can be [mounted](https://fastapi.tiangolo.com/advanced/sub-applications/) at a given path in an existing FastAPI app.
 
 ### Handle run input and output directly
 
@@ -117,7 +117,7 @@ This will expose the agent as an AG-UI server, and your frontend can start sendi
 
 ### Stand-alone ASGI app
 
-This example uses [`Agent.to_ag_ui()`][pydantic_ai.Agent.to_ag_ui] to turn the agent into a stand-alone ASGI application:
+This example uses [`Agent.to_ag_ui()`][pydantic_ai.agent.AbstractAgent.to_ag_ui] to turn the agent into a stand-alone ASGI application:
 
 ```py {title="agent_to_ag_ui.py" py="3.10" hl_lines="4"}
 from pydantic_ai import Agent
@@ -265,7 +265,7 @@ uvicorn ag_ui_tool_events:app --host 0.0.0.0 --port 9000
 
 ## Examples
 
-For more examples of how to use [`to_ag_ui()`][pydantic_ai.Agent.to_ag_ui] see
+For more examples of how to use [`to_ag_ui()`][pydantic_ai.agent.AbstractAgent.to_ag_ui] see
 [`pydantic_ai_examples.ag_ui`](https://github.com/pydantic/pydantic-ai/tree/main/examples/pydantic_ai_examples/ag_ui),
 which includes a server for use with the
 [AG-UI Dojo](https://docs.ag-ui.com/tutorials/debugging#the-ag-ui-dojo).