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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
perf: render the savings each source actually reported
Tejas Chopra56f809ce3987
diff --git a/headroom/perf/analyzer.py b/headroom/perf/analyzer.pyindex 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 breakdownif report.router_records:lines.append("Content Router Routing")diff --git a/tests/test_cli_perf_format.py b/tests/test_cli_perf_format.pyindex 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 recordsstats = _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