Format display-session tracker changes

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 []
 

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")