Skip to content

Commit d48fef5

Browse files
AbhiPrasadAbhiPrasad
committed
meta: Use mise everywhere and clean up contributing docs
1 parent 33cfa00 commit d48fef5

17 files changed

Lines changed: 345 additions & 388 deletions

‎.github/workflows/adk-py-test.yaml‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -22,29 +22,27 @@ jobs:
2222
steps:
2323
- uses: actions/checkout@v4
2424

25-
- name: Set up uv
26-
uses: astral-sh/setup-uv@v3
25+
- name: Set up mise
26+
uses: jdx/mise-action@v3
2727
with:
28-
enable-cache: true
29-
cache-dependency-glob: |
30-
integrations/adk-py/pyproject.toml
31-
integrations/adk-py/uv.lock
28+
cache: true
29+
experimental: true
30+
install_args: python@${{ inputs.python-version }} uv
3231

3332
- name: Install dependencies
3433
run: |
35-
uv python install ${{ inputs.python-version }}
36-
uv sync
34+
mise exec python@${{ inputs.python-version }} -- uv sync
3735
3836
- name: Lint with ruff
3937
if: ${{ inputs.os == 'ubuntu-latest' }}
4038
run: |
41-
uv run ruff check $(git ls-files '*.py' | grep -v 'examples/')
39+
mise exec python@${{ inputs.python-version }} -- uv run ruff check $(git ls-files '*.py' | grep -v 'examples/')
4240
4341
- name: Run tests
4442
run: |
45-
uv run pytest
43+
mise exec python@${{ inputs.python-version }} -- uv run pytest
4644
4745
- name: Test import
4846
run: |
49-
uv run python -c "import braintrust_adk; print('braintrust_adk imported successfully')"
50-
uv run python -c "from braintrust_adk import setup_braintrust; print('setup_braintrust imported successfully')"
47+
mise exec python@${{ inputs.python-version }} -- uv run python -c "import braintrust_adk; print('braintrust_adk imported successfully')"
48+
mise exec python@${{ inputs.python-version }} -- uv run python -c "from braintrust_adk import setup_braintrust; print('setup_braintrust imported successfully')"

‎.github/workflows/langchain-py-test.yaml‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -22,29 +22,27 @@ jobs:
2222
steps:
2323
- uses: actions/checkout@v4
2424

25-
- name: Set up uv
26-
uses: astral-sh/setup-uv@v3
25+
- name: Set up mise
26+
uses: jdx/mise-action@v3
2727
with:
28-
enable-cache: true
29-
cache-dependency-glob: |
30-
integrations/langchain-py/pyproject.toml
31-
integrations/langchain-py/uv.lock
28+
cache: true
29+
experimental: true
30+
install_args: python@${{ inputs.python-version }} uv
3231

3332
- name: Install dependencies
3433
run: |
35-
uv python install ${{ inputs.python-version }}
36-
uv sync
34+
mise exec python@${{ inputs.python-version }} -- uv sync
3735
3836
- name: Lint with ruff
3937
if: ${{ inputs.os == 'ubuntu-latest' }}
4038
run: |
41-
uv run ruff check $(git ls-files '*.py' | grep -v 'examples/')
39+
mise exec python@${{ inputs.python-version }} -- uv run ruff check $(git ls-files '*.py' | grep -v 'examples/')
4240
4341
- name: Run tests
4442
run: |
45-
uv run pytest src
43+
mise exec python@${{ inputs.python-version }} -- uv run pytest src
4644
4745
- name: Test import
4846
run: |
49-
uv run python -c "import braintrust_langchain; print('braintrust_langchain imported successfully')"
50-
uv run python -c "from braintrust_langchain import BraintrustCallbackHandler; print('BraintrustCallbackHandler imported successfully')"
47+
mise exec python@${{ inputs.python-version }} -- uv run python -c "import braintrust_langchain; print('braintrust_langchain imported successfully')"
48+
mise exec python@${{ inputs.python-version }} -- uv run python -c "from braintrust_langchain import BraintrustCallbackHandler; print('BraintrustCallbackHandler imported successfully')"

