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.

fix(proxy): keep negative compression savings across restart (#4406)

HetCreepbebe24c5ff0e
diff --git a/headroom/proxy/persistent_metrics.py b/headroom/proxy/persistent_metrics.py
index 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"] != 0
if "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.py
index 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_raw
if 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.py
new file mode 100644
index 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)