Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

perf: render the savings each source actually reported

Tejas Chopra56f809ce3987
diff --git a/headroom/perf/analyzer.py b/headroom/perf/analyzer.py
index 43d15b25d..b68224a6d 100644
--- a/headroom/perf/analyzer.py
+++ b/headroom/perf/analyzer.py
@@ -763,6 +763,52 @@ def format_report(report: PerfReport) -> str:
)
lines.append("")
+ # Savings attributed to a named source (extensions, plugins, hooks).
+ #
+ # The PERF line has carried this all along in `savings=` and the parser has
+ # decoded it into `savings_breakdown` since it was added -- but nothing ever
+ # RENDERED it, so an operator reading this report could not see that a paid
+ # extension had contributed anything at all.
+ #
+ # USD is reported next to tokens rather than folded into the headline because
+ # the two are different quantities and one source cannot produce both. A
+ # router that sends the SAME tokens to a cheaper model saves dollars and
+ # exactly zero tokens; every token-savings channel in the proxy would record
+ # it as nothing. Showing `$` beside a `0 tokens` row is the honest rendering
+ # of that, and collapsing them into one number would be an invented saving.
+ by_source: dict[tuple[str, bool], dict[str, float]] = {}
+ for record in report.perf_records:
+ for item in getattr(record, "savings_breakdown", ()) or ():
+ source = str(item.get("source") or "other")
+ realized = bool(item.get("realized", True))
+ row = by_source.setdefault(
+ (source, realized), {"events": 0, "tokens": 0, "usd": 0.0}
+ )
+ row["events"] += 1
+ raw_t, raw_u = item.get("tokens", 0), item.get("usd", 0.0)
+ row["tokens"] += max(0, int(raw_t) if isinstance(raw_t, (int, float, str)) else 0)
+ row["usd"] += float(raw_u) if isinstance(raw_u, (int, float, str)) else 0.0
+ if by_source:
+ lines.append("Savings by Source")
+ lines.append("-" * 40)
+ for (source, realized), row in sorted(
+ by_source.items(), key=lambda kv: (-kv[1]["usd"], -kv[1]["tokens"])
+ ):
+ usd = f" ${row['usd']:,.2f}" if row["usd"] else ""
+ # "projected" is not a hedge: an unrealized row is a saving the
+ # source computed against a baseline that did not run, so it cannot
+ # be reconciled against the bill the way a realized one can.
+ tag = "" if realized else " (projected)"
+ lines.append(
+ f" {source}: {int(row['events']):,} events, "
+ f"{int(row['tokens']):,} tokens{usd}{tag}"
+ )
+ lines.append(
+ " Sources self-report. A row with 0 tokens and a $ figure changed the "
+ "MODEL, not the payload — no tokens were removed."
+ )
+ lines.append("")
+
# Router routing breakdown
if report.router_records:
lines.append("Content Router Routing")
diff --git a/tests/test_cli_perf_format.py b/tests/test_cli_perf_format.py
index 039948641..fd39556d9 100644
--- a/tests/test_cli_perf_format.py
+++ b/tests/test_cli_perf_format.py
@@ -424,3 +424,73 @@ def test_throughput_empty_and_percentiles():
# _calculate_throughput_stats with empty records
stats = _calculate_throughput_stats([], 10.0)
assert stats["input_wall_clock"] == 0.0
+
+
+# ---- savings attributed to named sources -----------------------------------
+# The PERF line carried `savings=` and the parser decoded it from the start, but
+# nothing rendered it, so a paid extension's contribution was invisible in the
+# report operators actually read.
+
+def _savings_perf_line(encoded: str, req: int = 1) -> str:
+ return (
+ f"2026-08-31 16:00:0{req},000 - headroom.proxy - INFO - [hr_1_00000{req}] PERF "
+ "model=claude-haiku-4-5 msgs=12 tok_before=59343 tok_after=30613 "
+ "tok_saved=28730 tok_inflated=0 tool_saved=0 total_saved=28730 cache_read=0 "
+ "cache_write=0 cache_hit_pct=0 opt_ms=12 total_ms=900 tok_out=100 "
+ f"ttfb_ms=800 savings={encoded} transforms=turn_hook"
+ )
+
+
+def _report_for(lines: list[str], tmp_path, monkeypatch) -> str:
+ """Render a report over `lines`, using this file's established LOG_DIR seam.
+
+ Deliberately NOT `HEADROOM_WORKSPACE_DIR`: that env var flips which branch
+ resolves the log directory, which changes behaviour for the rotated-log
+ tests above.
+ """
+ from headroom.perf import analyzer
+
+ logs = tmp_path / "logs"
+ logs.mkdir(parents=True, exist_ok=True)
+ (logs / "proxy.log").write_text("\n".join(lines) + "\n")
+ monkeypatch.setattr(analyzer, "LOG_DIR", logs)
+ return analyzer.format_report(analyzer.parse_log_files(last_n_hours=0))
+
+
+def test_dollar_only_source_is_reported_with_zero_tokens(tmp_path, monkeypatch):
+ """A router saves DOLLARS and exactly zero tokens; both must be legible.
+
+ routemegood sends the same tokens to a cheaper model, so every token-savings
+ channel records nothing for it. Rendering the $ beside a 0-token row is the
+ only honest option — folding them together would invent a saving.
+ """
+ from headroom.proxy.savings_attribution import encode
+
+ out = _report_for(
+ [_savings_perf_line(encode([{"source": "routemegood", "tokens": 0,
+ "usd": 0.1257, "realized": True}]))],
+ tmp_path, monkeypatch,
+ )
+ assert "Savings by Source" in out
+ assert "routemegood" in out
+ assert "0 tokens" in out
+ assert "$0.13" in out
+
+
+def test_token_source_and_dollar_source_coexist(tmp_path, monkeypatch):
+ from headroom.proxy.savings_attribution import encode
+
+ out = _report_for(
+ [_savings_perf_line(encode([
+ {"source": "routemegood", "tokens": 0, "usd": 0.0431, "realized": True},
+ {"source": "lossless_guard", "tokens": 2233, "usd": 0.0, "realized": True},
+ ]))],
+ tmp_path, monkeypatch,
+ )
+ assert "routemegood" in out and "lossless_guard" in out
+ assert "2,233 tokens" in out
+
+
+def test_no_section_when_nothing_attributed(tmp_path, monkeypatch):
+ out = _report_for([_savings_perf_line("none")], tmp_path, monkeypatch)
+ assert "Savings by Source" not in out