chore(nox): centralize dependency pins in pyproject.toml

Migrate all nox session dependency pins and package metadata into
py/pyproject.toml as the single source of truth:

- Replace setup.py with pyproject.toml (setuptools backend)
- Move base test deps, session auxiliary deps, lint deps, build deps,
  and dev deps into PEP 735 dependency groups
- Move provider version matrices into [tool.braintrust.matrix] custom
  table (read by noxfile at import time)
- Generate and commit uv.lock for reproducible auxiliary dep resolution
- Pin all previously-floating 'latest' versions to explicit versions
- Remove requirements-dev.txt, requirements-build.txt,
  requirements-optional.txt, and the install-optional Makefile target
- Switch Makefile and CI from uv pip install to uv sync
- Bump uv to 0.11.6 in .tool-versions
- Add weekly dependency-updates.yml workflow that runs uv lock --upgrade
  and labels PRs based on whether provider SDKs changed
- Exclude uv.lock from codespell checks (false positive on astroid)
- Update AGENTS.md, CONTRIBUTING.md, and agent skill docs to reflect
  the new layout

Author: AbhiPrasad

.agents/skills/sdk-benchmarking/SKILL.md

@@ -24,7 +24,7 @@ Read when relevant:
 
 - `py/benchmarks/benches/bench_bt_json.py` for the module pattern
 - `py/benchmarks/fixtures.py` for shared payload builders
-- `py/setup.py` when benchmarking the optional `orjson` fast path
+- `py/pyproject.toml` when benchmarking the optional `orjson` fast path (see `[project.optional-dependencies]`)
 - `references/benchmark-patterns.md` in this skill for command and module templates
 
 ## Workflow
@@ -56,7 +56,7 @@ If the benchmark should measure the optional `orjson` path, install the performa
 
 ```bash
 cd py
-python -m uv pip install -e '.[performance]'
+uv sync --extra performance
 ```
 
 ## Adding Benchmarks

.agents/skills/sdk-ci-triage/SKILL.md

@@ -192,7 +192,7 @@ The smoke job validates install + import across OS and Python versions.
 Local equivalents:
 
 ```bash
-mise exec python@3.10 -- uv pip install -e ./py[all]
+mise exec python@3.10 -- uv sync --project ./py --all-extras
 mise exec python@3.10 -- uv run --active --no-project python -c 'import braintrust'
 ```
 

.agents/skills/sdk-vcr-workflows/SKILL.md

@@ -14,6 +14,7 @@ This repo prefers real recorded integration coverage over mocks for provider beh
 Always read:
 
 - `AGENTS.md`
+- `py/pyproject.toml` (`[tool.braintrust.matrix]` for provider version pins)
 - `py/noxfile.py`
 - `py/src/braintrust/conftest.py`
 - `py/src/braintrust/integrations/conftest.py` (shared version-aware cassette directory resolution)
@@ -37,7 +38,7 @@ These rules must stay aligned with `AGENTS.md`:
 
 - Work from `py/` for SDK tasks.
 - Use `mise` as the source of truth for tools and environment.
-- Do not guess nox session names or provider/version coverage.
+- Do not guess nox session names or provider/version coverage. Provider version pins (including what "latest" resolves to) are in `py/pyproject.toml` `[tool.braintrust.matrix]`.
 - Default bug-fix workflow is red -> green.
 - Prefer VCR-backed provider tests over mocks or fakes whenever practical.
 - Treat mock/fake tests for provider behavior as an exception that requires justification, not as a neutral alternative.

.github/workflows/checks.yaml

@@ -49,7 +49,7 @@ jobs:
       - name: Run pylint and type tests
         shell: bash
         run: |
-          mise exec python@${{ matrix.python-version }} -- nox -f ./py/noxfile.py -s pylint test_types
+          mise exec python@${{ matrix.python-version }} -- uv run --project ./py nox -f ./py/noxfile.py -s pylint test_types
 
   smoke:
     runs-on: ${{ matrix.os }}
@@ -71,10 +71,10 @@ jobs:
         run: |
           # This is already done by make install-dev, but we're keeping this as a separate step
           # to explicitly verify that installation works
-          mise exec python@${{ matrix.python-version }} -- uv pip install -e ./py[all]
+          mise exec python@${{ matrix.python-version }} -- uv sync --project ./py --all-extras
       - name: Test whether the Python SDK can be imported
         run: |
-          mise exec python@${{ matrix.python-version }} -- uv run --active --no-project python -c 'import braintrust'
+          mise exec python@${{ matrix.python-version }} -- uv run --project ./py python -c 'import braintrust'
 
   nox:
     runs-on: ${{ matrix.os }}

.github/workflows/dependency-updates.yml