‎.github/workflows/lint.yaml‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,14 @@ jobs:
1111
runs-on: ubuntu-latest
1212
timeout-minutes: 10
1313
steps:
14-
- uses: actions/checkout@v3
14+
- uses: actions/checkout@v4
1515
with:
1616
fetch-depth: 0 # Fetch full history for proper diff
17-
- uses: actions/setup-python@v3
18-
- uses: pre-commit/action@v3.0.0
17+
- name: Set up mise
18+
uses: jdx/mise-action@v3
1919
with:
20-
extra_args: --from-ref origin/${{ github.base_ref || 'main' }} --to-ref HEAD
20+
cache: true
21+
experimental: true
22+
- name: Run pre-commit
23+
run: |
24+
mise exec -- pre-commit run --from-ref origin/${{ github.base_ref || 'main' }} --to-ref HEAD

‎.github/workflows/publish-py-sdk.yaml‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -46,15 +46,15 @@ jobs:
4646
- uses: actions/checkout@v4
4747
with:
4848
fetch-depth: 0 # Fetch all history for changelog generation
49-
- name: Set up Python
50-
uses: actions/setup-python@v5
49+
- name: Set up mise
50+
uses: jdx/mise-action@v3
5151
with:
52-
python-version: "3.13"
52+
cache: true
53+
experimental: true
54+
install_args: python@3.13
5355
- name: Build and verify
54-
working-directory: py
5556
run: |
56-
make install-dev
57-
make verify-build
57+
mise exec python@3.13 -- make -C py install-dev verify-build
5858
- name: Upload build artifacts
5959
uses: actions/upload-artifact@v4
6060
with:

‎.github/workflows/py.yaml‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -26,25 +26,27 @@ jobs:
2626

2727
steps:
2828
- uses: actions/checkout@v4
29-
- name: Set up Python
30-
uses: actions/setup-python@v5
29+
- name: Set up mise
30+
uses: jdx/mise-action@v3
3131
with:
32-
python-version: ${{ matrix.python-version }}
32+
cache: true
33+
experimental: true
34+
install_args: python@${{ matrix.python-version }}
3335
- name: Install dependencies
3436
run: |
35-
cd py && make install-dev
37+
mise exec python@${{ matrix.python-version }} -- make -C py install-dev
3638
- name: Test whether the Python SDK can be installed
3739
run: |
3840
# This is already done by make install-dev, but we're keeping this as a separate step
3941
# to explicitly verify that installation works
40-
python -m uv pip install -e ./py[all]
42+
mise exec python@${{ matrix.python-version }} -- python -m uv pip install -e ./py[all]
4143
- name: Test whether the Python SDK can be imported
4244
run: |
43-
python -c 'import braintrust'
45+
mise exec python@${{ matrix.python-version }} -- python -c 'import braintrust'
4446
- name: Run nox tests (shard ${{ matrix.shard }}/2)
4547
shell: bash
4648
run: |
47-
cd py && ./scripts/nox-matrix.sh ${{ matrix.shard }} 2
49+
mise exec python@${{ matrix.python-version }} -- ./py/scripts/nox-matrix.sh ${{ matrix.shard }} 2
4850
4951
adk-py:
5052
uses: ./.github/workflows/adk-py-test.yaml
@@ -74,13 +76,15 @@ jobs:
7476
timeout-minutes: 10
7577
steps:
7678
- uses: actions/checkout@v4
77-
- name: Set up Python
78-
uses: actions/setup-python@v5
79+
- name: Set up mise
80+
uses: jdx/mise-action@v3
7981
with:
80-
python-version: "3.13"
82+
cache: true
83+
experimental: true
84+
install_args: python@3.13
8185
- name: Install build dependencies and build wheel
8286
run: |
83-
cd py && make install-build-deps && make build
87+
mise exec python@3.13 -- make -C py install-build-deps build
8488
- name: Upload wheel as artifact
8589
uses: actions/upload-artifact@v4
8690
with:

‎.github/workflows/test-publish-py-sdk.yaml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,18 +33,18 @@ jobs:
3333
- uses: actions/checkout@v4
3434
with:
3535
ref: ${{ github.event.inputs.ref }}
36-
- name: Set up Python
37-
uses: actions/setup-python@v5
36+
- name: Set up mise
37+
uses: jdx/mise-action@v3
3838
with:
39-
python-version: "3.13"
39+
cache: true
40+
experimental: true
41+
install_args: python@3.13
4042
- name: Install build dependencies
41-
working-directory: py
4243
run: |
43-
make install-dev
44+
mise exec python@3.13 -- make -C py install-dev
4445
- name: Build and verify
45-
working-directory: py
4646
run: |
47-
make verify-build
47+
mise exec python@3.13 -- make -C py verify-build
4848
- name: Get version from built wheel
4949
id: get_version
5050
run: |

