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.

feat(savings): show the proxy's model-routing savings in headroom savings (#4304)

Tejas Chopraaaab338b64cb
diff --git a/headroom/cli/savings.py b/headroom/cli/savings.py
index 762c275c4..37f13f171 100644
--- a/headroom/cli/savings.py
+++ b/headroom/cli/savings.py
@@ -4,11 +4,16 @@ Reads the append-only savings ledger (``~/.headroom/savings_events.jsonl``,
written by both the MCP tool path and the proxy) and renders a cost-avoided
summary with Today / Last 7 days / All time bars plus per-model and
per-client breakdowns. Durable across restarts; aggregated on read.
+
+When the local proxy runs a model router (a routing-stats provider, see
+``headroom.proxy.routing_stats``), its savings are shown beside: what each
+moved request cost on the cheaper model against the model it asked for.
"""
from __future__ import annotations
import json
+import os
from typing import Any
import click
@@ -82,6 +87,58 @@ _BASIS_NOTES = {
}
+def _proxy_routing() -> dict[str, Any] | None:
+ """The running proxy's routing rollup (``/stats`` ``routing``), or None.
+
+ None when no proxy answers or it routes nothing: the ledger sections are
+ unaffected either way, so a stopped proxy only hides this section.
+ """
+ from headroom.install.health import probe_json
+ from headroom.install.state import list_manifests
+
+ from .doctor import resolve_probe_port
+
+ env_port = os.environ.get("HEADROOM_PORT")
+ requested = int(env_port) if env_port and env_port.isdigit() else None
+ port = resolve_probe_port(requested, list_manifests())
+ stats = probe_json(f"http://127.0.0.1:{port}/stats", timeout=2.0)
+ routing = stats.get("routing") if isinstance(stats, dict) else None
+ if not isinstance(routing, dict) or not routing.get("decisions"):
+ return None
+ return routing
+
+
+#: How the routing section names the provider's ``window`` (routing_stats contract).
+_ROUTING_WINDOWS = {"lifetime": "lifetime", "session": "this proxy session"}
+
+
+def _echo_routing(routing: dict[str, Any]) -> None:
+ # Per the routing_stats contract: a pair's `enforced` requests are the ones whose
+ # model was rewritten (holdouts and shadow decisions are not), and the saving is
+ # the sum of the pairs' signed `savings_usd`.
+ pairs = [p for p in routing.get("pairs") or [] if p.get("direction") != "same"]
+ moved = sum(int(p.get("enforced") or 0) for p in pairs)
+ saved = sum(float(p.get("savings_usd") or 0.0) for p in pairs)
+ window = _ROUTING_WINDOWS.get(str(routing.get("window")), "all decisions on record")
+ click.echo("")
+ click.echo(
+ f"Model routing ({window}): {moved:,} of {int(routing.get('decisions') or 0):,} "
+ f"requests moved · {_money(saved)} saved"
+ )
+ for pair in pairs:
+ pair_name = f"{pair.get('requested')} → {pair.get('served')}"
+ priced = (
+ _money(float(pair.get("savings_usd") or 0.0))
+ if int(pair.get("measured") or 0)
+ else "not priced (no usage reported)"
+ )
+ click.echo(f" {pair_name:<44} {int(pair.get('enforced') or 0):,} moved {priced}")
+ click.echo(
+ " Saved = each moved request's usage priced on the model asked for, minus its cost "
+ "on the model served."
+ )
+
+
def _echo_basis_note(basis: Any) -> None:
"""Print a caveat when the headline rests on something weaker than the catalog."""
note = _BASIS_NOTES.get(str(basis or ""))
@@ -113,13 +170,20 @@ def savings(as_json: bool, days: int, reset: bool) -> None:
return
report = savings_ledger.aggregate_savings(retention_days=days)
+ routing = _proxy_routing()
if as_json:
- click.echo(json.dumps(report.to_dict(), indent=2))
+ data = report.to_dict()
+ if routing is not None: # no router installed: not even an empty key
+ data["routing"] = routing
+ click.echo(json.dumps(data, indent=2))
return
lifetime = report.lifetime
calls = int(lifetime.get("calls", 0) or 0)
+ if calls == 0 and routing is not None:
+ _echo_routing(routing)
+ return
if calls == 0:
click.echo("No savings recorded yet.")
click.echo(
@@ -156,3 +220,6 @@ def savings(as_json: bool, days: int, reset: bool) -> None:
f" {str(row['client']):<24} {int(row['calls']):,} calls · "
f"{_tokens(int(row['tokens_saved']))} tokens saved"
)
+
+ if routing is not None:
+ _echo_routing(routing)
diff --git a/tests/test_savings_ledger.py b/tests/test_savings_ledger.py
index 41bfc8ead..f7f2426ee 100644
--- a/tests/test_savings_ledger.py
+++ b/tests/test_savings_ledger.py
@@ -666,3 +666,108 @@ def test_many_unwritable_ledgers_do_not_warn_on_every_cycle(
assert len(warnings) == 65
assert sum("append to" in w for w in warnings) == 64
assert "More than 64 warnings about unwritable savings ledgers" in warnings[-1]
+
+
+_ROUTING = { # what routemegood publishes, trimmed to the routing_stats contract
+ "decisions": 11,
+ "window": "lifetime",
+ "pairs": [
+ {
+ "requested": "claude-opus-5-5",
+ "served": "claude-opus-5-5",
+ "direction": "same",
+ "count": 5,
+ "enforced": 0,
+ "holdout": 0,
+ "measured": 0,
+ "savings_usd": 0.0,
+ },
+ {
+ "requested": "claude-sonnet-5-5",
+ "served": "claude-haiku-5-5",
+ "direction": "downgrade",
+ "count": 5,
+ "enforced": 4,
+ "holdout": 1,
+ "measured": 4,
+ "savings_usd": 0.057101,
+ },
+ {
+ "requested": "gpt-5.6-sol",
+ "served": "gpt-5.6-terra",
+ "direction": "downgrade",
+ "count": 2,
+ "enforced": 2,
+ "holdout": 0,
+ "measured": 0,
+ "savings_usd": 0.0,
+ },
+ ],
+}
+
+
+def test_cli_shows_the_proxys_routing_savings_beside_compression(monkeypatch, tmp_path):
+ from click.testing import CliRunner
+
+ from headroom.cli import savings as cli
+
+ _events_env(monkeypatch, tmp_path)
+ L.record_savings_event(tokens_before=1000, tokens_after=300, model=None, client="claude-code")
+ monkeypatch.setattr(cli, "_proxy_routing", lambda: _ROUTING)
+
+ out = CliRunner().invoke(cli.savings, []).output
+ # The headline is the sum of the pairs; a holdout stayed on Sonnet and is not moved.
+ assert "Model routing (lifetime): 6 of 11 requests moved · $0.0571 saved" in out
+ assert "claude-sonnet-5-5 → claude-haiku-5-5" in out
+ assert "not priced (no usage reported)" in out # Sol -> Terra: a saving we cannot claim
+ assert "claude-opus-5-5 → claude-opus-5-5" not in out
+
+ data = json.loads(CliRunner().invoke(cli.savings, ["--json"]).output)
+ assert data["routing"]["pairs"][1]["savings_usd"] == 0.057101
+
+
+def test_cli_shows_routing_savings_before_any_compression(monkeypatch, tmp_path):
+ from click.testing import CliRunner
+
+ from headroom.cli import savings as cli
+
+ _events_env(monkeypatch, tmp_path)
+ monkeypatch.setattr(cli, "_proxy_routing", lambda: _ROUTING)
+ out = CliRunner().invoke(cli.savings, []).output
+ assert "No savings recorded yet." not in out
+ assert "$0.0571 saved" in out
+
+
+def test_proxy_routing_is_none_without_a_router(monkeypatch):
+ from headroom.cli import savings as cli
+
+ monkeypatch.setattr(
+ "headroom.install.health.probe_json", lambda url, timeout=2.0: {"routing": None}
+ )
+ assert cli._proxy_routing() is None
+ monkeypatch.setattr("headroom.install.health.probe_json", lambda url, timeout=2.0: None)
+ assert cli._proxy_routing() is None
+
+
+def test_cli_names_the_routing_window_the_provider_reports(monkeypatch, tmp_path):
+ from click.testing import CliRunner
+
+ from headroom.cli import savings as cli
+
+ _events_env(monkeypatch, tmp_path)
+ for window, label in (("session", "this proxy session"), (None, "all decisions on record")):
+ monkeypatch.setattr(cli, "_proxy_routing", lambda w=window: {**_ROUTING, "window": w})
+ out = CliRunner().invoke(cli.savings, []).output
+ assert f"Model routing ({label}): 6 of 11 requests moved" in out
+
+
+def test_cli_without_a_router_never_mentions_routing(monkeypatch, tmp_path):
+ from click.testing import CliRunner
+
+ from headroom.cli import savings as cli
+
+ _events_env(monkeypatch, tmp_path)
+ L.record_savings_event(tokens_before=1000, tokens_after=300, model=None, client="claude-code")
+ monkeypatch.setattr(cli, "_proxy_routing", lambda: None)
+ assert "routing" not in CliRunner().invoke(cli.savings, []).output.lower()
+ assert "routing" not in json.loads(CliRunner().invoke(cli.savings, ["--json"]).output)