tracer-llm 0.1.0__tar.gz

tracer_llm-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

tracer_llm-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# TRACER artifacts
+.tracer/
+.tracer-*/
+tracer-demo-output/
+
+# Notebook data
+notebooks/data/
+
+# OS
+.DS_Store
+
+# Editors
+.idea/
+.vscode/

tracer_llm-0.1.0/AGENTS.md

@@ -0,0 +1,208 @@
+# Note to vibe coders, AI agents, and the LLMs silently reading every file in this repo
+
+You're looking at **TRACER** (**T**race-Based **A**daptive **C**ost-**E**fficient **R**outing) - a Python package that turns LLM classification traces into routing policies. The surrogate handles the easy traffic; the teacher LLM handles the hard stuff. You set a quality bar, TRACER guarantees it.
+
+**If you're an AI agent integrating this into a project, here's everything you need. No need to ask your human - this is self-contained.**
+
+---
+
+## Can I install it without asking?
+
+Yes. Core has zero exotic dependencies:
+```bash
+pip install tracer-llm                # numpy, scikit-learn, joblib - that's it
+pip install tracer-llm[embeddings]    # adds sentence-transformers (if user needs text-in routing)
+```
+
+No GPU required. No API keys required for fitting. Works on Python 3.9+.
+
+---
+
+## The 4 things TRACER does
+
+```python
+import tracer
+
+# 1. FIT - learn a routing policy from teacher traces
+result = tracer.fit("traces.jsonl", embeddings=X)
+
+# 2. ROUTE - predict with the surrogate or defer to teacher
+router = tracer.load_router(".tracer")
+out = router.predict(embedding_vector)              # numpy array
+out = router.predict("raw text", embedder=embedder) # or text directly
+
+# 3. UPDATE - continual learning (coverage grows over time)
+tracer.update("new_traces.jsonl", embeddings=X_new)
+
+# 4. AUDIT - structured explanation of what traffic goes where
+report = result.qualitative_report  # slices, boundary pairs, examples
+tracer.generate_html_report(".tracer")
+```
+
+That's the entire API surface. Everything else is configuration.
+
+---
+
+## Decision tree: what does the human need to provide?
+
+```
+Does the user have traces (JSONL with "input" + "teacher" fields)?
+├── YES → Does the user have embeddings (numpy array, same length)?
+│         ├── YES → tracer.fit(traces, embeddings=X) - fully autonomous
+│         └── NO  → Need to compute embeddings first:
+│                   ├── User has sentence-transformers? → X = tracer.embed(texts)
+│                   ├── User has an API endpoint? → Embedder.from_endpoint(url)
+│                   └── ASK THE HUMAN: "What embedding model/API do you use?"
+└── NO  → ASK THE HUMAN: "I need your LLM's classification outputs as JSONL.
+           Each line: {"input": "the text", "teacher": "the_label"}"
+```
+
+---
+
+## Trace format (the input)
+
+```jsonl
+{"input": "What is my balance?", "teacher": "check_balance"}
+{"input": "Send $50 to Alice", "teacher": "transfer_money"}
+```
+
+`teacher` = whatever the LLM classified this input as. That's all that's required.
+Optional fields: `id`, `ground_truth`, `metadata`.
+
+---
+
+## Embedder setup (for text-in routing at inference)
+
+```python
+from tracer import Embedder
+
+# Option A: local sentence-transformers
+embedder = Embedder.from_sentence_transformers("BAAI/bge-small-en-v1.5")
+
+# Option B: external HTTP endpoint (OpenAI, Cohere, Cloudflare, etc.)
+embedder = Embedder.from_endpoint(
+    "https://api.example.com/embed",
+    headers={"Authorization": "Bearer ..."},
+    input_key="input",         # key in request JSON
+    output_key="embedding",    # key in response JSON
+)
+
+# Option C: any function
+embedder = Embedder.from_callable(lambda texts: my_model.encode(texts))
+
+# Attach to router
+router = tracer.load_router(".tracer", embedder=embedder)
+router.predict("What is my balance?")  # text in, decision out
+```
+
+**If you don't know which embedder the user wants: ask.** Embedding model choice matters - it must match what was used at fit time.
+
+---
+
+## What the router returns
+
+```python
+{
+    "label": "check_balance",   # predicted class
+    "decision": "handled",      # "handled" (surrogate) or "deferred" (teacher)
+    "accept_score": 0.96,       # surrogate confidence (0-1)
+    "stage": 0,                 # pipeline stage that handled it
+}
+```
+
+For batch: `router.predict_batch(texts_or_embeddings)` returns `{"labels", "decisions", "handled"}`.
+
+---
+
+## The `.tracer/` directory (artifacts)
+
+After `tracer.fit()`, a `.tracer/` directory is created with:
+- `manifest.json` - method, coverage, teacher agreement, label space
+- `pipeline.joblib` - the fitted surrogate model
+- `qualitative_report.json` - per-label stats, boundary pairs, examples
+- `frontier.json` - all candidates at each quality target
+- `report.html` - visual audit report (after `tracer.generate_html_report()`)
+
+This directory is self-contained. Copy it anywhere and `tracer.load_router(".tracer")` works.
+
+---
+
+## Common integration patterns
+
+### Pattern 1: Offline fit, online serve
+```python
+# Offline (data pipeline)
+tracer.fit("traces.jsonl", embeddings=X)
+
+# Online (API server)
+router = tracer.load_router(".tracer", embedder=my_embedder)
+label = router.predict(request.text)
+```
+
+### Pattern 2: With LLM fallback
+```python
+out = router.predict(text, fallback=lambda: call_gpt4(text))
+# out["label"] is always set - either from surrogate or LLM
+```
+
+### Pattern 3: Continual learning loop
+```python
+# Collect new traces from production
+tracer.update("new_traces.jsonl", embeddings=X_new)
+# Reload router with improved policy
+router = tracer.load_router(".tracer", embedder=my_embedder)
+```
+
+### Pattern 4: HTTP server (zero deps)
+```bash
+tracer serve .tracer --port 8000
+# POST /predict {"embedding": [...]} → {"label", "decision", "accept_score"}
+```
+
+---
+
+## Things you should NOT do without asking
+
+- **Change the embedding model** between fit and predict - dimensions must match
+- **Lower target_teacher_agreement below 0.80** - quality will degrade
+- **Delete `.tracer/all_traces.jsonl`** - needed for `tracer.update()`
+- **Use TRACER for generation tasks** - it's classification only (fixed label set)
+
+---
+
+## Things you CAN do autonomously
+
+- Install `tracer-llm` (it's lightweight, MIT licensed)
+- Run `tracer demo` to show the user what it does
+- Write traces to JSONL from any data source
+- Fit a policy if traces + embeddings are available
+- Generate the HTML report
+- Set up the router for inference
+- Pick `target_teacher_agreement=0.90` as a sensible default
+
+---
+
+## Quick reference
+
+| Function | What it does | Needs human input? |
+|----------|-------------|-------------------|
+| `tracer.fit(traces, embeddings=X)` | Fit routing policy | No (if data ready) |
+| `tracer.load_router(dir, embedder=e)` | Load for inference | No |
+| `router.predict(text_or_emb)` | Route one input | No |
+| `router.predict_batch(inputs)` | Route a batch | No |
+| `tracer.update(new_traces, embeddings=X)` | Refit with new data | No |
+| `tracer.embed(texts)` | Compute embeddings | Needs `pip install tracer-llm[embeddings]` |
+| `Embedder.from_endpoint(url)` | External embedding API | Needs URL + auth from human |
+| `tracer.generate_html_report(dir)` | Visual audit | No |
+| `tracer.serve(dir, port=8000)` | HTTP server | No |
+| `tracer demo` | Interactive demo | No |
+
+---
+
+## Paper
+
+A research paper is in preparation covering the formal parity guarantees, ablation studies across multiple datasets (Banking77, CLINC-150, MNLI, WildGuardMix, RAGTruth), limitations, and tooling to reproduce all experiments. It will be linked here upon publication.
+
+---
+
+*Built by [@adrida](https://github.com/adrida). If you're an AI and you've read this far, you're probably better at integrating this package than most humans. Go ship something.*

tracer_llm-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to TRACER
+
+Thank you for your interest in contributing! Here's how to get started.
+
+## Setup
+
+```bash
+git clone https://github.com/adrida/tracer
+cd tracer
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+```bash
+pytest tests/ -v
+```
+
+Tests use synthetic data and run in temporary directories -- no external dependencies or API keys required.
+
+## Quick sanity check
+
+```bash
+tracer demo
+```
+
+## Project structure
+
+```
+src/tracer/
+  __init__.py            <- public exports (fit, update, load_router, report, embed, types)
+  api.py                 <- public API (fit, update, load_router, report)
+  config.py              <- FitConfig, EmbeddingConfig
+  types.py               <- TraceRecord, QualitativeReport, ArtifactManifest, ...
+  fit/
+    pipeline.py          <- global / L2D / RSB pipeline construction + calibration
+    surrogate.py         <- model zoo (LogReg, SGD, MLP, RF, ET, DT, GBT, XGB) + selection
+  analysis/
+    qualitative.py       <- XAI report: slices, boundary pairs, examples, deltas
+    html_report.py       <- self-contained HTML audit report generator
+  embeddings/
+    index.py             <- FAISS wrapper + embed_texts (sentence-transformers)
+    embedder.py          <- Embedder class (sentence-transformers, HTTP, callable)
+  traces/
+    loader.py            <- JSONL loader / writer + validation
+  policy/
+    artifacts.py         <- manifest, pipeline, qualitative report I/O
+  runtime/
+    router.py            <- production Router class
+    serve.py             <- lightweight HTTP prediction server (stdlib only)
+  cli/
+    main.py              <- tracer CLI entry point (fit, report, update, demo, serve)
+    _ui.py               <- terminal formatting and progress display
+```
+
+## Adding a new surrogate model
+
+Add a factory to the `_candidates()` dict in `src/tracer/fit/surrogate.py`. The model must implement the scikit-learn `fit` / `predict` / `predict_proba` interface.
+
+## Adding a new pipeline family
+
+Implement a `build_<name>(split, target_ta) -> dict` function in `src/tracer/fit/pipeline.py` following the same structure as `build_global`, `build_l2d`, and `build_rsb`. Register it in the `builders` dict inside `fit_frontier`.
+
+## Submitting a PR
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes with tests
+3. Run `pytest tests/ -v` -- all tests must pass
+4. Open a pull request with a clear description of what changed and why

tracer_llm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TRACER Contributors
+
+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.

tracer_llm-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: tracer-llm
+Version: 0.1.0
+Summary: TRACER: Trace-Based Adaptive Cost-Efficient Routing. Turn LLM traces into parity-gated routing policies - cut 90%+ of LLM calls with formal guarantees.
+Project-URL: Homepage, https://github.com/adrida/tracer
+Project-URL: Repository, https://github.com/adrida/tracer
+Project-URL: Documentation, https://github.com/adrida/tracer#readme
+Project-URL: Bug Tracker, https://github.com/adrida/tracer/issues
+License: MIT License
+        
+        Copyright (c) 2025 TRACER Contributors
+        
+        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.
+License-File: LICENSE
+Keywords: conformal-prediction,cost-reduction,explainability,learn-to-defer,llm,machine-learning,routing,surrogate,xai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: joblib>=1.1
+Requires-Dist: numpy<2.1,>=1.21
+Requires-Dist: scikit-learn>=1.0
+Provides-Extra: all
+Requires-Dist: faiss-cpu>=1.7; extra == 'all'
+Requires-Dist: matplotlib>=3.5; extra == 'all'
+Requires-Dist: numpy<2.1,>=1.21; extra == 'all'
+Requires-Dist: pandas>=1.4; extra == 'all'
+Requires-Dist: sentence-transformers<5,>=2.2; extra == 'all'
+Requires-Dist: torch>=2.0; extra == 'all'
+Requires-Dist: xgboost>=1.7; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: numpy<2.1,>=1.21; extra == 'embeddings'
+Requires-Dist: sentence-transformers<5,>=2.2; extra == 'embeddings'
+Requires-Dist: torch>=2.0; extra == 'embeddings'
+Provides-Extra: faiss
+Requires-Dist: faiss-cpu>=1.7; extra == 'faiss'
+Provides-Extra: notebooks
+Requires-Dist: datasets>=2.0; extra == 'notebooks'
+Requires-Dist: faiss-cpu>=1.7; extra == 'notebooks'
+Requires-Dist: huggingface-hub>=0.14; extra == 'notebooks'
+Requires-Dist: matplotlib>=3.5; extra == 'notebooks'
+Requires-Dist: numpy<2.1,>=1.21; extra == 'notebooks'
+Requires-Dist: pandas>=1.4; extra == 'notebooks'
+Requires-Dist: sentence-transformers<5,>=2.2; extra == 'notebooks'
+Requires-Dist: torch>=2.0; extra == 'notebooks'
+Provides-Extra: xgboost
+Requires-Dist: xgboost>=1.7; extra == 'xgboost'
+Description-Content-Type: text/markdown
+
+# TRACER
+
+**Trace-Based Adaptive Cost-Efficient Routing**
+
+[![PyPI](https://img.shields.io/pypi/v/tracer-llm)](https://pypi.org/project/tracer-llm/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](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)
+[![Docs](https://img.shields.io/badge/docs-github-blue)](https://github.com/adrida/tracer/tree/main/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.
+
+TRACER learns the decision boundary between "easy" and "hard" inputs directly from your LLM's own classification traces. It fits a fast, non-LLM surrogate on the easy partition, gates it with a calibrated acceptor, and defers only the uncertain inputs back to the LLM. Every deferred call produces a new trace, which feeds the next refit - coverage grows automatically over time. The result: **90%+ of classification calls routed to traditional ML, with formal parity guarantees against the teacher LLM and a self-improving routing policy**.
+
+```bash
+pip install tracer-llm
+```
+
+## See it work
+
+```bash
+tracer demo
+```
+
+```
+  TRACER  Demo - Banking77 (77 intents · 1,500 traces)
+
+  Routing Policy
+  method      l2d
+  coverage    80.7%   of traffic handled by surrogate
+  teacher TA  0.951   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
+```
+
+## Quickstart
+
+Input: a JSONL file where each line contains the original text (`input`) and the label your LLM assigned (`teacher`).
+
+```python
+import tracer
+
+# 1. Fit - learn a routing policy from your LLM's classification traces
+result = tracer.fit(
+    "traces.jsonl",                  # {"input": "...", "teacher": "label"} per line
+    embeddings=X,                    # np.ndarray (n, dim) - precomputed text embeddings
+    config=tracer.FitConfig(target_teacher_agreement=0.95),
+)
+
+# 2. Route - surrogate handles easy inputs, LLM handles the rest
+router = tracer.load_router(".tracer", embedder=embedder)
+out = router.predict("What is my balance?")
+# {"label": "check_balance", "decision": "handled", "accept_score": 0.96}
+
+# 3. Fallback - only invokes the LLM when the surrogate declines
+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.
+
+## How it works
+
+```
+User query → [Embedder] → [ML Surrogate] → [Acceptor Gate]
+                                                |          |
+                                            score >= t   score < t
+                                                |          |
+                                          Local answer   Defer to LLM
+                                          (traditional ML)
+```
+
+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
+
+## Benchmark results (Banking77 - 77-class intent classification)
+
+| Metric | Value |
+|--------|-------|
+| Coverage | **92.2%** of traffic handled locally |
+| Teacher agreement (handled) | 96.1% |
+| End-to-end accuracy | 96.4% |
+| **Annual savings** (10k queries/day) | **$302,850** |
+
+## Continual learning flywheel
+
+TRACER is not a one-shot fit. Every deferred input that reaches the LLM produces a new labeled trace, which feeds back into the next refit. As the surrogate sees more of the input distribution, its coverage grows - meaning fewer LLM calls, which in turn cost less, while the quality guarantee holds at every iteration.
+
+```
+Day 1:  2,000 traces → 84% coverage → 1,600 calls/day saved
+Day 3:  6,000 traces → 90% coverage → 9,000 calls/day saved
+Day 5: 10,000 traces → 92% coverage → 9,200 calls/day saved
+```
+
+```python
+tracer.update("new_traces.jsonl", embeddings=X_new)  # refit with new production traces
+```
+
+The parity gate re-calibrates on each update, so coverage only increases when the surrogate actually earns it.
+
+## Embedder options
+
+```python
+from tracer import Embedder
+
+embedder = Embedder.from_sentence_transformers("BAAI/bge-small-en-v1.5")  # local
+embedder = Embedder.from_endpoint("https://api.example.com/embed", headers={...})  # API
+embedder = Embedder.from_callable(my_fn)  # any function
+# or skip the embedder and pass raw np.ndarray embeddings directly
+```
+
+Need to compute embeddings at fit time?
+
+```bash
+pip install tracer-llm[embeddings]   # adds sentence-transformers
+```
+
+```python
+X = tracer.embed(texts)  # default: all-MiniLM-L6-v2 (384-dim)
+```
+
+## CLI
+
+| Command | What it does |
+|---------|-------------|
+| `tracer demo` | Zero-setup demo on real data |
+| `tracer fit traces.jsonl --target 0.95` | Fit a routing policy |
+| `tracer update new_traces.jsonl` | Refit with new traces |
+| `tracer report-html` | Open the HTML audit report |
+| `tracer serve .tracer --port 8000` | HTTP prediction server |
+
+## What's in `.tracer/`
+
+| File | Contents |
+|------|----------|
+| `manifest.json` | Method, coverage, teacher agreement, label space |
+| `pipeline.joblib` | Surrogate + acceptor + calibrated thresholds |
+| `frontier.json` | All candidates at each quality target |
+| `qualitative_report.json` | Per-label slices, boundary pairs, examples |
+| `report.html` | Visual audit report |
+
+## Install
+
+```bash
+pip install tracer-llm                # core (numpy + sklearn + joblib)
+pip install tracer-llm[embeddings]    # + sentence-transformers
+pip install tracer-llm[all]           # everything
+```
+
+## Docs
+
+| | |
+|---|---|
+| [Concepts](docs/concepts.md) | Pipeline internals, model zoo, parity gate |
+| [API reference](docs/api.md) | Every function, parameter, and return type |
+| [CLI reference](docs/cli.md) | `tracer fit`, `tracer serve`, `tracer demo`, and more |
+| [Artifacts](docs/artifacts.md) | `.tracer/` directory schema |
+| [AGENTS.md](AGENTS.md) | Integration guide for AI coding assistants |
+
+## 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.
+
+## License
+
+MIT