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
fix(proxy): keep negative compression savings across restart (#4406)
HetCreepbebe24c5ff0e
diff --git a/headroom/proxy/persistent_metrics.py b/headroom/proxy/persistent_metrics.pyindex 08286dc38..5cc4cc295 100644--- a/headroom/proxy/persistent_metrics.py+++ b/headroom/proxy/persistent_metrics.py@@ -83,6 +83,15 @@ def _coerce_float(value: Any) -> float:return result if math.isfinite(result) and result >= 0 else 0.0+def _coerce_signed_float(value: Any) -> float:+ """_coerce_float without the zero floor, for compression savings that can lose."""+ try:+ result = float(value)+ except (TypeError, ValueError, OverflowError):+ return 0.0+ return result if math.isfinite(result) else 0.0++def _label(value: Any) -> str:if not isinstance(value, str):return "other"@@ -257,7 +266,10 @@ class PersistentMetricsState:"compression_savings_list_usd","cache_savings_usd",):- result["cost"][key] = round(_coerce_float(raw_cost.get(key)), 6)+ coerce = (+ _coerce_signed_float if key.startswith("compression_savings") else _coerce_float+ )+ result["cost"][key] = round(coerce(raw_cost.get(key)), 6)# A state written before cache-aware pricing has no list column and its# dollars WERE list-priced, so that one figure seeds both and the# aggregate stays honestly labelled.@@ -266,7 +278,7 @@ class PersistentMetricsState:# column, and labelling that "list" would tell every new install its# untouched $0.00 total was list-priced. Only a state that actually# accumulated dollars has history to migrate.- has_priced_history = result["cost"]["compression_savings_usd"] > 0+ has_priced_history = result["cost"]["compression_savings_usd"] != 0if "compression_savings_list_usd" in raw_cost:result["cost"]["savings_basis"] = str(raw_cost.get("savings_basis") or "unknown")elif has_priced_history:@@ -466,7 +478,7 @@ class PersistentMetricsState:cost = self._state["cost"]cost["input_usd"] = round(cost["input_usd"] + _coerce_float(input_usd), 6)cost["compression_savings_usd"] = round(- cost["compression_savings_usd"] + _coerce_float(compression_savings_usd), 6+ cost["compression_savings_usd"] + _coerce_signed_float(compression_savings_usd), 6)# Defaults to the cache-aware figure when a caller supplies no ceiling,# which is the truthful reading of "these are the same number" for a@@ -477,7 +489,9 @@ class PersistentMetricsState:else compression_savings_list_usd)cost["compression_savings_list_usd"] = round(- _coerce_float(cost.get("compression_savings_list_usd")) + _coerce_float(list_delta), 6+ _coerce_signed_float(cost.get("compression_savings_list_usd"))+ + _coerce_signed_float(list_delta),+ 6,)if savings_basis:cost["savings_basis"] = _blend_savings_basis(cost.get("savings_basis"), savings_basis)diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.pyindex 89cda7d7b..c82e74d3f 100644--- a/headroom/proxy/savings_tracker.py+++ b/headroom/proxy/savings_tracker.py@@ -727,7 +727,7 @@ def _normalize_history_entry(entry: Any) -> dict[str, Any] | None:if isinstance(entry, dict):timestamp = _parse_timestamp(entry.get("timestamp"))total_tokens_saved = _coerce_int(entry.get("total_tokens_saved"))- compression_savings_usd = _coerce_float(entry.get("compression_savings_usd"))+ compression_savings_usd = _coerce_signed_float(entry.get("compression_savings_usd"))# Older history points predate cache-savings tracking and omit these# keys entirely; default to 0/0.0 rather than raising or dropping the# entry, matching how every other field here handles legacy shapes.@@ -747,7 +747,7 @@ def _normalize_history_entry(entry: Any) -> dict[str, Any] | None:timestamp = _parse_timestamp(entry[0])total_tokens_saved = _coerce_int(entry[1])if len(entry) >= 3:- compression_savings_usd = _coerce_float(entry[2])+ compression_savings_usd = _coerce_signed_float(entry[2])if len(entry) >= 4:total_input_tokens = _coerce_int(entry[3])if len(entry) >= 5:@@ -1881,7 +1881,7 @@ class SavingsTracker:if isinstance(lifetime_raw, dict):lifetime_requests = _coerce_int(lifetime_raw.get("requests"))lifetime_tokens_saved = _coerce_int(lifetime_raw.get("tokens_saved"))- lifetime_savings_usd = _coerce_float(lifetime_raw.get("compression_savings_usd"))+ lifetime_savings_usd = _coerce_signed_float(lifetime_raw.get("compression_savings_usd"))lifetime_tool_tokens_saved = _coerce_int(lifetime_raw.get("tool_tokens_saved"))lifetime_tool_savings_usd = _coerce_float(lifetime_raw.get("tool_schema_savings_usd"))lifetime_cache_read_tokens = _coerce_int(lifetime_raw.get("cache_read_tokens"))@@ -1891,7 +1891,7 @@ class SavingsTracker:migrated_at = lifetime_raw.get("savings_basis_migrated_at")is_v6_lifetime = "compression_savings_list_usd" in lifetime_rawif is_v6_lifetime:- lifetime_savings_list_usd = _coerce_float(+ lifetime_savings_list_usd = _coerce_signed_float(lifetime_raw.get("compression_savings_list_usd"))lifetime_basis = str(lifetime_raw.get("savings_basis") or BASIS_UNKNOWN)@@ -1901,14 +1901,27 @@ class SavingsTracker:if normalized_history:last = normalized_history[-1]+ # A losing request that saves no tokens and reads no cache appends+ # no checkpoint, so the saved total can legitimately sit BELOW the+ # last checkpoint. Only trust the checkpoint for dollars when the+ # saved counters show the lifetime block is behind it.+ history_ahead = (+ lifetime_tokens_saved < last["total_tokens_saved"]+ or lifetime_cache_read_tokens < _coerce_int(last.get("cache_read_tokens"))+ or lifetime_output_tokens_saved < _coerce_int(last.get("output_tokens_saved"))+ or lifetime_tool_tokens_saved < _coerce_int(last.get("tool_tokens_saved"))+ or not (+ isinstance(lifetime_raw, dict) and "compression_savings_usd" in lifetime_raw+ )+ )lifetime_tokens_saved = max(lifetime_tokens_saved,last["total_tokens_saved"],)- lifetime_savings_usd = max(- lifetime_savings_usd,- _coerce_float(last["compression_savings_usd"]),- )+ if history_ahead:+ # The checkpoint is the newer source here; a numeric max() would+ # discard a newer negative total in favour of an older higher one.+ lifetime_savings_usd = _coerce_signed_float(last["compression_savings_usd"])lifetime_tool_tokens_saved = max(lifetime_tool_tokens_saved,_coerce_int(last.get("tool_tokens_saved")),@@ -2225,7 +2238,7 @@ class SavingsTracker:2,)session["compression_savings_usd"] = round(- _coerce_float(session.get("compression_savings_usd")),+ _coerce_signed_float(session.get("compression_savings_usd")),6,)session["total_input_cost_usd"] = round(diff --git a/tests/test_negative_savings_reload.py b/tests/test_negative_savings_reload.pynew file mode 100644index 000000000..2e10918f8--- /dev/null+++ b/tests/test_negative_savings_reload.py@@ -0,0 +1,135 @@+"""A negative compression-savings total must survive a restart, not reload as 0."""++from __future__ import annotations++import json++import pytest++from headroom.proxy.persistent_metrics import PersistentMetricsState+from headroom.proxy.savings_tracker import SavingsTracker+++def _losing_request(tracker: SavingsTracker) -> None:+ tracker.record_request(+ model="claude-sonnet-4",+ tokens_saved=100,+ input_tokens=1000,+ estimated_savings_usd={+ "compression": -0.5,+ "tool_schema": 0.0,+ "compression_list": -0.5,+ "tool_schema_list": 0.0,+ "basis": "cache_aware",+ },+ )+ tracker.flush()+++def test_negative_savings_survive_reload(tmp_path) -> None:+ path = str(tmp_path / "savings.json")+ live = SavingsTracker(path=path)+ _losing_request(live)+ snap = live.snapshot()+ assert snap["lifetime"]["compression_savings_usd"] == pytest.approx(-0.5)+ assert snap["display_session"]["compression_savings_usd"] == pytest.approx(-0.5)++ reloaded = SavingsTracker(path=path).snapshot()+ assert reloaded["lifetime"]["compression_savings_usd"] == pytest.approx(-0.5)+ assert reloaded["display_session"]["compression_savings_usd"] == pytest.approx(-0.5)+ assert reloaded["history"][-1]["compression_savings_usd"] == pytest.approx(-0.5)+++def test_lifetime_metrics_keep_negative_compression_savings() -> None:+ state = PersistentMetricsState()+ state.record_request(+ provider="anthropic",+ model="claude-sonnet-4",+ stack=None,+ compression_savings_usd=-0.5,+ )+ cost = state.to_dict()["cost"]+ assert cost["compression_savings_usd"] == pytest.approx(-0.5)+ assert cost["compression_savings_list_usd"] == pytest.approx(-0.5)++ reloaded = PersistentMetricsState(state.to_dict()).to_dict()["cost"]+ assert reloaded["compression_savings_usd"] == pytest.approx(-0.5)+ assert reloaded["compression_savings_list_usd"] == pytest.approx(-0.5)+++def test_negative_list_total_survives_reload_and_next_request(tmp_path) -> None:+ path = str(tmp_path / "savings.json")+ live = SavingsTracker(path=path)+ _losing_request(live)++ reloaded = SavingsTracker(path=path)+ assert reloaded.snapshot()["lifetime"]["compression_savings_list_usd"] == pytest.approx(-0.5)+ reloaded.record_request(+ model="claude-sonnet-4",+ tokens_saved=100,+ input_tokens=1000,+ estimated_savings_usd={+ "compression": 0.1,+ "tool_schema": 0.0,+ "compression_list": 0.1,+ "tool_schema_list": 0.0,+ "basis": "cache_aware",+ },+ )+ lifetime = reloaded.snapshot()["lifetime"]+ assert lifetime["compression_savings_usd"] == pytest.approx(-0.4)+ assert lifetime["compression_savings_list_usd"] == pytest.approx(-0.4)+++def test_loss_after_last_checkpoint_is_not_overwritten_by_history(tmp_path) -> None:+ path = tmp_path / "savings.json"+ live = SavingsTracker(path=str(path))+ live.record_request(+ model="claude-sonnet-4",+ tokens_saved=100,+ input_tokens=1000,+ estimated_savings_usd={+ "compression": 0.5,+ "tool_schema": 0.0,+ "compression_list": 0.5,+ "tool_schema_list": 0.0,+ "basis": "cache_aware",+ },+ )+ # No tokens saved and no cache reads: no history checkpoint is appended.+ live.record_request(+ model="claude-sonnet-4",+ tokens_saved=0,+ input_tokens=1000,+ estimated_savings_usd={+ "compression": -1.0,+ "tool_schema": 0.0,+ "compression_list": -1.0,+ "tool_schema_list": 0.0,+ "basis": "cache_aware",+ },+ )+ live.flush()+ saved = json.loads(path.read_text())+ assert saved["lifetime"]["compression_savings_usd"] == pytest.approx(-0.5)+ assert saved["history"][-1]["compression_savings_usd"] == pytest.approx(0.5)++ reloaded = SavingsTracker(path=str(path)).snapshot()+ assert reloaded["lifetime"]["compression_savings_usd"] == pytest.approx(-0.5)++[email protected]("stale_usd", [0.0, 1.0])+def test_newer_negative_checkpoint_wins_over_stale_lifetime_dollars(tmp_path, stale_usd) -> None:+ path = tmp_path / "savings.json"+ _losing_request(SavingsTracker(path=str(path)))+ saved = json.loads(path.read_text())+ assert saved["history"][-1]["total_tokens_saved"] == 100+ assert saved["history"][-1]["compression_savings_usd"] == pytest.approx(-0.5)+ # Stale lifetime block: behind the checkpoint on tokens, dollars older/higher.+ saved["lifetime"]["tokens_saved"] = 0+ saved["lifetime"]["compression_savings_usd"] = stale_usd+ path.write_text(json.dumps(saved))++ lifetime = SavingsTracker(path=str(path)).snapshot()["lifetime"]+ assert lifetime["tokens_saved"] == 100+ assert lifetime["compression_savings_usd"] == pytest.approx(-0.5)