@@ -0,0 +1,83 @@
+name: Dependency updates
+on:
+  schedule:
+    - cron: "0 6 * * *" # daily 6am UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up mise
+        uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
+        with:
+          cache: true
+          experimental: true
+
+      - name: Upgrade lockfile
+        working-directory: py
+        run: uv lock --upgrade
+
+      - name: Determine labels
+        id: labels
+        working-directory: py
+        run: |
+          python3 << 'PYEOF' >> "$GITHUB_OUTPUT"
+          import subprocess, sys
+
+          if sys.version_info >= (3, 11):
+              import tomllib
+          else:
+              try:
+                  import tomllib
+              except ModuleNotFoundError:
+                  import tomli as tomllib
+
+          diff = subprocess.check_output(["git", "diff", "uv.lock"], text=True)
+          if not diff:
+              print("changed=false")
+              raise SystemExit(0)
+
+          # Read pyproject.toml to find provider SDK packages from the matrix table
+          with open("pyproject.toml", "rb") as f:
+              pyproject = tomllib.load(f)
+
+          matrix = pyproject.get("tool", {}).get("braintrust", {}).get("matrix", {})
+
+          # Extract the base package name from each matrix requirement string
+          provider_pkgs = set()
+          for _prefix, versions in matrix.items():
+              for req in versions.values():
+                  # req looks like "openai==1.92.0" or "pydantic-ai==1.82.0"
+                  pkg = req.split("==")[0].split(">=")[0].split("<=")[0].strip()
+                  provider_pkgs.add(pkg)
+
+          # Check if any provider package changed in the lockfile diff
+          needs_rerecord = any(pkg in diff for pkg in provider_pkgs)
+
+          print("changed=true")
+          print(f"needs_rerecord={str(needs_rerecord).lower()}")
+          PYEOF
+
+      - name: Get date
+        id: date
+        run: echo "date=$(date +%Y-%m-%d)" >> "$GITHUB_OUTPUT"
+
+      - name: Open PR
+        if: steps.labels.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@271a8d0340265f705b14b31e8c0e067c3b0d45ef # v7.0.8
+        with:
+          title: "chore(deps): daily dependency update"
+          body: |
+            Automated daily dependency update via `uv lock --upgrade`.
+
+            ${{ steps.labels.outputs.needs_rerecord == 'true' && '⚠️ **Provider SDK packages changed.** A human needs to re-record cassettes locally before merging.' || '✅ Only test infrastructure deps changed. Safe to merge if CI passes.' }}
+          branch: deps/daily-update-${{ steps.date.outputs.date }}
+          labels: |
+            dependencies
+            ${{ steps.labels.outputs.needs_rerecord == 'true' && 'needs-cassette-rerecord' || 'auto-merge-candidate' }}

.pre-commit-config.yaml

@@ -19,6 +19,14 @@ repos:
       - id: ruff-format
       - id: ruff-check
         args: [--fix, --exit-non-zero-on-fix]
+  - repo: local
+    hooks:
+      - id: check-stale-cassettes
+        name: check stale cassettes
+        entry: python py/scripts/check-stale-cassettes.py
+        language: python
+        pass_filenames: false
+        files: (pyproject\.toml|cassettes/)
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.5
     hooks:
@@ -28,6 +36,7 @@ repos:
               .*\.(json|prisma|svg)
               |.*.yaml
               |.*/cassettes/.*
+              |.*uv\.lock
           )$
         args:
           - "-L"

.tool-versions

@@ -1,3 +1,3 @@
 python 3.14.3
 pre-commit 4.2.0
-uv 0.7.8
+uv 0.11.6

AGENTS.md

@@ -15,7 +15,8 @@ Use this file as the default playbook for work in this repository.
 2. **Use `mise` as the source of truth for tools and environment.**
 
 3. **Do not guess test commands or version coverage.**
-   - `py/noxfile.py` is the source of truth for nox session names, provider/version matrices, and local reproduction commands.
+   - `py/pyproject.toml` `[tool.braintrust.matrix]` is the source of truth for provider version pins (including what "latest" resolves to).
+   - `py/noxfile.py` reads those pins and is the source of truth for nox session names, parametrized version matrices, and local reproduction commands.
    - `.github/workflows/checks.yaml` is the source of truth for which sessions run in CI, on which Python versions, and outside vs. inside the nox shard matrix.
    - For provider and integration work, also check `py/src/braintrust/integrations/versioning.py`.
 
@@ -42,6 +43,8 @@ Use this file as the default playbook for work in this repository.
 ## Repo Map
 
 - `py/`: main Python package, tests, examples, nox sessions, build/release workflow
+- `py/pyproject.toml`: single source of truth for package metadata, dependency groups, and provider version matrix
+- `py/uv.lock`: committed lockfile for reproducible auxiliary dep resolution
 - `py/src/braintrust/`: SDK source
   - top-level package files: core SDK
   - `wrappers/`: wrappers
