Skip to content

docs(examples): convert to per-integration uv projects using auto_instrument#363

Merged
Abhijeet Prasad (AbhiPrasad) merged 5 commits intomainfrom
examples-uv-projects-auto-instrument
Apr 29, 2026
Merged

docs(examples): convert to per-integration uv projects using auto_instrument#363
Abhijeet Prasad (AbhiPrasad) merged 5 commits intomainfrom
examples-uv-projects-auto-instrument

Conversation

@starfolkai
Copy link
Copy Markdown
Contributor

@starfolkai starfolkai Bot commented Apr 28, 2026

Summary

  • New examples/ directory at the repo root — each integration gets a self-contained uv project with its own pyproject.toml (pointing braintrust at the local py/ checkout), README.md, and example script(s). Lockfiles are gitignored so each clone resolves fresh against current PyPI.
  • Every provider example uses braintrust.auto_instrument() + init_logger() as the canonical setup, instead of integration-specific setup_*() / wrap_*() helpers.
  • Add 13 missing examples: agentscope, autogen, claude_agent_sdk, cohere, crewai, google_genai, langchain, litellm, llamaindex, mistral, openai_agents, openrouter, strands.

What changed

  • Layout: examples live at examples/ (repo root), not py/examples/. The repo-root README points at them.
  • Existing top-level scripts moved into their own dirs (history preserved): openai_example.pyopenai/, anthropic_*.pyanthropic/, pydantic_ai_example.pypydantic_ai/.
  • temporal/: requirements.txtpyproject.toml; Procfile and mise.toml updated to use uv sync / uv run.
  • langsmith/: drop committed uv.lock for consistency with the new per-example convention.
  • adk/: drop manual_patching.py since auto_instrument() covers the same case; rename auto.pyexample.py.
  • Drop the dedicated auto_instrument/ showcase since every provider example now demonstrates it by default.
  • examples/README.md explains the layout, the canonical 2-line pattern, and lists every example.

CI lint coverage

  • Extend the pylint nox session in py/noxfile.py to also enumerate ../examples/**/*.py and lint them in the same invocation. Reuses the existing matrix (Python 3.10–3.14), reuses the existing lint dependency-group, keeps it as one CI job — no new workflow surface area.
  • Add claude-agent-sdk and strands-agents to the lint dependency-group so pylint can resolve the new examples' imports.
  • Skip examples/crewai/ on Python 3.14 to mirror the existing conditional crewai pin (its transitive pydantic-core has 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:

Example Before After
anthropic/sync.py + anthropic/async_example.py claude-3-haiku-20240307 / claude-3-5-sonnet-latest claude-haiku-4-5
openai/example.py + pydantic_ai/example.py gpt-4o gpt-4o-mini
otel/basic_otel_example.py + otel/filtered_otel_example.py gpt-3.5-turbo gpt-4o-mini

Already-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.lock files would create constant churn on every transitive bump and would actively work against the demo goal. pyproject.toml already constrains requires-python and direct deps. (See examples/README.md for the rationale.)

Test plan

  • uv sync succeeds in every example dir
  • braintrust.auto_instrument() returns instrumented: True for the relevant integration in each example's venv (19/19 verified)
  • Imports succeed in every example with the correct symbols
  • nox -s pylint runs locally on Python 3.14 and lints all SDK source plus all moved examples in one pass (with crewai correctly skipped)
  • Reviewer manually runs one or two examples end-to-end with real API keys

🤖 Generated with Claude Code

Nova (SFK) and others added 5 commits April 28, 2026 23:09
…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>
@AbhiPrasad Abhijeet Prasad (AbhiPrasad) merged commit 97c75c2 into main Apr 29, 2026
82 checks passed
@AbhiPrasad Abhijeet Prasad (AbhiPrasad) deleted the examples-uv-projects-auto-instrument branch April 29, 2026 14:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant