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
Format display-session tracker changes
Garm02b74607e4a4
diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.pyindex 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 candidateexcept Exception:break@@ -170,8 +179,14 @@ def _estimate_input_cost_usd(return 0.0if 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_pointsself._max_history_age_days = max_history_age_daysself._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 Noneself._state = statetry:@@ -667,7 +706,9 @@ class SavingsTracker:returnif 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 = [itemfor 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.pyindex 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.0monkeypatch.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_requestsdef 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_passert history_data["display_session"]["tokens_saved"] == 40assert history_data["display_session"]["total_input_tokens"] == 120assert 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"] == 120assert 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")