feat: 0.3.0: tracer.watch, @tracer/watch (JS/TS), and the tracer cloud CLI

- tracer.watch: one-line observability for the LLM calls your pipeline already
  makes, recorded on the OpenTelemetry GenAI schema, with local, OTLP, and free
  Tracer Cloud sinks. The same trace object feeds tracer.fit() and tracer.scan().
- @tracer/watch: a zero-dependency JavaScript/TypeScript watcher with the same
  one-line API, async-context aware.
- tracer cloud: a full command-line interface at parity with the dashboard:
  login, tracers (create, quick and bulk uploads, agentic onboard), training
  (retrain, auto-retrain, promote, live status), routing, test batteries, the
  model library, API keys, observability ingest keys, billing, analytics,
  trace selection, and scan.
- Lazy package initialization so import tracer stays fast.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: adrida

.gitignore

@@ -32,3 +32,6 @@ notebooks/data/
 # Editors
 .idea/
 .vscode/
+
+# Node (JS package)
+node_modules/

CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to TRACER are recorded here. This project follows semantic
 versioning.
 
+## 0.3.0 (2026-06)
+
+### Added
+- `tracer.watch`: a decorator (and HTTP fallback) that observes the LLM calls
+  your pipeline already makes and ships them, free, to Tracer Cloud, where they
+  accumulate and auto-optimize once there are enough. Captures the full request
+  and response on the OpenTelemetry GenAI (`gen_ai.*`) schema, with pluggable
+  sinks (local file, Tracer Cloud, OTLP, or several at once).
+- `@tracer/watch`: a zero-dependency JavaScript/TypeScript mirror of the watch
+  decorator (async-context aware), so JS pipelines get the same one-line
+  observability as Python.
+- `tracer cloud`: a full command-line interface for Tracer Cloud, at parity with
+  the dashboard. Browser or password login, then manage tracers (create, quick
+  and bulk uploads, agentic `onboard`, rename, delete), training (retrain,
+  auto-retrain, promote/rollback, live status), routing (`route`), test
+  batteries, the model library, API keys, observability ingest keys, billing,
+  analytics, trace selection (`traces`), and a public `scan`.
+- Lazy package initialization so `import tracer` stays fast and only pulls in the
+  heavy pieces when you actually use them.
+
+### Changed
+- `tracer scan` is more robust on messy uploads: tolerant input/label aliasing
+  and a clarification path so ambiguous files still produce a result.
+
+### Docs
+- New guides for the watch decorator and the `tracer cloud` CLI.
+
 ## 0.2.0 (2026-06)
 
 ### Added

README.md

