reflectionai
diff --git a/‎.claude/settings.json‎
Lines changed: 26 additions & 0 deletions b/‎.claude/settings.json‎
Lines changed: 26 additions & 0 deletions
diff --git a/‎.github/ISSUE_TEMPLATE/config.yaml‎
Lines changed: 1 addition & 1 deletion b/‎.github/ISSUE_TEMPLATE/config.yaml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.github/workflows/ci.yml‎
Lines changed: 87 additions & 50 deletions b/‎.github/workflows/ci.yml‎
Lines changed: 87 additions & 50 deletions
diff --git a/‎.gitignore‎
Lines changed: 1 addition & 0 deletions b/‎.gitignore‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎.hyperlint/config.yaml‎
Lines changed: 0 additions & 3 deletions b/‎.hyperlint/config.yaml‎
Lines changed: 0 additions & 3 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 45 additions & 10 deletions b/‎CLAUDE.md‎
Lines changed: 45 additions & 10 deletions
diff --git a/‎Makefile‎
Lines changed: 2 additions & 5 deletions b/‎Makefile‎
Lines changed: 2 additions & 5 deletions
@@ -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": []
+  }
+}
@@ -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'
 
@@ -71,8 +71,9 @@ jobs:
         # always build docs to check it works without insiders packages
       - run: make docs
 
-      - run: make docs-insiders
-        if: github.event.pull_request.head.repo.full_name == github.repository || github.ref == 'refs/heads/main'
+      - name: Build docs with insiders packages
+        run: make docs-insiders
+        if: (github.event.pull_request.head.repo.full_name == github.repository || github.ref == 'refs/heads/main') && env.PPPR_TOKEN != ''
         env:
           PPPR_TOKEN: ${{ secrets.PPPR_TOKEN }}
 
@@ -107,6 +108,7 @@ jobs:
         with:
           model: qwen2:0.5b
 
+      - run: uv sync --only-dev
       - run: >
           uv run
           --package pydantic-ai-slim
@@ -130,16 +132,24 @@ 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
+      COVERAGE_PROCESS_START: ./pyproject.toml
     steps:
       - uses: actions/checkout@v4
 
@@ -151,42 +161,88 @@ 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 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
-        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
-        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
+      - 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 }}
-          path: coverage
+          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:
@@ -197,38 +253,19 @@ 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: uv sync --group dev
+      - run: uv run coverage combine
+      - run: uv run coverage report
 
-      - 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 strict-no-cover
+        env:
+          COVERAGE_FILE: .coverage/.coverage
 
   test-mcp-run-python:
     runs-on: ubuntu-latest
@@ -256,7 +293,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:
 
@@ -19,3 +19,4 @@ node_modules/
 **.idea/
 .coverage*
 /test_tmp/
+.mcp.json
@@ -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) or `make test-fast` (parallel, no 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`.
@@ -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
+	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
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-blank_issues_enabled: true`
	`1`	`+blank_issues_enabled: false`
`2`	`2`	`contact_links:`
`3`	`3`	`- name: 💬 Join Slack`
`4`	`4`	`url: 'https://logfire.pydantic.dev/docs/help/#slack'`