@@ -70,12 +73,7 @@ cd py
 make install-dev
 ```
 
-Install optional provider dependencies only when needed:
-
-```bash
-cd py
-make install-optional
-```
+Note: `install-dev` uses `uv sync` under the hood, reading dependency groups from `py/pyproject.toml`. There is no separate `requirements-dev.txt`.
 
 ## Default Workflow
 
@@ -236,6 +234,16 @@ BRAINTRUST_CLAUDE_AGENT_SDK_RECORD_MODE=all nox -s "test_claude_agent_sdk(latest
 
 Only re-record HTTP or subprocess cassettes when the behavior change is intentional. If unsure, ask the user.
 
+Stale cassette detection:
+
+- When versions are dropped from `[tool.braintrust.matrix]`, their cassette subdirectories become orphaned.
+- `py/scripts/check-stale-cassettes.py` compares on-disk cassette version directories against the matrix.
+- The mapping from integration directory name to matrix key(s) lives in `[tool.braintrust.cassette-dirs]` in `py/pyproject.toml`.
+- Runs automatically via pre-commit hook (triggers on `pyproject.toml` or `cassettes/` changes).
+- Manual check: `cd py && make check-stale-cassettes`
+- To auto-delete stale dirs: `cd py && python scripts/check-stale-cassettes.py --clean`
+- When adding a new integration with versioned cassettes, add an entry to `[tool.braintrust.cassette-dirs]`.
+
 ## Benchmarks
 
 If you touch a hot path such as serialization, deep-copy, span creation, or logging, consider benchmarks.
@@ -270,13 +278,27 @@ cd py
 make build
 ```
 
+The build uses `pyproject.toml` with the setuptools backend. There is no `setup.py`.
+
 Caveat:
 
 - `py/scripts/template-version.py` rewrites `py/src/braintrust/version.py` during build
 - `py/Makefile` restores that file afterward with `git checkout`
 
 Avoid editing `py/src/braintrust/version.py` while also running build commands.
 
+## Dependency Pinning
+
+All nox session dependency pins are centralized in `py/pyproject.toml`:
+
+- **`[dependency-groups]`** (PEP 735): base test deps, session-specific auxiliary deps (e.g. `test-litellm`, `test-langchain`), lint deps, build deps, and dev deps. These participate in `uv lock` and produce `py/uv.lock`.
+- **`[tool.braintrust.matrix]`**: provider version matrix pins (e.g. `openai`, `anthropic`). Each provider has a `latest` key pinned to an explicit version and additional older version keys. The noxfile reads these at import time to derive the parametrized version tuples.
+- **`[tool.uv.conflicts]`**: declares which dependency groups cannot coexist in one resolution (e.g. groups pinning different `openai` versions).
+
+The `LATEST` sentinel in the noxfile maps to the `latest` key in the matrix table — it is no longer a floating install.
+
+A daily GitHub Actions workflow (`.github/workflows/dependency-updates.yml`) runs `uv lock --upgrade`, classifies changes by reading group names from `pyproject.toml`, and opens a PR labeled `needs-cassette-rerecord` (provider SDK bumps) or `auto-merge-candidate` (infra-only bumps).
+
 ## Editing Guidelines
 
 - Keep tests close to the code they cover.

CONTRIBUTING.md

@@ -23,10 +23,12 @@ If you use `mise activate` in your shell, entering the repo will automatically e
 ## Repo Layout
 
 - `py/`: main Python SDK
+- `py/pyproject.toml`: single source of truth for package metadata, dependency groups, and provider version matrix
+- `py/uv.lock`: committed lockfile for reproducible auxiliary dep resolution
 - `integrations/`: separate integration packages such as LangChain and ADK
 - `docs/`: supporting docs
 
-Most SDK changes should happen under `py/`.
+Most SDK changes should happen under `py/`. There is no `setup.py` — `pyproject.toml` is the build configuration.
 
 ## Common Workflows
 
@@ -40,6 +42,8 @@ make lint
 nox -l
 ```
 
+`make install-dev` uses `uv sync` under the hood, reading dependency groups from `py/pyproject.toml`. There are no separate `requirements-*.txt` files.
+
 Run a focused session:
 
 ```bash
@@ -54,12 +58,7 @@ cd py
 nox -s "test_openai(latest)" -- -k "test_chat_metrics"
 ```
 
-Install optional provider packages only when you need them:
-
-```bash
-cd py
-make install-optional
-```
+Optional provider packages are installed automatically by each nox session — there is no separate `install-optional` target.
 
 ### Repo-Level Commands
 
@@ -95,7 +94,7 @@ uv run pytest
 
 ## Testing Notes
 
-The SDK uses [nox](https://nox.thea.codes/) for compatibility testing across optional providers and versions. `py/noxfile.py` is the source of truth for available sessions.
+The SDK uses [nox](https://nox.thea.codes/) for compatibility testing across optional providers and versions. Provider version pins live in `py/pyproject.toml` under `[tool.braintrust.matrix]`; the noxfile reads them at import time. `py/noxfile.py` is the source of truth for available sessions and their auxiliary deps.
 
 ### VCR Tests
 
@@ -187,7 +186,7 @@ To benchmark with the optional `orjson` fast-path installed:
 
 ```bash
 cd py
-python -m uv pip install -e '.[performance]'
+uv sync --extra performance
 make bench
 ```
 

README.md

@@ -13,6 +13,9 @@ This repository contains Braintrust's Python SDKs and integrations, including:
 Install the main SDK and scorer package:
 
 ```bash
+# uv
+uv add braintrust autoevals
+# pip
 pip install braintrust autoevals
 ```