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

## 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.py` → `openai/`, `anthropic_*.py` →
`anthropic/`, `pydantic_ai_example.py` → `pydantic_ai/`.
- **`temporal/`:** `requirements.txt` → `pyproject.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.py` → `example.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

- [x] `uv sync` succeeds in every example dir
- [x] `braintrust.auto_instrument()` returns `instrumented: True` for
the relevant integration in each example's venv (19/19 verified)
- [x] Imports succeed in every example with the correct symbols
- [x] `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](https://claude.com/claude-code)

---------

Co-authored-by: Nova (SFK) <nova@starfolk.ai>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: 3 people

README.md

@@ -6,7 +6,8 @@ This repository contains Braintrust's Python SDKs and integrations, including:
 
 - The main `braintrust` SDK package in [`./py`](./py)
 - Built-in integrations under [`py/src/braintrust/integrations`](py/src/braintrust/integrations) and related compatibility packages under [`./integrations`](./integrations)
-- Examples, tests, and local development tooling for Python SDK development
+- Self-contained `uv`-project examples for every integration in [`./examples`](./examples)
+- Tests and local development tooling for Python SDK development
 
 ## Quickstart
 

examples/.gitignore

@@ -0,0 +1,8 @@
+run.sh
+
+# Examples install fresh against current PyPI; locks aren't checked in.
+uv.lock
+.venv/
+__pycache__/
+*.pyc
+.env

examples/README.md

@@ -0,0 +1,96 @@
+# Braintrust Python SDK Examples
+
+Each subdirectory in this folder is a self-contained [`uv`](https://docs.astral.sh/uv/) project demonstrating one Braintrust integration or feature. They are designed to be cloned, copied, or run as-is without affecting the rest of the repository.
+
+## Layout
+
+Every example has the same shape:
+
+```
+examples/<name>/
+├── pyproject.toml   # declares deps + a local `path` source for braintrust
+├── README.md        # what it shows + how to run it
+└── *.py             # the example script(s)
+```
+
+The `pyproject.toml` in each example pins `braintrust` to the local SDK checkout in `py/` via:
+
+```toml
+[tool.uv.sources]
+braintrust = { path = "../../py", editable = true }
+```
+
+That means `uv sync` inside any example installs the version of the SDK currently on disk — edits to `py/src/braintrust/` are picked up immediately.
+
+## Running an example
+
+From the repo root:
+
+```bash
+cd examples/<name>
+uv sync
+uv run python <script>.py
+```
+
+You will need a `BRAINTRUST_API_KEY` in your environment, plus whatever provider key the example uses (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.). Each example's README lists its requirements.
+
+## The default pattern: `auto_instrument()`
+
+Most provider/framework examples follow the same two-line setup:
+
+```python
+import braintrust
+
+braintrust.auto_instrument()
+braintrust.init_logger(project="example-<name>")
+
+# now import and use the library normally
+```
+
+`braintrust.auto_instrument()` patches every supported integration that's installed in the current environment — there's no need to call individual `setup_*()` or `wrap_*()` helpers. The exceptions are examples that demonstrate non-tracing concerns (`evals/`, `langsmith/`, `otel/`, `temporal/`).
+
+If you want to see `auto_instrument()` light up multiple providers in one trace, the `openai/`, `anthropic/`, and any other provider example can be combined trivially — just install both packages in the same environment, call `auto_instrument()` once, and use both clients.
+
+## Available examples
+
+Unless noted otherwise, every example below uses `braintrust.auto_instrument()`.
+
+| Directory | What it shows |
+| --- | --- |
+| `adk/` | Google ADK weather agent with one tool |
+| `agentscope/` | AgentScope `ReActAgent` against `gpt-4o-mini` |
+| `agno/` | Agno agents and teams, sync + async, streaming + non-streaming |
+| `anthropic/` | Sync and async Anthropic clients |
+| `autogen/` | AutoGen `AssistantAgent` backed by `OpenAIChatCompletionClient` |
+| `claude_agent_sdk/` | Claude Agent SDK subprocess query |
+| `cohere/` | Cohere `ClientV2` chat call |
+| `crewai/` | CrewAI `Agent` + `Task` + `Crew` end-to-end |
+| `dspy/` | DSPy `ReAct` agent with two tools (LiteLLM token metrics propagate) |
+| `evals/` | The `Eval` framework — does **not** use `auto_instrument()` |
+| `google_genai/` | Google GenAI `generate_content` against Gemini |
+| `langchain/` | LangChain `prompt | model` chain — global handler installed by `auto_instrument()` |
+| `langsmith/` | Migration helper for projects coming from LangSmith — uses `setup_langsmith()` |
+| `litellm/` | LiteLLM `completion` |
+| `llamaindex/` | LlamaIndex LLM completion |
+| `mistral/` | Mistral chat completion |
+| `openai/` | OpenAI chat completion plus `@braintrust.traced` for the surrounding function |
+| `openai_agents/` | OpenAI Agents SDK `Runner` running an agent |
+| `openrouter/` | OpenRouter chat completion routed to OpenAI |
+| `otel/` | OpenTelemetry interop — `BraintrustSpanProcessor`, filtering, distributed tracing |
+| `pydantic_ai/` | Pydantic AI agent run inside a `start_span` for a permalink |
+| `strands/` | Strands `Agent` against `gpt-4o-mini` |
+| `temporal/` | Distributed Temporal workflow tracing via `BraintrustPlugin` |
+
+## Why no committed `uv.lock`?
+
+Examples are meant to demonstrate the **current** SDK against **current** provider releases, not snapshot a specific point in time. Committing lockfiles would create constant churn (a new lockfile for every transitive bump on PyPI) and would actively work against the demo goal — someone running an example next quarter wants it to work with whatever's on PyPI today, not a 3-month-old pin. Lockfiles are gitignored.
+
+If you want a reproducible snapshot for your own use, run `uv lock` locally; it just won't be checked in.
+
+## Adding a new example
+
+1. Create `examples/<name>/` with the layout above.
+2. In `pyproject.toml`, declare deps under `[project] dependencies` and add the local `braintrust` source under `[tool.uv.sources]` (see any existing example).
+3. Write a short README explaining required env vars and how to run it.
+4. Verify with `uv sync && uv run python <script>.py` from inside the example dir.
+5. The `pylint` nox session in `py/noxfile.py` automatically lints `examples/`, so any imports your example needs must be in the `lint` dependency group of `py/pyproject.toml`.

examples/adk/README.md

@@ -0,0 +1,13 @@
+# Google ADK + Braintrust
+
+Calls `braintrust.auto_instrument()` so Google ADK is patched automatically, then runs a weather agent against `gemini-2.0-flash` with one tool. The trace shows the runner span, the agent span, the LLM span, and the tool call.
+
+## Run
+
+```bash
+export BRAINTRUST_API_KEY=...
+export GOOGLE_API_KEY=...
+
+uv sync
+uv run python example.py
+```

py/examples/adk/auto.py examples/adk/example.pypy/examples/adk/auto.py renamed to examples/adk/example.py

@@ -1,18 +1,12 @@
-"""Auto-instrument Google ADK with Braintrust tracing.
-
-Usage:
-    export BRAINTRUST_API_KEY="your-api-key"
-    export GOOGLE_API_KEY="your-google-api-key"
-    python auto.py
-"""
+"""Google ADK weather agent traced via braintrust.auto_instrument()."""
 
 import asyncio
 
 import braintrust
 
 
-# Auto-instrument all supported libraries including Google ADK
 braintrust.auto_instrument()
+braintrust.init_logger(project="example-adk")
 
 from google.adk import Agent
 from google.adk.runners import Runner

examples/adk/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "braintrust-adk-example"
+version = "0.1.0"
+description = "Google ADK agents traced via Braintrust"
+requires-python = ">=3.10"
+dependencies = [
+    "braintrust",
+    "google-adk",
+    "google-genai",
+]
+
+[tool.uv.sources]
+braintrust = { path = "../../py", editable = true }

examples/agentscope/README.md

@@ -0,0 +1,13 @@
+# AgentScope + Braintrust
+
+Calls `braintrust.auto_instrument()` to register the AgentScope tracing hooks, then runs a `ReActAgent` against `gpt-4o-mini`. The trace shows the agent's `*.reply` task span and the underlying LLM span.
+
+## Run
+
+```bash
+export BRAINTRUST_API_KEY=...
+export OPENAI_API_KEY=...
+
+uv sync
+uv run python example.py
+```

examples/agentscope/example.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python
+"""AgentScope ReAct agent traced via braintrust.auto_instrument()."""
+
+import asyncio
+
+import braintrust
+
+
+braintrust.auto_instrument()
+braintrust.init_logger(project="example-agentscope")
+
+from agentscope.agent import ReActAgent
+from agentscope.formatter import OpenAIChatFormatter
+from agentscope.memory import InMemoryMemory
+from agentscope.message import Msg
+from agentscope.model import OpenAIChatModel
+from agentscope.tool import Toolkit
+
+
+async def main() -> None:
+    agent = ReActAgent(
+        name="Friday",
+        sys_prompt="You are a concise assistant. Answer in one sentence.",
+        model=OpenAIChatModel(model_name="gpt-4o-mini", stream=False),
+        formatter=OpenAIChatFormatter(),
+        toolkit=Toolkit(),
+        memory=InMemoryMemory(),
+    )
+
+    response = await agent(Msg(name="user", content="Say hello in exactly two words.", role="user"))
+    print(response.content if response is not None else "(no response)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/agentscope/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "braintrust-agentscope-example"
+version = "0.1.0"
+description = "AgentScope ReAct agent traced with Braintrust"
+requires-python = ">=3.10"
+dependencies = [
+    "braintrust",
+    "agentscope",
+    "openai",
+]
+
+[tool.uv.sources]
+braintrust = { path = "../../py", editable = true }

examples/agno/README.md

@@ -0,0 +1,21 @@
+# Agno + Braintrust
+
+Each script calls `braintrust.auto_instrument()` before importing `agno`, so all subsequent agent/team activity is traced. The agents use `YFinanceTools` so they actually exercise tool calls.
+
+| Script | Shape |
+| --- | --- |
+| `simple_agent.py` | one agent, one question |
+| `simple_agent_stream.py` | one agent, streamed |
+| `async_simple_agent_stream.py` | one agent, async + streamed |
+| `team_agent.py` | research + advisor team, sync |
+| `async_team_agent.py` | research + advisor team, async + streamed |
+
+## Run
+
+```bash
+export BRAINTRUST_API_KEY=...
+export OPENAI_API_KEY=...
+
+uv sync
+uv run python simple_agent.py
+```