‎.tool-versions‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
python 3.13.3
22
pre-commit 4.2.0
3+
uv 0.7.8

‎AGENTS.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Braintrust SDK Agent Guide
2+
3+
Guide for contributing to the Braintrust Python SDK repository.
4+
5+
## Defaults
6+
7+
- Use `mise` as the source of truth for tools and environment.
8+
- Prefer `py/` commands over root `make` targets when working on the SDK itself.
9+
- Keep changes narrow and run the smallest relevant test session first.
10+
- Do not rely on optional provider packages being installed unless the active nox session installs them.
11+
12+
## Repo Map
13+
14+
- `py/`: main Python package, tests, examples, nox sessions, release build
15+
- `integrations/`: separate integration packages
16+
- `internal/golden/`: compatibility and golden projects
17+
- `docs/`: supporting docs
18+
19+
Important code areas in `py/src/braintrust/`:
20+
21+
- core SDK modules: top-level package files
22+
- wrappers/integrations: `wrappers/`
23+
- temporal: `contrib/temporal/`
24+
- CLI/devserver: `cli/`, `devserver/`
25+
- tests: colocated `test_*.py`
26+
27+
## Setup
28+
29+
Preferred repo bootstrap:
30+
31+
```bash
32+
mise install
33+
make develop
34+
```
35+
36+
Package-focused setup:
37+
38+
```bash
39+
cd py
40+
make install-dev
41+
```
42+
43+
Install optional provider dependencies only if needed:
44+
45+
```bash
46+
cd py
47+
make install-optional
48+
```
49+
50+
## Commands
51+
52+
Preferred SDK workflow:
53+
54+
```bash
55+
cd py
56+
make lint
57+
make test-core
58+
nox -l
59+
```
60+
61+
Targeted wrapper/session runs:
62+
63+
```bash
64+
cd py
65+
nox -s "test_openai(latest)"
66+
nox -s "test_openai(latest)" -- -k "test_chat_metrics"
67+
```
68+
69+
Root `Makefile` exists as a convenience wrapper. The authoritative SDK workflow is in `py/Makefile` and `py/noxfile.py`.
70+
71+
## Tests
72+
73+
`py/noxfile.py` is the source of truth for compatibility coverage.
74+
75+
Key facts:
76+
77+
- `test_core` runs without optional vendor packages.
78+
- wrapper coverage is split across dedicated nox sessions by provider/version.
79+
- `pylint` installs the broad dependency surface before checking files.
80+
- `test-wheel` is a wheel sanity check and requires a built wheel first.
81+
82+
When changing behavior, run the narrowest affected session first, then expand only if needed.
83+
84+
## VCR
85+
86+
VCR cassette directories:
87+
88+
- `py/src/braintrust/cassettes/`
89+
- `py/src/braintrust/wrappers/cassettes/`
90+
- `py/src/braintrust/devserver/cassettes/`
91+
92+
Behavior from `py/src/braintrust/conftest.py`:
93+
94+
- local default: `record_mode="once"`
95+
- CI default: `record_mode="none"`
96+
- wheel-mode skips VCR-marked tests
97+
- test fixtures inject dummy API keys and reset global state
98+
99+
Common commands:
100+
101+
```bash
102+
cd py
103+
nox -s "test_openai(latest)"
104+
nox -s "test_openai(latest)" -- --disable-vcr
105+
nox -s "test_openai(latest)" -- --vcr-record=all -k "test_openai_chat_metrics"
106+
```
107+
108+
Only re-record cassettes when the behavior change is intentional. If in doubt, ask the user.
109+
110+
## Build Notes
111+
112+
Build from `py/`:
113+
114+
```bash
115+
cd py
116+
make build
117+
```
118+
119+
Important caveat:
120+
121+
- `py/scripts/template-version.sh` rewrites `py/src/braintrust/version.py` during build.
122+
- `py/Makefile` restores that file afterward with `git checkout`.
123+
124+
Avoid editing `py/src/braintrust/version.py` while also running build commands.
125+
126+
## Editing Guidance
127+
128+
- Keep tests near the code they cover.
129+
- Reuse existing fixtures and cassette patterns.
130+
- If a change affects examples or integrations, update the nearest example or focused test.
131+
- For CLI/devserver changes, consider whether wheel-mode behavior also needs coverage.

‎CLAUDE.md‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)