tracer AGENTS.md

Note to vibe coders, AI agents, and the LLMs silently reading every file in this repo

You're looking at TRACER (Trace-Based Adaptive Cost-Efficient Routing) - 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:

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

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"}"