@@ -3,6 +3,7 @@
 **Trace-Based Adaptive Cost-Efficient Routing**
 
 [![PyPI](https://img.shields.io/pypi/v/tracer-llm)](https://pypi.org/project/tracer-llm/)
+[![Downloads](https://static.pepy.tech/badge/tracer-llm/month)](https://pepy.tech/project/tracer-llm)
 [![Python](https://img.shields.io/pypi/pyversions/tracer-llm)](https://pypi.org/project/tracer-llm/)
 [![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)
@@ -27,12 +28,12 @@ tracer demo
 
   Routing Policy
   method      l2d
-  coverage    80.7%   of traffic handled by surrogate
-  teacher TA  0.951   surrogate matches teacher on handled traffic
+  coverage    91.4%   of traffic handled by surrogate
+  teacher TA  0.920   surrogate matches teacher on handled traffic
 
   Cost Projection (10k queries/day)
       Without TRACER   10,000 LLM calls/day   $20.00/day
-      With TRACER       1,926 LLM calls/day   $ 3.85/day   $5,894 saved/yr
+      With TRACER         863 LLM calls/day   $ 1.73/day   $6,670 saved/yr
 ```
 
 ## Quickstart
@@ -71,38 +72,13 @@ User query → [Embedder] → [ML Surrogate] → [Acceptor Gate]
                                           (traditional ML)
 ```
 
-The surrogate is **not another LLM** - it is a classical ML or shallow DL model (the model zoo includes logistic regression, SGD, gradient-boosted trees, random forests, and small feed-forward nets). This is what makes the cost reduction real: inference is CPU-bound, sub-millisecond, and free.
+The surrogate is **not another LLM** - it is a classical ML or shallow DL model (the model zoo includes logistic regression, SGD, LightGBM, random forests, and small feed-forward nets). This is what makes the cost reduction real: inference is CPU-bound, sub-millisecond, and free.
 
 1. **Fit** - train a suite of candidate surrogates on your LLM's classification traces; select the best via cross-validated teacher agreement
 2. **Gate** - attach a learned acceptor that estimates, per-input, whether the surrogate will agree with the teacher
 3. **Calibrate** - sweep the acceptor threshold to maximise coverage at your target parity (e.g. ≥ 95% teacher agreement)
 4. **Guard** - block deployment if the best candidate cannot clear the parity bar on held-out data
 
-## Explainability
-
-Every fit produces a structured audit report alongside the routing policy -- not just aggregate numbers.
-
-| Report component | What it answers |
-|-----------------|-----------------|
-| **Per-label slice stats** | Which intents are fully self-serve? Which always defer? |
-| **Contrastive boundary pairs** | For each label: one handled example, one deferred -- what makes an input "easy" vs "hard"? |
-| **Representative examples** | What does typical handled/deferred traffic look like? |
-| **Temporal deltas** | Which intents improved between the last refit and this one? |
-
-```python
-result = tracer.fit("traces.jsonl", embeddings=X)
-qr = result.qualitative_report
-
-print(qr.summary)
-# "Handled 9278/10003 (92.8%) by surrogate"
-
-for bp in qr.boundary_pairs[:3]:
-    print(f"{bp.teacher_label}: handled={bp.handled_preview!r} / deferred={bp.deferred_preview!r}")
-
-# Generate self-contained HTML report
-tracer.generate_html_report(".tracer")
-```
-
 ## Benchmark results (Banking77 - 77-class intent classification)
 
 | Metric | Value |
@@ -187,18 +163,6 @@ pip install tracer-llm[all]           # everything
 | [Artifacts](docs/artifacts.md) | `.tracer/` directory schema |
 | [AGENTS.md](AGENTS.md) | Integration guide for AI coding assistants |
 
-## Prior work
-
-TRACER builds on and connects three research threads:
-
-**Learn to Defer (L2D)** -- the algorithmic backbone. The surrogate + acceptor gate architecture is grounded in Mozannar & Sontag ([ICML 2020](https://proceedings.mlr.press/v119/mozannar20b.html)), Madras et al. ([NeurIPS 2018](https://papers.nips.cc/paper_files/paper/2018/hash/09d37c08f7b129e96277388757530c72-Abstract.html)), and Mao et al. ([NeurIPS 2023](https://proceedings.neurips.cc/paper_files/paper/2023/hash/7e1bf09d2e4e6e5c5a0b63b66b47ef42-Abstract.html)).
-
-**Post-hoc calibration** -- the threshold sweep that enforces the parity guarantee follows the post-hoc deferral estimator framework of Narasimhan et al. ([ICML 2022](https://proceedings.mlr.press/v162/narasimhan22a.html)).
-
-**LLM routing** -- the problem setting is shared with Hybrid LLM (Ding et al., [ICLR 2024](https://openreview.net/forum?id=02f3mUtqnM)) and RouteLLM (Ong et al., [ICLR 2025](https://openreview.net/forum?id=sSt9fROCn2)). TRACER's distinction: it targets classification specifically, uses the teacher's own trace distribution rather than preference data, and enforces a formal parity guarantee rather than a quality heuristic.
-
-**Interpretability** -- the qualitative audit design is informed by Slice Finder (Chung et al., [ICDE 2019](https://ieeexplore.ieee.org/document/8731353)) and the contrastive explanation literature (Miller, [AIJ 2019](https://www.sciencedirect.com/science/article/pii/S0004370217301126)).
-
 ## Paper
 
 A research paper detailing the approach, formal guarantees, ablation studies, limitations, and reproducible experiment tooling is in preparation. It will be linked here upon publication.
 
@@ -35,6 +35,7 @@ result.manifest.embedding_dim            # int
 result.qualitative_report    # QualitativeReport | None
 result.notes                 # list[str], human-readable notes
 result.artifact_dir          # str
+result.get_sankey()          # generate Sankey diagram (requires tracer-llm[viz])
 ```
 
 **Example:**
@@ -378,6 +379,51 @@ webbrowser.open(f"file://{path}")
 
 ---
 
+## `tracer.generate_sankey()`
+
+Generate an interactive Sankey diagram of the routing flow.
+
+```python
+tracer.generate_sankey(
+    artifact_dir,
+    output_path=None,
+    fmt="html",
+    top_k=15,
+    title=None,
+) -> str
+```
+
+**Parameters:**
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `artifact_dir` | required | Path to `.tracer/` directory |
+| `output_path` | `<artifact_dir>/sankey.<fmt>` | Where to write the output |
+| `fmt` | `"html"` | `"html"` for interactive, `"png"`, `"svg"`, `"pdf"`, or `"jpeg"` for static |
+| `top_k` | `15` | Number of top labels to show individually (rest grouped as "other") |
+| `title` | auto-generated | Custom diagram title |
+
+**Returns:** `str` path to the generated file.
+
+**Requires:** `pip install tracer-llm[viz]`
+
+**Example:**
+
+```python
+path = tracer.generate_sankey(".tracer")
+tracer.generate_sankey(".tracer", fmt="png", output_path="routing.png")
+```
+
+Also available as a method on `FitResult`:
+
+```python
+result = tracer.fit("traces.jsonl", embeddings=X)
+result.get_sankey()                # interactive HTML
+result.get_sankey(fmt="png")       # static image
+```
+
+---
+
 ## `FitConfig`
 
 Configuration for `fit()` and `update()`.
 
@@ -13,6 +13,7 @@ tracer <command> [options]
 | `tracer update` | Refit with new traces (continual learning) |
 | `tracer report` | Print the policy manifest as JSON |
 | `tracer report-html` | Generate an HTML audit report and open it |
+| `tracer sankey` | Generate a Sankey routing flow diagram |
 | `tracer serve` | Start a prediction HTTP server |
 
 ---
@@ -208,6 +209,38 @@ The HTML is fully self-contained -- no external dependencies, works offline, can
 
 ---
 
+## `tracer sankey`
+
+Generate an interactive Sankey diagram showing how traffic flows from labels to the surrogate or teacher.
+
+```bash
+tracer sankey [<artifact-dir>] [--output <path>] [--format <fmt>] [--top-k <n>] [--no-open]
+```
+
+**Arguments:**
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `artifact-dir` | `.tracer` | Artifact directory |
+| `--output` | `<artifact-dir>/sankey.<format>` | Output path |
+| `--format` | `html` | `html` (interactive), `png`, or `svg` |
+| `--top-k` | `15` | Number of top labels to show individually |
+| `--no-open` | off | Don't open browser automatically (html only) |
+
+**Examples:**
+
+```bash
+tracer sankey
+
+tracer sankey .tracer --format png --output routing-flow.png
+
+tracer sankey --top-k 20 --no-open
+```
+
+**Requires:** `pip install tracer-llm[viz]`
+
+---
+
 ## `tracer serve`
 
 Start a lightweight HTTP prediction server (stdlib, zero extra deps).