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.

Format display-session tracker changes

Garm02b74607e4a4
diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.py
index bccea97e2..00711252c 100644
--- a/headroom/proxy/savings_tracker.py
+++ b/headroom/proxy/savings_tracker.py
@@ -49,7 +49,12 @@ def _utc_now() -> datetime:
def _to_utc_iso(dt: datetime) -> str:
- return dt.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+ return (
+ dt.astimezone(timezone.utc)
+ .replace(microsecond=0)
+ .isoformat()
+ .replace("+00:00", "Z")
+ )
def _parse_timestamp(value: Any) -> datetime | None:
@@ -117,7 +122,11 @@ def _resolve_litellm_model(model: str) -> str:
if model.startswith(pattern):
candidate = f"{prefix}{model}"
try:
- litellm.cost_per_token(model=candidate, prompt_tokens=1, completion_tokens=0)
+ litellm.cost_per_token(
+ model=candidate,
+ prompt_tokens=1,
+ completion_tokens=0,
+ )
return candidate
except Exception:
break
@@ -170,8 +179,14 @@ def _estimate_input_cost_usd(
return 0.0
if cache_read + cache_write + uncached > 0:
- cache_read_cost = info.get("cache_read_input_token_cost", input_cost_per_token)
- cache_write_cost = info.get("cache_creation_input_token_cost", input_cost_per_token)
+ cache_read_cost = info.get(
+ "cache_read_input_token_cost",
+ input_cost_per_token,
+ )
+ cache_write_cost = info.get(
+ "cache_creation_input_token_cost",
+ input_cost_per_token,
+ )
return (
float(cache_read) * float(cache_read_cost)
+ float(cache_write) * float(cache_write_cost)
@@ -247,7 +262,10 @@ def _normalize_display_session(entry: Any) -> dict[str, Any]:
tokens_saved = _coerce_int(entry.get("tokens_saved"))
total_input_tokens = _coerce_int(entry.get("total_input_tokens"))
total_before = tokens_saved + total_input_tokens
- savings_percent = round((tokens_saved / total_before * 100) if total_before > 0 else 0.0, 2)
+ savings_percent = round(
+ (tokens_saved / total_before * 100) if total_before > 0 else 0.0,
+ 2,
+ )
return {
"requests": _coerce_int(entry.get("requests")),
@@ -257,7 +275,10 @@ def _normalize_display_session(entry: Any) -> dict[str, Any]:
6,
),
"total_input_tokens": total_input_tokens,
- "total_input_cost_usd": round(_coerce_float(entry.get("total_input_cost_usd")), 6),
+ "total_input_cost_usd": round(
+ _coerce_float(entry.get("total_input_cost_usd")),
+ 6,
+ ),
"savings_percent": savings_percent,
"started_at": _to_utc_iso(started_at),
"last_activity_at": _to_utc_iso(last_activity_at),
@@ -272,13 +293,18 @@ class SavingsTracker:
path: str | None = None,
max_history_points: int = DEFAULT_MAX_HISTORY_POINTS,
max_history_age_days: int = DEFAULT_MAX_HISTORY_AGE_DAYS,
- display_session_inactivity_minutes: int = DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES,
+ display_session_inactivity_minutes: int = (
+ DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES
+ ),
) -> None:
self._path = Path(path or get_default_savings_storage_path())
self._max_history_points = max_history_points
self._max_history_age_days = max_history_age_days
self._display_session_inactivity_minutes = max(
- _coerce_int(display_session_inactivity_minutes, DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES),
+ _coerce_int(
+ display_session_inactivity_minutes,
+ DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES,
+ ),
1,
)
self._lock = threading.Lock()
@@ -446,7 +472,9 @@ class SavingsTracker:
)
total_before = session["tokens_saved"] + session["total_input_tokens"]
session["savings_percent"] = round(
- (session["tokens_saved"] / total_before * 100) if total_before > 0 else 0.0,
+ (session["tokens_saved"] / total_before * 100)
+ if total_before > 0
+ else 0.0,
2,
)
session["last_activity_at"] = _to_utc_iso(timestamp_dt)
@@ -556,7 +584,9 @@ class SavingsTracker:
"lifetime": dict(self._state["lifetime"]),
"display_session": self._display_session_snapshot_locked(),
"display_session_policy": {
- "rollover_inactivity_minutes": self._display_session_inactivity_minutes,
+ "rollover_inactivity_minutes": (
+ self._display_session_inactivity_minutes
+ ),
},
"history": history,
"retention": {
@@ -615,13 +645,20 @@ 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_float(
+ lifetime_raw.get("compression_savings_usd")
+ )
lifetime_input_tokens = _coerce_int(lifetime_raw.get("total_input_tokens"))
- lifetime_input_cost_usd = _coerce_float(lifetime_raw.get("total_input_cost_usd"))
+ lifetime_input_cost_usd = _coerce_float(
+ lifetime_raw.get("total_input_cost_usd")
+ )
if normalized_history:
last = normalized_history[-1]
- lifetime_tokens_saved = max(lifetime_tokens_saved, last["total_tokens_saved"])
+ lifetime_tokens_saved = max(
+ lifetime_tokens_saved,
+ last["total_tokens_saved"],
+ )
lifetime_savings_usd = max(
lifetime_savings_usd,
_coerce_float(last["compression_savings_usd"]),
@@ -649,7 +686,9 @@ class SavingsTracker:
}
if normalized_history:
- reference_time = _parse_timestamp(normalized_history[-1]["timestamp"]) or _utc_now()
+ reference_time = (
+ _parse_timestamp(normalized_history[-1]["timestamp"]) or _utc_now()
+ )
original_state = self._state if hasattr(self, "_state") else None
self._state = state
try:
@@ -667,7 +706,9 @@ class SavingsTracker:
return
if self._max_history_age_days > 0:
- cutoff = (reference_time or _utc_now()) - timedelta(days=self._max_history_age_days)
+ cutoff = (reference_time or _utc_now()) - timedelta(
+ days=self._max_history_age_days
+ )
filtered = [
item
for item in history
@@ -754,7 +795,11 @@ class SavingsTracker:
minutes=self._display_session_inactivity_minutes
)
- def _build_rollup(self, history: list[dict[str, Any]], bucket: str) -> list[dict[str, Any]]:
+ def _build_rollup(
+ self,
+ history: list[dict[str, Any]],
+ bucket: str,
+ ) -> list[dict[str, Any]]:
if not history:
return []
diff --git a/tests/test_proxy_savings_history.py b/tests/test_proxy_savings_history.py
index d354048b5..191e91411 100644
--- a/tests/test_proxy_savings_history.py
+++ b/tests/test_proxy_savings_history.py
@@ -43,7 +43,9 @@ def _record_request(
def test_savings_tracker_helpers_normalize_inputs_and_paths(tmp_path, monkeypatch):
override_path = tmp_path / "custom-savings.json"
monkeypatch.setenv(HEADROOM_SAVINGS_PATH_ENV_VAR, str(override_path))
- assert savings_tracker_module.get_default_savings_storage_path() == str(override_path)
+ assert savings_tracker_module.get_default_savings_storage_path() == str(
+ override_path
+ )
monkeypatch.delenv(HEADROOM_SAVINGS_PATH_ENV_VAR, raising=False)
default_path = savings_tracker_module.get_default_savings_storage_path()
@@ -102,7 +104,11 @@ def test_savings_tracker_sanitizes_legacy_state_and_applies_retention(tmp_path):
encoding="utf-8",
)
- tracker = SavingsTracker(path=str(path), max_history_points=1, max_history_age_days=2)
+ tracker = SavingsTracker(
+ path=str(path),
+ max_history_points=1,
+ max_history_age_days=2,
+ )
snapshot = tracker.snapshot()
assert snapshot["schema_version"] == 2
@@ -113,7 +119,10 @@ def test_savings_tracker_sanitizes_legacy_state_and_applies_retention(tmp_path):
"total_input_tokens": 0,
"total_input_cost_usd": 0.0,
}
- assert snapshot["display_session"] == savings_tracker_module._empty_display_session()
+ assert (
+ snapshot["display_session"]
+ == savings_tracker_module._empty_display_session()
+ )
assert snapshot["history"] == [
{
"timestamp": "2026-03-27T09:00:00Z",
@@ -143,7 +152,10 @@ def test_non_dict_savings_state_resets_to_default(tmp_path):
"total_input_tokens": 0,
"total_input_cost_usd": 0.0,
}
- assert snapshot["display_session"] == savings_tracker_module._empty_display_session()
+ assert (
+ snapshot["display_session"]
+ == savings_tracker_module._empty_display_session()
+ )
assert snapshot["history"] == []
@@ -242,7 +254,9 @@ def test_litellm_resolution_and_savings_estimation_fallbacks(monkeypatch):
) == pytest.approx(0.2)
fake_litellm.model_cost = {}
- assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0
+ assert (
+ savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0
+ )
assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0
monkeypatch.setattr(
@@ -250,11 +264,19 @@ def test_litellm_resolution_and_savings_estimation_fallbacks(monkeypatch):
"cost_per_token",
lambda **kwargs: (_ for _ in ()).throw(RuntimeError("boom")),
)
- assert savings_tracker_module._resolve_litellm_model("mystery-model") == "mystery-model"
- assert savings_tracker_module._estimate_compression_savings_usd("mystery-model", 100) == 0.0
+ assert (
+ savings_tracker_module._resolve_litellm_model("mystery-model")
+ == "mystery-model"
+ )
+ assert (
+ savings_tracker_module._estimate_compression_savings_usd("mystery-model", 100)
+ == 0.0
+ )
monkeypatch.setattr(savings_tracker_module, "LITELLM_AVAILABLE", False)
- assert savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0
+ assert (
+ savings_tracker_module._estimate_compression_savings_usd("gpt-4o", 100) == 0.0
+ )
assert savings_tracker_module._estimate_input_cost_usd("gpt-4o", 100) == 0.0
@@ -309,7 +331,10 @@ def test_display_session_rolls_after_inactivity_and_counts_zero_savings_requests
"_utc_now",
lambda: datetime(2026, 3, 27, 9, 45, tzinfo=timezone.utc),
)
- assert tracker.snapshot()["display_session"] == savings_tracker_module._empty_display_session()
+ assert (
+ tracker.snapshot()["display_session"]
+ == savings_tracker_module._empty_display_session()
+ )
tracker.record_request(
model="gpt-4o",
@@ -339,7 +364,11 @@ def test_display_session_rolls_after_inactivity_and_counts_zero_savings_requests
def test_savings_tracker_rollups_preserve_spend_and_input_history(tmp_path, monkeypatch):
path = tmp_path / "proxy_savings.json"
- tracker = SavingsTracker(path=str(path), max_history_points=100, max_history_age_days=30)
+ tracker = SavingsTracker(
+ path=str(path),
+ max_history_points=100,
+ max_history_age_days=30,
+ )
monkeypatch.setattr(
"headroom.proxy.savings_tracker._estimate_compression_savings_usd",
lambda model, tokens_saved: tokens_saved / 1000.0,
@@ -476,7 +505,9 @@ def test_savings_tracker_rollups_preserve_spend_and_input_history(tmp_path, monk
]
-def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_path, monkeypatch):
+def test_stats_history_persists_across_restarts_and_stats_stays_compatible(
+ tmp_path, monkeypatch
+):
savings_path = tmp_path / "proxy_savings.json"
monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
monkeypatch.setattr(
@@ -514,7 +545,12 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_p
assert history_data["display_session"]["tokens_saved"] == 40
assert history_data["display_session"]["total_input_tokens"] == 120
assert history_data["display_session"]["savings_percent"] == pytest.approx(25.0)
- assert list(history_data["series"].keys()) == ["hourly", "daily", "weekly", "monthly"]
+ assert list(history_data["series"].keys()) == [
+ "hourly",
+ "daily",
+ "weekly",
+ "monthly",
+ ]
assert history_data["exports"]["available_series"][-2:] == ["weekly", "monthly"]
assert history_data["series"]["hourly"][0]["total_input_tokens_delta"] == 120
assert history_data["series"]["hourly"][0]["total_input_cost_usd_delta"] == pytest.approx(
@@ -522,7 +558,10 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_p
)
assert stats_data["display_session"] == history_data["display_session"]
- assert stats_data["persistent_savings"]["display_session"] == history_data["display_session"]
+ assert (
+ stats_data["persistent_savings"]["display_session"]
+ == history_data["display_session"]
+ )
with TestClient(create_app(config)) as client:
history = client.get("/stats-history")