wandb · LorenzoWandB · Aug 18, 2026
diff --git a/weave-cookbook/.gitignore b/weave-cookbook/.gitignore
@@ -0,0 +1,59 @@
+# Local environment and secrets
+.env
+.env.*
+!.env.example
+.envrc
+.direnv/
+.netrc
+.npmrc
+.pypirc
+credentials*.json
+secrets*.json
+service-account*.json
+!credentials.example.json
+!secrets.example.json
+*.pem
+*.key
+*.p12
+*.pfx
+*.jks
+*.keystore
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Node
+node_modules/
+dist/
+.vite/
+*.tsbuildinfo
+coverage/
+
+# W&B local artifacts
+wandb/
+weave_logs/
+
+# Logs and temporary files
+*.log
+logs/
+.cache/
+.tmp/
+tmp/
+
+# OS and editor
+.DS_Store
+
+# Local AI tools and model files
+models/
+CLAUDE.md
+.claude/
+.cursor/
+.aider*
+.continue/
diff --git a/weave-cookbook/CONTRIBUTING.md b/weave-cookbook/CONTRIBUTING.md
@@ -0,0 +1,35 @@
+# Contributing
+
+Keep additions small, runnable, and aligned across Python and TypeScript.
+
+Before writing a guide, read the [cookbook blueprint](reference/COOKBOOK_BLUEPRINT.md), [guide template](reference/GUIDE_TEMPLATE.md), and [source map](reference/SOURCE_MAP.md). A guide should add one idea, run from its language directory, show a concrete Weave success state, and link exhaustive API details to the official docs.
+
+## Validate changes
+
+From the repository root:
+
+```bash
+python3 scripts/validate_docs.py
+python3 scripts/check_secrets.py
+```
+
+For Python:
+
+```bash
+cd python
+uv sync
+uv run ruff format --check .
+uv run ruff check .
+uv run pytest -q -m "not live"
+```
+
+For TypeScript:
+
+```bash
+cd typescript
+npm ci
+npm run typecheck
+npm test
+```
+
+Live checks are opt-in because they write to W&B services and may use Inference credits. When an API, SDK behavior, UI label, or expected output changes, update the example, guide, tests, sanitized capture, [source map](reference/SOURCE_MAP.md), and [compatibility record](reference/COMPATIBILITY.md) together.
diff --git a/weave-cookbook/LICENSE b/weave-cookbook/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weights & Biases
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/weave-cookbook/README.md b/weave-cookbook/README.md
@@ -0,0 +1,105 @@
+# Weave Cookbook
+
+Short, runnable Python and TypeScript guides for AI engineers learning [W&B Weave](https://weave-docs.wandb.ai/). Each guide adds one capability to the **Game Night Agent** and ends with a concrete result to inspect in Weave.
+
+Official docs remain the API reference. This repository is the ordered path between a quickstart and a full production demo: enough code to trace, evaluate, and improve one LLM application, without deployment infrastructure or product boilerplate.
+
+Published by [Lorenzo Balderrama](https://github.com/LorenzoWandB).
+
+## Your first trace
+
+Pick a language. Each cookbook is self-contained.
+
+**Python** (needs [uv](https://docs.astral.sh/uv/)):
+
+```bash
+cd python
+uv sync
+cp .env.example .env   # set WANDB_API_KEY from https://wandb.ai/settings
+uv run python examples/00_hello_trace.py
+```
+
+**TypeScript** (needs Node.js 20.12+):
+
+```bash
+cd typescript
+npm install
+cp .env.example .env   # set WANDB_API_KEY from https://wandb.ai/settings
+npm run hello
+```
+
+Either way, the terminal prints a link to your project — open **Agents** to see the first conversation.
+
+## Core path
+
+| # | Guide | Python | TypeScript |
+| --- | --- | --- | --- |
+| 00 | Setup | [guide](python/guides/00-setup/README.md) | [guide](typescript/guides/00-setup/README.md) |
+| 01 | Tracing | [guide](python/guides/01-tracing/README.md) | [guide](typescript/guides/01-tracing/README.md) |
+| 02 | Evaluations | [guide](python/guides/02-evaluations/README.md) | [guide](typescript/guides/02-evaluations/README.md) |
+| 03 | LLM as a judge | [guide](python/guides/03-llm-judge/README.md) | [guide](typescript/guides/03-llm-judge/README.md) |
+
+The core loop is: trace the agent, measure it, add a judge. Version objects when you need to compare the next run.
+
+## Track agents
+
+| # | Guide | Python | TypeScript |
+| --- | --- | --- | --- |
+| 07 | Track agents | [guide](python/guides/07-agents/README.md) | [guide](typescript/guides/07-agents/README.md) |
+
+Harness plugins trace agents you already use — Claude Code first, no code changes.
+
+## Iterate
+
+| # | Guide | Python | TypeScript |
+| --- | --- | --- | --- |
+| 04 | Version objects | [guide](python/guides/04-versioning/README.md) | [guide](typescript/guides/04-versioning/README.md) |
+| 05 | Prompts | [guide](python/guides/05-prompts/README.md) | [guide](typescript/guides/05-prompts/README.md) |
+
+## Platform
+
+| # | Guide | Python | TypeScript |
+| --- | --- | --- | --- |
+| 06 | Serverless Inference | [guide](python/guides/06-serverless-inference/README.md) | [guide](typescript/guides/06-serverless-inference/README.md) |
+| 08 | OpenTelemetry | [guide](python/guides/08-otel/README.md) | [guide](typescript/guides/08-otel/README.md) |
+
+## I want to...
+
+| Task | Where |
+| --- | --- |
+| Log my first conversation | Guide 00 ([Python](python/guides/00-setup/README.md) / [TypeScript](typescript/guides/00-setup/README.md)) |
+| Trace tool and LLM calls inside a turn | Guide 01 ([Python](python/guides/01-tracing/README.md) / [TypeScript](typescript/guides/01-tracing/README.md)) |
+| Track agents I already use | Guide 07 ([Python](python/guides/07-agents/README.md) / [TypeScript](typescript/guides/07-agents/README.md)) |
+| Measure whether my app works | Guide 02 ([Python](python/guides/02-evaluations/README.md) / [TypeScript](typescript/guides/02-evaluations/README.md)) |
+| Score a fuzzy property with an LLM judge | Guide 03 ([Python](python/guides/03-llm-judge/README.md) / [TypeScript](typescript/guides/03-llm-judge/README.md)) |
+| Compare a new prompt or dataset version | Guides 04–05 ([Python](python/guides/04-versioning/README.md) / [TypeScript](typescript/guides/04-versioning/README.md)) |
+| List or switch Serverless Inference models | Guide 06 ([Python](python/guides/06-serverless-inference/README.md) / [TypeScript](typescript/guides/06-serverless-inference/README.md)) |
+| Send spans from an existing OTel pipeline | Guide 08 ([Python](python/guides/08-otel/README.md) / [TypeScript](typescript/guides/08-otel/README.md)) |
+| Follow the shortest learning route | [Golden path](reference/GOLDEN_PATH.md) |
+| See what is built and planned | [Cookbook blueprint](reference/COOKBOOK_BLUEPRINT.md) |
+| Check tested SDK and runtime versions | [Compatibility](reference/COMPATIBILITY.md) |
+| Understand Conversation, Turn, Scorer... | [Glossary](reference/GLOSSARY.md) |
+| See where every API claim was verified | [Source map](reference/SOURCE_MAP.md) |
+| Fix a failing run | [Troubleshooting](reference/TROUBLESHOOTING.md) |
+
+## Map
+
+```text
+weave-cookbook/
+├── python/       Python cookbook: examples, guides, tests
+├── typescript/   TypeScript cookbook: examples, guides, tests
+├── reference/    blueprint, glossary, source map, troubleshooting, compatibility
+├── scripts/      documentation and secret checks
+└── assets/       sanitized expected output
+```
+
+## Validate the repository
+
+```bash
+python3 scripts/validate_docs.py
+python3 scripts/check_secrets.py
+```
+
+Per-language checks are listed in [python/README.md](python/README.md) and [typescript/README.md](typescript/README.md).
+
+Contribution requirements are in [CONTRIBUTING.md](CONTRIBUTING.md). The examples are available under the [MIT License](LICENSE).
diff --git a/weave-cookbook/assets/expected-output/python-00-hello-trace.txt b/weave-cookbook/assets/expected-output/python-00-hello-trace.txt
@@ -0,0 +1,6 @@
+$ uv run python examples/00_hello_trace.py
+weave: Logged in as Weights & Biases user: <your-username>.
+weave: View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+Welcome to game night! Bring snacks.
+
+Captured 2026-08-02 with weave 0.53.4 on Python 3.11.13.
diff --git a/weave-cookbook/assets/expected-output/python-01-trace-recommendation.txt b/weave-cookbook/assets/expected-output/python-01-trace-recommendation.txt
@@ -0,0 +1,7 @@
+$ uv run python examples/01_trace_recommendation.py --players 4 --minutes 60 --vibe "cooperative"
+weave: Logged in as Weights & Biases user: <your-username>.
+weave: View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+Gemcutter's Guild
+
+The model's pick varies between runs; the output remains one catalog name or "none".
+Expected output shape for weave 0.53.4 on Python 3.11.13.
diff --git a/weave-cookbook/assets/expected-output/python-02-eval-logger.txt b/weave-cookbook/assets/expected-output/python-02-eval-logger.txt
@@ -0,0 +1,7 @@
+$ uv run python examples/02_eval_logger.py
+weave: Logged in as Weights & Biases user: <your-username>.
+weave: View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+Logged 3 predictions to evaluation 'game-night-batch'.
+weave: 🍩 https://wandb.ai/<entity>/weave-cookbook/r/call/<call-id>
+
+Captured 2026-08-02 with weave 0.53.4 on Python 3.11.13.
diff --git a/weave-cookbook/assets/expected-output/python-02-evaluate.txt b/weave-cookbook/assets/expected-output/python-02-evaluate.txt
@@ -0,0 +1,30 @@
+$ uv run python examples/02_evaluate.py
+weave: Logged in as Weights & Biases user: <your-username>.
+weave: View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+weave: Evaluated 1 of 5 examples
+weave: Evaluated 2 of 5 examples
+weave: Evaluated 3 of 5 examples
+weave: Evaluated 4 of 5 examples
+weave: Evaluated 5 of 5 examples
+weave: Evaluation summary {
+weave:   "valid_pick": {
+weave:     "valid_pick": {
+weave:       "true_count": 5,
+weave:       "true_fraction": 1.0
+weave:     }
+weave:   },
+weave:   "fits_constraints": {
+weave:     "fits_constraints": {
+weave:       "true_count": 5,
+weave:       "true_fraction": 1.0
+weave:     }
+weave:   },
+weave:   "model_latency": {
+weave:     "mean": 0.71
+weave:   }
+weave: }
+{'valid_pick': {'valid_pick': {'true_count': 5, 'true_fraction': 1.0}}, 'fits_constraints': {'fits_constraints': {'true_count': 5, 'true_fraction': 1.0}}, 'model_latency': {'mean': 0.71}}
+weave: 🍩 https://wandb.ai/<entity>/weave-cookbook/r/call/<call-id>
+
+Counts can dip below 5 when the model adds extra words to a reply.
+Captured 2026-08-02 with weave 0.53.4 on Python 3.11.13.
diff --git a/weave-cookbook/assets/expected-output/python-03-llm-judge.txt b/weave-cookbook/assets/expected-output/python-03-llm-judge.txt
@@ -0,0 +1,18 @@
+$ uv run python examples/03_llm_judge.py
+weave: Logged in as Weights & Biases user: <your-username>.
+weave: View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+weave: Evaluated 1 of 6 examples
+...
+weave: Evaluated 6 of 6 examples
+weave: Evaluation summary { ... "agrees_with_human": { "true_count": 5, "true_fraction": 0.83 } ... }
+weave: Evaluated 1 of 3 examples
+...
+weave: Evaluated 3 of 3 examples
+weave: Evaluation summary { ... "vibe_match": { "true_count": 2, "true_fraction": 0.67 } ... }
+Judge agrees with the human labels on 83% of calibration rows.
+{'true_count': 2, 'true_fraction': 0.6666666666666666}
+weave: 🍩 https://wandb.ai/<entity>/weave-cookbook/r/call/<call-id>
+weave: 🍩 https://wandb.ai/<entity>/weave-cookbook/r/call/<call-id>
+
+Agreement and scores vary between runs; 5/6 and 2/3 were one captured run.
+Captured 2026-08-02 with weave 0.53.4 on Python 3.11.13.
diff --git a/weave-cookbook/assets/expected-output/python-04-versioning.txt b/weave-cookbook/assets/expected-output/python-04-versioning.txt
@@ -0,0 +1,10 @@
+$ uv run python examples/04_versioning.py
+weave: Logged in as Weights & Biases user: <your-username>.
+weave: View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+weave: 📦 Published to https://wandb.ai/<entity>/weave-cookbook/weave/objects/game-catalog/versions/<digest>
+weave: 📦 Published to https://wandb.ai/<entity>/weave-cookbook/weave/objects/game-catalog/versions/<digest>
+published: weave:///<entity>/weave-cookbook/object/game-catalog:<digest>
+published: weave:///<entity>/weave-cookbook/object/game-catalog:<digest>
+latest has 13 games; v0 still has 12.
+
+Captured 2026-08-02 with weave 0.53.4 on Python 3.11.13.
diff --git a/weave-cookbook/assets/expected-output/python-05-prompts.txt b/weave-cookbook/assets/expected-output/python-05-prompts.txt
@@ -0,0 +1,12 @@
+$ uv run python examples/05_prompts.py
+weave: Logged in as Weights & Biases user: <your-username>.
+weave: View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+weave: 📦 Published to https://wandb.ai/<entity>/weave-cookbook/weave/objects/game-night-system/versions/<digest>
+weave: 📦 Published to https://wandb.ai/<entity>/weave-cookbook/weave/objects/game-night-request/versions/<digest>
+weave: 🍩 https://wandb.ai/<entity>/weave-cookbook/r/call/<call-id>
+The Alchemist's Cellar
+
+fetched game-night-system:latest -> You are the Game Night Agent. Pick exactly one game from the candidate list. Cho...
+
+The model's pick varies between runs; the prompt preview does not.
+Expected output shape for weave 0.53.4 on Python 3.11.13.
diff --git a/weave-cookbook/assets/expected-output/python-06-inference.txt b/weave-cookbook/assets/expected-output/python-06-inference.txt
@@ -0,0 +1,10 @@
+$ uv run python examples/06_inference.py
+weave: Logged in as Weights & Biases user: <your-username>.
+weave: View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+30 models available through one API key; using meta-llama/Llama-3.1-8B-Instruct
+Game Night is about to begin, folks, in just ten minutes, so get your snacks ready and your competitive spirits warmed up!
+usage: 62 prompt + 27 completion tokens
+weave: 🍩 https://wandb.ai/<entity>/weave-cookbook/r/call/<call-id>
+
+The model count and wording vary; temperature 0.2 keeps replies stable but not identical.
+Captured 2026-08-02 with weave 0.53.4 on Python 3.11.13.
diff --git a/weave-cookbook/assets/expected-output/python-08-otel.txt b/weave-cookbook/assets/expected-output/python-08-otel.txt
@@ -0,0 +1,6 @@
+$ uv run python examples/08_otel.py
+Play Orchard Sprint: done in 20 minutes.
+
+No weave banner and no trace link: the Weave SDK is not involved. The trace
+appears under Traces in your project (wandb.ai/<entity>/weave-cookbook/weave).
+Captured 2026-08-02 with opentelemetry-sdk 1.44.0 on Python 3.11.13.
diff --git a/weave-cookbook/assets/expected-output/typescript-00-hello-trace.txt b/weave-cookbook/assets/expected-output/typescript-00-hello-trace.txt
@@ -0,0 +1,9 @@
+$ npm run hello
+
+> weave-cookbook-ts@0.1.0 hello
+> tsx examples/00-hello-trace.ts
+
+View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+Welcome to game night! Bring snacks.
+
+Captured 2026-08-02 with weave (npm) 0.16.5 on Node.js 26.4.0.
diff --git a/weave-cookbook/assets/expected-output/typescript-01-trace-recommendation.txt b/weave-cookbook/assets/expected-output/typescript-01-trace-recommendation.txt
@@ -0,0 +1,10 @@
+$ npm run recommend -- --players 4 --minutes 60 --vibe "cooperative"
+
+> weave-cookbook-ts@0.1.0 recommend
+> tsx examples/01-trace-recommendation.ts --players 4 --minutes 60 --vibe cooperative
+
+View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+The Alchemist's Cellar
+
+The model's pick varies between runs; the output remains one catalog name or "none".
+Expected output shape for weave (npm) 0.16.5 on Node.js 26.4.0.
diff --git a/weave-cookbook/assets/expected-output/typescript-02-eval-logger.txt b/weave-cookbook/assets/expected-output/typescript-02-eval-logger.txt
@@ -0,0 +1,9 @@
+$ npm run eval-logger
+
+> weave-cookbook-ts@0.1.0 eval-logger
+> tsx examples/02-eval-logger.ts
+
+View Weave data at https://wandb.ai/<entity>/weave-cookbook/weave
+Logged 3 predictions to evaluation 'game-night-batch'.
+
+Captured 2026-08-02 with weave (npm) 0.16.5 on Node.js 26.4.0.