docs(examples): convert to per-integration uv projects using auto_instrument#363
Merged
Abhijeet Prasad (AbhiPrasad) merged 5 commits intomainfrom Apr 29, 2026
Merged
Conversation
…trument Restructure py/examples/ so every example is an isolated uv project that clones/copies cleanly. Each one consists of a pyproject.toml (with a local editable braintrust source), a short README, and a tiny example script. Every provider example now uses braintrust.auto_instrument() + init_logger() as the canonical setup pattern instead of integration-specific setup_*() / wrap_*() helpers, matching the direction of the integrations API. - 13 new examples for previously uncovered integrations: agentscope, autogen, claude_agent_sdk, cohere, crewai, google_genai, langchain, litellm, llamaindex, mistral, openai_agents, openrouter, strands. - Existing top-level scripts moved into their own directories (openai_example.py -> openai/, anthropic_*.py -> anthropic/, etc.) with git history preserved. - temporal/: requirements.txt -> pyproject.toml; Procfile/mise.toml updated to use uv run / uv sync. - langsmith/: drop committed uv.lock for consistency. - adk/: drop manual_patching.py since auto_instrument supersedes it. - Drop the dedicated auto_instrument/ showcase since every provider example now demonstrates auto_instrument by default. - Top-level examples/README.md explains the layout, the canonical auto_instrument() pattern, and lists every example. - uv.lock files are gitignored: examples target current PyPI, not pinned snapshots, so each clone resolves fresh. Verified by running `uv sync` and `braintrust.auto_instrument()` in every example dir; each integration reports `instrumented: True`. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The new examples/claude_agent_sdk/example.py and examples/strands/example.py import these packages at module top, so pylint --errors-only flagged them as import-error since the lint dependency-group didn't include either package. Add both to the lint group (consistent with the rest of the provider deps already there) and refresh py/uv.lock. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Move py/examples/ to examples/ at the repo root so they're discoverable from the GitHub landing page without having to dig into py/. Each example's [tool.uv.sources] braintrust path moves from "../.." to "../../py". To avoid losing the lint coverage that previously caught broken imports, extend the pylint nox session in py/noxfile.py to also enumerate ../examples/**/*.py via `git -C ../examples ls-files` and lint them alongside the SDK source. Reuses the same `lint` dependency-group, same matrix, same CI job — just one extra line in the file list. Skip examples/crewai/ on Python 3.14 to match the existing conditional crewai pin in the lint group (its transitive pydantic-core has no 3.14 wheel yet). Add a pointer to examples/ in the repo-root README, and update example READMEs to reference `examples/<name>` instead of `py/examples/<name>`. Verified by running `nox -s pylint` locally on Python 3.14: 0 errors across all SDK source plus all moved examples (with crewai skipped). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replace stale model identifiers with current ones, matching what the SDK's own integration tests use: - anthropic/sync.py + anthropic/async_example.py: claude-3-haiku-20240307 and claude-3-5-sonnet-latest -> claude-haiku-4-5 (cheap + fast, matches py/src/braintrust/integrations/anthropic/test_anthropic.py). - openai/example.py + pydantic_ai/example.py: gpt-4o -> gpt-4o-mini, for consistency with every other OpenAI example in the tree. - otel/basic_otel_example.py + otel/filtered_otel_example.py: gpt-3.5-turbo -> gpt-4o-mini. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Pre-commit's ruff-format wanted the new git-ls-files call on a single line; revert the line break. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Abhijeet Prasad (AbhiPrasad)
approved these changes
Apr 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
examples/directory at the repo root — each integration gets a self-containeduvproject with its ownpyproject.toml(pointingbraintrustat the localpy/checkout),README.md, and example script(s). Lockfiles are gitignored so each clone resolves fresh against current PyPI.braintrust.auto_instrument()+init_logger()as the canonical setup, instead of integration-specificsetup_*()/wrap_*()helpers.agentscope,autogen,claude_agent_sdk,cohere,crewai,google_genai,langchain,litellm,llamaindex,mistral,openai_agents,openrouter,strands.What changed
examples/(repo root), notpy/examples/. The repo-root README points at them.openai_example.py→openai/,anthropic_*.py→anthropic/,pydantic_ai_example.py→pydantic_ai/.temporal/:requirements.txt→pyproject.toml;Procfileandmise.tomlupdated to useuv sync/uv run.langsmith/: drop committeduv.lockfor consistency with the new per-example convention.adk/: dropmanual_patching.pysinceauto_instrument()covers the same case; renameauto.py→example.py.auto_instrument/showcase since every provider example now demonstrates it by default.examples/README.mdexplains the layout, the canonical 2-line pattern, and lists every example.CI lint coverage
pylintnox session inpy/noxfile.pyto also enumerate../examples/**/*.pyand lint them in the same invocation. Reuses the existing matrix (Python 3.10–3.14), reuses the existinglintdependency-group, keeps it as one CI job — no new workflow surface area.claude-agent-sdkandstrands-agentsto thelintdependency-group so pylint can resolve the new examples' imports.examples/crewai/on Python 3.14 to mirror the existing conditional crewai pin (its transitivepydantic-corehas no 3.14 wheel yet).Modernized model names
Replaced stale model identifiers in examples with current ones, matching what the SDK's own integration tests use:
anthropic/sync.py+anthropic/async_example.pyclaude-3-haiku-20240307/claude-3-5-sonnet-latestclaude-haiku-4-5openai/example.py+pydantic_ai/example.pygpt-4ogpt-4o-miniotel/basic_otel_example.py+otel/filtered_otel_example.pygpt-3.5-turbogpt-4o-miniAlready-current models (
gemini-2.0-flash,command-r-plus-08-2024,mistral-small-latest,claude-haiku-4-5-20251001,gpt-4o-mini) left alone.Why no committed lockfiles
Examples are meant to demonstrate the current SDK against current providers, not snapshot a moment in time. Committing ~24
uv.lockfiles would create constant churn on every transitive bump and would actively work against the demo goal.pyproject.tomlalready constrainsrequires-pythonand direct deps. (Seeexamples/README.mdfor the rationale.)Test plan
uv syncsucceeds in every example dirbraintrust.auto_instrument()returnsinstrumented: Truefor the relevant integration in each example's venv (19/19 verified)nox -s pylintruns locally on Python 3.14 and lints all SDK source plus all moved examples in one pass (withcrewaicorrectly skipped)🤖 Generated with Claude Code