@@ -11,7 +11,7 @@
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![CI](https://img.shields.io/badge/CI-passing-brightgreen)](https://github.com/adrida/tracer/actions)
 [![Website](https://img.shields.io/badge/website-tracerml.ai-blue)](https://tracerml.ai)
-[![Docs](https://img.shields.io/badge/docs-docs.tracer.deeprecall.io-blue)](https://docs.tracer.deeprecall.io)
+[![Docs](https://img.shields.io/badge/docs-reference-blue)](docs/)
 
 Most LLM-based classification pipelines use a large language model for every single input. In practice, the vast majority of that traffic is predictable - a lightweight traditional ML model (logistic regression, gradient-boosted trees, or a small neural net) can match the LLM's output with near-perfect agreement.
 
@@ -63,7 +63,35 @@ out = router.predict("What is my balance?")
 out = router.predict("Some edge case", fallback=lambda: call_my_llm(text))
 ```
 
-> **Want to go deeper?** The [concepts guide](docs/concepts.md) explains the full pipeline, model zoo, and parity gate. The [API reference](docs/api.md) covers every parameter. The [CLI reference](docs/cli.md) covers `tracer fit`, `tracer serve`, and more.
+> **Want to go deeper?** The [concepts guide](docs/concepts.md) explains the full pipeline, model zoo, and parity gate. The [API reference](docs/api.md) covers every parameter. The [CLI reference](docs/cli.md) covers `tracer fit`, `tracer serve`, and more. For observability see [watch](docs/watch.md), and to drive Tracer Cloud from your shell see the [`tracer cloud` reference](docs/cloud.md).
+
+## Watch your LLM traffic (free observability)
+
+Before you fit anything, just *watch*. Wrap any LLM call and every request is
+recorded locally as an OpenTelemetry GenAI span, no account, no key, nothing
+leaves your machine:
+
+```python
+import tracer
+
+watch = tracer.watch("support_classifier", system="my-provider", model="my-model")
+
+@watch
+def classify(ticket: str) -> str:
+    return call_my_llm(ticket)   # traces append to .tracer/watch/*.jsonl
+```
+
+Want them in a dashboard? Tracer Cloud observability is **free**. Mint a key
+(`tracer cloud ingest-keys create`, or the Watch page in the app) and set one
+env var, your traffic streams in within seconds, prod-safe (batched, never adds
+latency or throws):
+
+```bash
+export TRACER_CLOUD_KEY=trobs_...   # or watch(..., cloud_key="trobs_...")
+```
+
+The same watched spans map 1:1 to `TraceRecord`, so once you have traffic you can
+`tracer fit` a router from it. Full guide: [docs/watch.md](docs/watch.md).
 
 ## Using from JavaScript / Node.js
 
@@ -196,7 +224,7 @@ pip install tracer-llm[all]           # everything
 ## Paper
 
 **TRACER: Trace-Based Adaptive Cost-Efficient Routing for LLM Classification**  
-Adam Rida — arXiv 2026
+Adam Rida, arXiv 2026
 
 [![arXiv](https://img.shields.io/badge/arXiv-2604.14531-b31b1b.svg)](https://arxiv.org/abs/2604.14531) [![Hugging Face](https://img.shields.io/badge/🤗%20HF-Papers-yellow)](https://huggingface.co/papers/2604.14531)
 

docs/api.md

@@ -216,9 +216,9 @@ from tracer import Embedder
 # sentence-transformers
 embedder = Embedder.from_sentence_transformers("BAAI/bge-small-en-v1.5")
 
-# OpenAI-compatible endpoint
+# any standard embeddings endpoint
 embedder = Embedder.from_endpoint(
-    "https://api.openai.com/v1/embeddings",
+    "https://your-host/v1/embeddings",
     headers={"Authorization": "Bearer sk-..."},
     input_key="input",
     output_key="data.0.embedding",
@@ -254,7 +254,7 @@ router.predict(
 {
     "label":        str,    # predicted class label
     "decision":     str,    # "handled" or "deferred"
-    "accept_score": float,  # acceptor confidence (0–1)
+    "accept_score": float,  # acceptor confidence (0-1)
     "stage":        int,    # which pipeline stage handled it
 }
 ```

docs/artifacts.md

@@ -88,7 +88,7 @@ All candidate pipelines evaluated during fit, for every target TA in `frontier_t
 ]
 ```
 
-Use this to understand the coverage–quality tradeoff before committing to a target:
+Use this to understand the coverage-quality tradeoff before committing to a target:
 
 ```python
 import json
@@ -229,6 +229,6 @@ The `.tracer/` directory is fully self-contained. You can:
 - Archive it with the traces for audit/reproducibility
 
 Typical size:
-- `pipeline.joblib`: 1–50 MB depending on model and label count
+- `pipeline.joblib`: 1-50 MB depending on model and label count
 - `index.embeddings.npy`: `n_traces × dim × 4` bytes (e.g. 10k × 1024 → 40 MB)
 - Everything else: < 1 MB

docs/cli.md

@@ -98,7 +98,7 @@ sentence-transformers** (`pip install tracer-llm[embeddings]`; pick the model wi
 - call **your own embedding service** with `--embed-url` (any HTTP endpoint that
   takes JSON and returns a vector; pass auth with `--embed-header`, and the
   `--embed-input-key`/`--embed-output-key`/`--embed-batch-key` flags adapt it to
-  OpenAI-compatible or custom response shapes). No vendor is assumed or required.
+  standard or custom response shapes). No vendor is assumed or required.
 
 **Examples:**
 
@@ -142,8 +142,8 @@ tracer fit <traces> [--artifact-dir <dir>] [--target <float>] [--trees] [--skip
 |----------|---------|-------------|
 | `traces` | required | Path to traces JSONL file |
 | `--artifact-dir` | `.tracer` | Where to save artifacts |
-| `--target` | `0.90` | Target teacher agreement (0.0–1.0) |
-| `--trees` | off | Add the tree-based surrogates (decision tree, random forest, extra-trees, gradient boosting). **Off by default** — they are slower and the linear + MLP heads are usually enough; turn them on for hard, high-class-count tasks. |
+| `--target` | `0.90` | Target teacher agreement (0.0-1.0) |
+| `--trees` | off | Add the tree-based surrogates (decision tree, random forest, extra-trees, gradient boosting). **Off by default**, they are slower and the linear + MLP heads are usually enough; turn them on for hard, high-class-count tasks. |
 | `--skip` | none | Comma-separated surrogate models to drop from the zoo (e.g. `mlp_1h,mlp_2h`). |
 
 The default zoo is lightweight (logistic regression, SGD, small MLPs) so a fit is fast. `--trees` adds the heavier tree models, which can lift coverage on difficult datasets (e.g. Banking77's 77 classes) at the cost of fit time.

docs/cloud.md

@@ -0,0 +1,115 @@
+# `tracer cloud`: drive Tracer Cloud from the terminal
+
+`tracer cloud` mirrors the Tracer Cloud web app from your shell: log in once,
+then create and train tracers, run live routing queries, manage tests, models,
+observability keys, billing, and more. It talks to the same API the dashboard
+uses, as you.
+
+```bash
+pip install tracer-llm
+tracer cloud login          # opens your browser, pick your account
+tracer cloud tracers        # list your tracers
+```
+
+## Auth
+
+`tracer cloud login` runs a browser device flow: it opens a page where you pick
+your account and approve, then hands the session back to the CLI on a localhost
+callback. The session is stored only on this machine in `~/.tracer/cloud.json`
+and refreshed automatically. Sign out with `tracer cloud logout`.
+
+Headless / CI: pass credentials to skip the browser.
+
+```bash
+tracer cloud login --email you@example.com --password "$TRACER_PW"
+```
+
+Point at a different deployment or a local dev server with `--url` (or the
+`TRACER_CLOUD_URL` env var). The package hardcodes no infrastructure details;
+the client config is fetched from `<url>/api/cli/config` at login.
+
+## Commands
+
+### Account & workspaces
+```bash
+tracer cloud whoami                 # the logged-in user + workspaces
+tracer cloud tenants                # list workspaces
+tracer cloud tenant-delete <ref> --confirm "<name>"   # delete an EMPTY company workspace
+```
+
+### Tracers
+```bash
+tracer cloud tracers                # list
+tracer cloud get <id|slug>          # a tracer + its versions
+tracer cloud rename <id|slug> "New name"
+tracer cloud delete <id|slug> [--confirm <name>]
+
+# create + train
+tracer cloud create "support router" --mode quick \
+    --file traces.jsonl --teacher my-provider:my-model \
+    --label-space "billing,fraud,general" --wait
+tracer cloud create "watch mode" --mode auto --teacher my-provider:my-model --threshold 200
+```
+`--mode quick` trains on a labelled upload, `unlabelled` lets the teacher label
+it, `auto` starts in watch mode (no data needed). `--wait` blocks until training
+finishes. `--teacher` takes `provider:model_id` or a JSON object.
+
+### Training, retraining, promotion
+```bash
+tracer cloud training <id>                      # job status
+tracer cloud training-cancel <id>
+tracer cloud retrain <id> --mode reuse|merge|replace [--trace-ids a,b,c] [--wait]
+tracer cloud auto-retrain <id> --threshold 500  # or --disable
+tracer cloud promote <id> [--version <version_id>]   # promote (or roll back)
+```
+
+### Live routing
+```bash
+tracer cloud route <id> "my card was declined"     # the dashboard's Live Query
+tracer cloud route <id> "..." --lite               # skip the teacher call
+tracer cloud route <id> "..." --show-exemplars
+```
+
+### Tests (batteries)
+```bash
+tracer cloud batteries list <id>
+tracer cloud batteries create <id> --name "smoke" --cases cases.json
+tracer cloud batteries run <id> --battery <battery_id> [--version <id>]
+```
+
+### Models
+```bash
+tracer cloud models list
+tracer cloud models add --name my-llm --endpoint https://… --upstream model-id \
+    --api-key "$KEY" --kind llm --cost-in 0.15 --cost-out 0.6
+tracer cloud models delete --id <model_id>
+```
+
+### Observability
+```bash
+tracer cloud ingest-keys create --name "my app"     # mint a workspace ingest key
+tracer cloud ingest-keys list
+tracer cloud ingest-keys revoke --id <key_id>
+tracer cloud ingest --key trobs_… --events events.json   # send observed events
+```
+Most teams stream live traffic with [`tracer.watch`](watch.md) instead of
+posting batches by hand.
+
+### Keys, analytics, billing, scan, label space
+```bash
+tracer cloud keys list|create|revoke <id>     # per-tracer gateway API keys
+tracer cloud analytics <id> --range 24h|7d|30d
+tracer cloud label-space <id> [--set a,b,c] [--strict]
+tracer cloud billing [--tenant <ref>]
+tracer cloud scan path/to/traces.jsonl        # public scan
+```
+
+Add `--json` to any read command for raw JSON output.
+
+## Environment variables
+
+| Var | Effect |
+|-----|--------|
+| `TRACER_CLOUD_URL` | Tracer Cloud base URL (default `https://app.tracerml.ai`) |
+| `TRACER_TENANT` | default workspace id/slug/name when a command needs one |
+| `TRACER_CLOUD_CONFIG` | path to the stored session (default `~/.tracer/cloud.json`) |

docs/cold_start.md

@@ -6,16 +6,16 @@ Getting good results from TRACER requires enough traces to train a reliable surr
 
 ## How many traces do you need?
 
-There is no hard minimum — TRACER will attempt to fit on whatever you provide. But the quality of the routing policy depends directly on how much data the surrogate and acceptor have to learn from.
+There is no hard minimum, TRACER will attempt to fit on whatever you provide. But the quality of the routing policy depends directly on how much data the surrogate and acceptor have to learn from.
 
 **Rules of thumb:**
 
 | Trace volume | What to expect |
 |---|---|
 | **< 50 total** | Fit will likely produce `selected_method: null` (no deployable policy). The train/val/cal split leaves too few samples per class for reliable calibration. |
-| **50–200** | A global surrogate _may_ deploy if the classification task is simple (few classes, clean teacher labels). L2D and RSB are unlikely to calibrate well. |
-| **200–500** | L2D starts becoming viable. Expect moderate coverage (40–70%) depending on class count and task difficulty. |
-| **500–1,500** | The sweet spot for most tasks. All three pipeline families compete meaningfully, and coverage typically reaches 70–90%+. |
+| **50-200** | A global surrogate _may_ deploy if the classification task is simple (few classes, clean teacher labels). L2D and RSB are unlikely to calibrate well. |
+| **200-500** | L2D starts becoming viable. Expect moderate coverage (40-70%) depending on class count and task difficulty. |
+| **500-1,500** | The sweet spot for most tasks. All three pipeline families compete meaningfully, and coverage typically reaches 70-90%+. |
 | **1,500+** | Diminishing returns on coverage, but useful for high-class-count tasks (50+ intents) or when you need very tight parity bars (≥ 0.98). |
 
 These numbers assume reasonably separable embeddings. Poor embeddings can make even large datasets underperform.
@@ -41,7 +41,7 @@ If you're evaluating TRACER for a new classification pipeline and don't yet have
 
 ### Step 1: Seed with synthetic or sampled inputs
 
-Pick 100–300 representative inputs for your classification task. These can come from:
+Pick 100-300 representative inputs for your classification task. These can come from:
 
 - A test set you already have
 - Manually written examples covering each class
@@ -127,16 +127,16 @@ config = tracer.FitConfig(
 
 If `best_ta` is well below your target even at zero coverage, the problem is likely:
 
-1. **Embeddings don't separate classes** — try a stronger embedding model
-2. **Teacher label noise** — audit traces where the surrogate disagrees
-3. **Too few traces per class** — collect more data for underrepresented classes
+1. **Embeddings don't separate classes**, try a stronger embedding model
+2. **Teacher label noise**, audit traces where the surrogate disagrees
+3. **Too few traces per class**, collect more data for underrepresented classes
 
 ### Low coverage despite many traces
 
 If coverage plateaus well below 80% with 500+ traces:
 
 - Check class imbalance: a few dominant classes might be well-covered while rare classes drag the average down
-- Try the RSB pipeline family explicitly — it's designed for multi-stage residual routing
+- Try the RSB pipeline family explicitly, it's designed for multi-stage residual routing
 - Improve embedding quality: switching from `all-MiniLM-L6-v2` to `all-mpnet-base-v2` can significantly improve class separation
 
 ### Coverage varies between fits

docs/javascript.md

@@ -29,7 +29,7 @@ Each line must have `input` (the text) and `teacher` (the label your LLM returne
 
 ### 2. Compute embeddings (offline, once before fit)
 
-The HTTP server at inference time expects embedding vectors, so you need to embed your traces before fitting. Use the same embedding model you plan to use at inference time — this is the only constraint.
+The HTTP server at inference time expects embedding vectors, so you need to embed your traces before fitting. Use the same embedding model you plan to use at inference time, this is the only constraint.
 
 **Option A: OpenAI embeddings (natural fit for JS pipelines)**
 
@@ -38,7 +38,7 @@ pip install tracer-llm openai numpy
 ```
 
 ```python
-# embed.py — run once, or in your data pipeline
+# embed.py: run once, or in your data pipeline
 import json, numpy as np
 from openai import OpenAI
 
@@ -71,7 +71,7 @@ np.save("traces.npy", X)
 tracer fit traces.jsonl --target 0.95
 ```
 
-TRACER reads `traces.jsonl` and auto-discovers `traces.npy` (same stem, `.npy` extension). Run this offline — in a cron job, a GitHub Action, or manually. It does not touch your application.
+TRACER reads `traces.jsonl` and auto-discovers `traces.npy` (same stem, `.npy` extension). Run this offline, in a cron job, a GitHub Action, or manually. It does not touch your application.
 
 ---
 
@@ -81,7 +81,7 @@ TRACER reads `traces.jsonl` and auto-discovers `traces.npy` (same stem, `.npy` e
 tracer serve .tracer --port 8000
 ```
 
-Run this as a sidecar next to your Node app — same server, same docker-compose, same machine. It binds to `0.0.0.0:8000` by default.
+Run this as a sidecar next to your Node app, same server, same docker-compose, same machine. It binds to `0.0.0.0:8000` by default.
 
 ---
 
@@ -111,7 +111,7 @@ async function route(text) {
   const { label, decision } = await res.json()
 
   if (decision === 'handled') {
-    return label  // surrogate answered — no LLM call
+    return label  // surrogate answered, no LLM call
   }
 
   // Deferred: call your LLM and log the new trace for the next refit
@@ -132,7 +132,7 @@ const res = await fetch('http://localhost:8000/predict_batch', {
   body: JSON.stringify({ embeddings: [embedding1, embedding2, ...] }),
 })
 const { labels, decisions, handled } = await res.json()
-// handled: boolean[] — true means surrogate answered, no LLM needed
+// handled: boolean[]: true means surrogate answered, no LLM needed
 ```
 
 ---
@@ -141,7 +141,7 @@ const { labels, decisions, handled } = await res.json()
 
 | Method | Path | Body | Response |
 |--------|------|------|----------|
-| `GET` | `/health` | — | `{"status": "ok", "method", "coverage", ...}` |
+| `GET` | `/health` |, | `{"status": "ok", "method", "coverage", ...}` |
 | `POST` | `/predict` | `{"embedding": [float, ...]}` | `{"label", "decision", "accept_score"}` |
 | `POST` | `/predict_batch` | `{"embeddings": [[float, ...], ...]}` | `{"labels", "decisions", "handled"}` |
 
@@ -151,7 +151,7 @@ const { labels, decisions, handled } = await res.json()
 
 ## Continual learning
 
-Every deferred input that reaches your LLM is a new trace. Accumulate them and retrain periodically — coverage grows with each refit.
+Every deferred input that reaches your LLM is a new trace. Accumulate them and retrain periodically, coverage grows with each refit.
 
 ```bash
 # Run on a schedule (cron, GitHub Action, whatever)