Skip to content

Commit 3332d96

Browse files
committed
docs: add XAI section and research grounding to README and concepts
1 parent bb2d51b commit 3332d96

2 files changed

Lines changed: 40 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,31 @@ The surrogate is **not another LLM** - it is a classical ML or shallow DL model
7979
3. **Calibrate** - sweep the acceptor threshold to maximise coverage at your target parity (e.g. ≥ 95% teacher agreement)
8080
4. **Guard** - block deployment if the best candidate cannot clear the parity bar on held-out data
8181

82+
## Explainability
83+
84+
Every fit produces a structured audit report alongside the routing policy -- not just aggregate numbers.
85+
86+
| Report component | What it answers |
87+
|-----------------|-----------------|
88+
| **Per-label slice stats** | Which intents are fully self-serve? Which always defer? |
89+
| **Contrastive boundary pairs** | For each label: one handled example, one deferred -- what makes an input "easy" vs "hard"? |
90+
| **Representative examples** | What does typical handled/deferred traffic look like? |
91+
| **Temporal deltas** | Which intents improved between the last refit and this one? |
92+
93+
```python
94+
result = tracer.fit("traces.jsonl", embeddings=X)
95+
qr = result.qualitative_report
96+
97+
print(qr.summary)
98+
# "Handled 9278/10003 (92.8%) by surrogate"
99+
100+
for bp in qr.boundary_pairs[:3]:
101+
print(f"{bp.teacher_label}: handled={bp.handled_preview!r} / deferred={bp.deferred_preview!r}")
102+
103+
# Generate self-contained HTML report
104+
tracer.generate_html_report(".tracer")
105+
```
106+
82107
## Benchmark results (Banking77 - 77-class intent classification)
83108

84109
| Metric | Value |
@@ -163,6 +188,18 @@ pip install tracer-llm[all] # everything
163188
| [Artifacts](docs/artifacts.md) | `.tracer/` directory schema |
164189
| [AGENTS.md](AGENTS.md) | Integration guide for AI coding assistants |
165190

191+
## Prior work
192+
193+
TRACER builds on and connects three research threads:
194+
195+
**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)).
196+
197+
**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)).
198+
199+
**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.
200+
201+
**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)).
202+
166203
## Paper
167204

168205
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.

‎docs/concepts.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,13 +38,13 @@ A second binary classifier that predicts: "will the surrogate's prediction match
3838

3939
### Threshold calibration
4040

41-
The acceptor threshold τ is calibrated on a held-out set (not used for training). The calibration objective: find the threshold that maximizes coverage subject to teacher agreement ≥ target. This is a conformal-style guarantee: on the calibration distribution, you get the promised agreement rate.
41+
The acceptor threshold τ is calibrated on a held-out set (not used for training). The calibration objective: find the threshold that maximizes coverage subject to teacher agreement ≥ target. This is a conformal-style guarantee: on the calibration distribution, you get the promised agreement rate. The approach follows the post-hoc deferral estimator framework of Narasimhan et al. ([ICML 2022](https://proceedings.mlr.press/v162/narasimhan22a.html)).
4242

4343
---
4444

4545
## Three pipeline families
4646

47-
TRACER fits three candidate architectures and picks the one with highest coverage at your target teacher agreement.
47+
TRACER fits three candidate architectures and picks the one with highest coverage at your target teacher agreement. The L2D and RSB families are grounded in the Learn-to-Defer literature (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); Mao et al., [NeurIPS 2023](https://proceedings.neurips.cc/paper_files/paper/2023/hash/7e1bf09d2e4e6e5c5a0b63b66b47ef42-Abstract.html)).
4848

4949
### Global
5050

@@ -136,7 +136,7 @@ Coverage grows monotonically as more traces accumulate. Easy intents (tight embe
136136

137137
## Qualitative audit
138138

139-
Every fit produces a structured explanation of the routing policy:
139+
Every fit produces a structured explanation of the routing policy. The slice and boundary-pair 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)).
140140

141141
**Slice summaries**: per-label and per-length-bucket handled/deferred rates. Answers: "which parts of my label space are well-covered?"
142142

0 commit comments

Comments
 (0)