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.

Add canonical display-session metrics for downstream dashboards

Garm460247c93f59
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index b8b9b2c8c..44fc7c370 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -324,6 +324,7 @@ Usage:
Endpoints:
GET /health Health check
GET /stats Detailed statistics
+ GET /stats-history Durable compression history + display session
GET /metrics Prometheus metrics
Press Ctrl+C to stop.
diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.py
index 0ac72399c..bccea97e2 100644
--- a/headroom/proxy/savings_tracker.py
+++ b/headroom/proxy/savings_tracker.py
@@ -1,8 +1,8 @@
-"""Durable proxy savings history tracking.
+"""Durable proxy savings and display-session tracking.
-Persists cumulative proxy compression savings to a local JSON file so
-historical charts survive proxy restarts and can be shared by multiple
-Headroom frontends.
+Persists cumulative proxy compression savings plus a canonical display session
+window to a local JSON file so historical charts and dashboard session stats
+survive proxy restarts and can be shared by multiple Headroom frontends.
"""
from __future__ import annotations
@@ -23,9 +23,10 @@ logger = logging.getLogger(__name__)
HEADROOM_SAVINGS_PATH_ENV_VAR = "HEADROOM_SAVINGS_PATH"
DEFAULT_SAVINGS_DIR = ".headroom"
DEFAULT_SAVINGS_FILE = "proxy_savings.json"
-SCHEMA_VERSION = 1
+SCHEMA_VERSION = 2
DEFAULT_MAX_HISTORY_POINTS = 5000
DEFAULT_MAX_HISTORY_AGE_DAYS = 365
+DEFAULT_DISPLAY_SESSION_INACTIVITY_MINUTES = 60
try:
import litellm
@@ -140,6 +141,48 @@ def _estimate_compression_savings_usd(model: str, tokens_saved: int) -> float:
return 0.0
+def _estimate_input_cost_usd(
+ model: str,
+ input_tokens: int,
+ *,
+ cache_read_tokens: int = 0,
+ cache_write_tokens: int = 0,
+ uncached_input_tokens: int = 0,
+) -> float:
+ """Estimate input spend in USD for a request.
+
+ Uses provider cache pricing when a complete cache breakdown is available and
+ otherwise falls back to list-price input tokens.
+ """
+ total_input_tokens = _coerce_int(input_tokens)
+ if total_input_tokens <= 0 or not LITELLM_AVAILABLE:
+ return 0.0
+
+ cache_read = _coerce_int(cache_read_tokens)
+ cache_write = _coerce_int(cache_write_tokens)
+ uncached = _coerce_int(uncached_input_tokens)
+
+ try:
+ resolved = _resolve_litellm_model(model)
+ info = litellm.model_cost.get(resolved, {})
+ input_cost_per_token = info.get("input_cost_per_token")
+ if not input_cost_per_token:
+ 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)
+ return (
+ float(cache_read) * float(cache_read_cost)
+ + float(cache_write) * float(cache_write_cost)
+ + float(uncached) * float(input_cost_per_token)
+ )
+
+ return float(total_input_tokens) * float(input_cost_per_token)
+ except Exception:
+ return 0.0
+
+
def _normalize_history_entry(entry: Any) -> dict[str, Any] | None:
"""Normalize persisted history entries across schema shapes."""
timestamp: datetime | None = None
@@ -178,6 +221,49 @@ def _normalize_history_entry(entry: Any) -> dict[str, Any] | None:
}
+def _empty_display_session() -> dict[str, Any]:
+ return {
+ "requests": 0,
+ "tokens_saved": 0,
+ "compression_savings_usd": 0.0,
+ "total_input_tokens": 0,
+ "total_input_cost_usd": 0.0,
+ "savings_percent": 0.0,
+ "started_at": None,
+ "last_activity_at": None,
+ }
+
+
+def _normalize_display_session(entry: Any) -> dict[str, Any]:
+ if not isinstance(entry, dict):
+ return _empty_display_session()
+
+ started_at = _parse_timestamp(entry.get("started_at"))
+ last_activity_at = _parse_timestamp(entry.get("last_activity_at"))
+
+ if started_at is None or last_activity_at is None or last_activity_at < started_at:
+ return _empty_display_session()
+
+ 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)
+
+ return {
+ "requests": _coerce_int(entry.get("requests")),
+ "tokens_saved": tokens_saved,
+ "compression_savings_usd": round(
+ _coerce_float(entry.get("compression_savings_usd")),
+ 6,
+ ),
+ "total_input_tokens": total_input_tokens,
+ "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),
+ }
+
+
class SavingsTracker:
"""Persist bounded proxy compression savings history."""
@@ -186,10 +272,15 @@ 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,
) -> 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),
+ 1,
+ )
self._lock = threading.Lock()
self._state = self._load_state()
@@ -257,6 +348,126 @@ class SavingsTracker:
self._save_locked()
return True
+ def record_request(
+ self,
+ *,
+ model: str,
+ input_tokens: int,
+ tokens_saved: int,
+ cache_read_tokens: int = 0,
+ cache_write_tokens: int = 0,
+ uncached_input_tokens: int = 0,
+ total_input_tokens: int | None = None,
+ total_input_cost_usd: float | None = None,
+ timestamp: datetime | str | None = None,
+ ) -> bool:
+ """Persist a canonical display-session update for every request."""
+ timestamp_dt = (
+ _parse_timestamp(timestamp)
+ if isinstance(timestamp, str)
+ else timestamp.astimezone(timezone.utc)
+ if isinstance(timestamp, datetime)
+ else _utc_now()
+ )
+ if timestamp_dt is None:
+ timestamp_dt = _utc_now()
+
+ delta_tokens_saved = _coerce_int(tokens_saved)
+ delta_input_tokens = _coerce_int(input_tokens)
+ delta_savings_usd = _estimate_compression_savings_usd(model, delta_tokens_saved)
+ delta_input_cost_usd = _estimate_input_cost_usd(
+ model,
+ delta_input_tokens,
+ cache_read_tokens=cache_read_tokens,
+ cache_write_tokens=cache_write_tokens,
+ uncached_input_tokens=uncached_input_tokens,
+ )
+
+ with self._lock:
+ lifetime = self._state["lifetime"]
+ previous_total_input_tokens = lifetime["total_input_tokens"]
+ previous_total_input_cost_usd = lifetime["total_input_cost_usd"]
+
+ next_total_input_tokens = max(
+ previous_total_input_tokens + delta_input_tokens,
+ _coerce_int(
+ total_input_tokens,
+ default=previous_total_input_tokens + delta_input_tokens,
+ ),
+ )
+ next_total_input_cost_usd = round(
+ max(
+ previous_total_input_cost_usd + delta_input_cost_usd,
+ _coerce_float(
+ total_input_cost_usd,
+ default=previous_total_input_cost_usd + delta_input_cost_usd,
+ ),
+ ),
+ 6,
+ )
+ session_input_tokens_delta = max(
+ next_total_input_tokens - previous_total_input_tokens,
+ 0,
+ )
+ session_input_cost_delta = round(
+ max(next_total_input_cost_usd - previous_total_input_cost_usd, 0.0),
+ 6,
+ )
+
+ lifetime["requests"] += 1
+ lifetime["tokens_saved"] += delta_tokens_saved
+ lifetime["compression_savings_usd"] = round(
+ lifetime["compression_savings_usd"] + delta_savings_usd,
+ 6,
+ )
+ lifetime["total_input_tokens"] = next_total_input_tokens
+ lifetime["total_input_cost_usd"] = next_total_input_cost_usd
+
+ session = self._state["display_session"]
+ last_activity = _parse_timestamp(session.get("last_activity_at"))
+ if last_activity is None or self._is_display_session_expired(
+ last_activity,
+ reference_time=timestamp_dt,
+ ):
+ session = _empty_display_session()
+ session["started_at"] = _to_utc_iso(timestamp_dt)
+ self._state["display_session"] = session
+
+ session["requests"] += 1
+ session["tokens_saved"] += delta_tokens_saved
+ session["compression_savings_usd"] = round(
+ session["compression_savings_usd"] + delta_savings_usd,
+ 6,
+ )
+ session["total_input_tokens"] += session_input_tokens_delta
+ session["total_input_cost_usd"] = round(
+ session["total_input_cost_usd"] + session_input_cost_delta,
+ 6,
+ )
+ 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,
+ 2,
+ )
+ session["last_activity_at"] = _to_utc_iso(timestamp_dt)
+ if session.get("started_at") is None:
+ session["started_at"] = session["last_activity_at"]
+
+ if delta_tokens_saved > 0:
+ self._state["history"].append(
+ {
+ "timestamp": _to_utc_iso(timestamp_dt),
+ "total_tokens_saved": lifetime["tokens_saved"],
+ "compression_savings_usd": lifetime["compression_savings_usd"],
+ "total_input_tokens": lifetime["total_input_tokens"],
+ "total_input_cost_usd": lifetime["total_input_cost_usd"],
+ }
+ )
+ self._trim_history_locked(reference_time=timestamp_dt)
+
+ self._save_locked()
+ return True
+
def stats_preview(self, recent_points: int = 20) -> dict[str, Any]:
"""Return a compact preview for `/stats`."""
snapshot = self.snapshot()
@@ -264,6 +475,8 @@ class SavingsTracker:
"schema_version": snapshot["schema_version"],
"storage_path": snapshot["storage_path"],
"lifetime": snapshot["lifetime"],
+ "display_session": snapshot["display_session"],
+ "display_session_policy": snapshot["display_session_policy"],
"history_points": len(snapshot["history"]),
"recent_history": snapshot["history"][-recent_points:],
"retention": snapshot["retention"],
@@ -284,6 +497,8 @@ class SavingsTracker:
"generated_at": _to_utc_iso(_utc_now()),
"storage_path": snapshot["storage_path"],
"lifetime": snapshot["lifetime"],
+ "display_session": snapshot["display_session"],
+ "display_session_policy": snapshot["display_session_policy"],
"history": history,
"series": series,
"exports": {
@@ -339,6 +554,10 @@ class SavingsTracker:
"schema_version": SCHEMA_VERSION,
"storage_path": str(self._path),
"lifetime": dict(self._state["lifetime"]),
+ "display_session": self._display_session_snapshot_locked(),
+ "display_session_policy": {
+ "rollover_inactivity_minutes": self._display_session_inactivity_minutes,
+ },
"history": history,
"retention": {
"max_history_points": self._max_history_points,
@@ -350,11 +569,13 @@ class SavingsTracker:
return {
"schema_version": SCHEMA_VERSION,
"lifetime": {
+ "requests": 0,
"tokens_saved": 0,
"compression_savings_usd": 0.0,
"total_input_tokens": 0,
"total_input_cost_usd": 0.0,
},
+ "display_session": _empty_display_session(),
"history": [],
}
@@ -386,11 +607,13 @@ class SavingsTracker:
normalized_history.sort(key=lambda item: item["timestamp"])
lifetime_raw = raw.get("lifetime", {})
+ lifetime_requests = 0
lifetime_tokens_saved = 0
lifetime_savings_usd = 0.0
lifetime_input_tokens = 0
lifetime_input_cost_usd = 0.0
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_input_tokens = _coerce_int(lifetime_raw.get("total_input_tokens"))
@@ -415,11 +638,13 @@ class SavingsTracker:
state = {
"schema_version": SCHEMA_VERSION,
"lifetime": {
+ "requests": lifetime_requests,
"tokens_saved": lifetime_tokens_saved,
"compression_savings_usd": round(lifetime_savings_usd, 6),
"total_input_tokens": lifetime_input_tokens,
"total_input_cost_usd": round(lifetime_input_cost_usd, 6),
},
+ "display_session": _normalize_display_session(raw.get("display_session")),
"history": normalized_history,
}
@@ -463,6 +688,7 @@ class SavingsTracker:
payload = {
"schema_version": SCHEMA_VERSION,
"lifetime": self._state["lifetime"],
+ "display_session": self._state["display_session"],
"history": self._state["history"],
}
json_data = json.dumps(payload, indent=2)
@@ -487,6 +713,47 @@ class SavingsTracker:
except OSError as e:
logger.warning("Failed to save savings history to %s: %s", self._path, e)
+ def _display_session_snapshot_locked(
+ self,
+ reference_time: datetime | None = None,
+ ) -> dict[str, Any]:
+ session = dict(self._state["display_session"])
+ last_activity = _parse_timestamp(session.get("last_activity_at"))
+ if last_activity is None or self._is_display_session_expired(
+ last_activity,
+ reference_time=reference_time,
+ ):
+ return _empty_display_session()
+
+ total_before = _coerce_int(session.get("tokens_saved")) + _coerce_int(
+ session.get("total_input_tokens")
+ )
+ session["savings_percent"] = round(
+ (_coerce_int(session.get("tokens_saved")) / total_before * 100)
+ if total_before > 0
+ else 0.0,
+ 2,
+ )
+ session["compression_savings_usd"] = round(
+ _coerce_float(session.get("compression_savings_usd")),
+ 6,
+ )
+ session["total_input_cost_usd"] = round(
+ _coerce_float(session.get("total_input_cost_usd")),
+ 6,
+ )
+ return session
+
+ def _is_display_session_expired(
+ self,
+ last_activity: datetime,
+ *,
+ reference_time: datetime | None = None,
+ ) -> bool:
+ return (reference_time or _utc_now()) - last_activity > timedelta(
+ minutes=self._display_session_inactivity_minutes
+ )
+
def _build_rollup(self, history: list[dict[str, Any]], bucket: str) -> list[dict[str, Any]]:
if not history:
return []
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 71c56804d..e64f58580 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -1269,6 +1269,7 @@ class PrometheusMetrics:
waste_signals: dict[str, int] | None = None,
cache_read_tokens: int = 0,
cache_write_tokens: int = 0,
+ uncached_input_tokens: int = 0,
):
"""Record metrics for a request."""
async with self._lock:
@@ -1342,14 +1343,17 @@ class PrometheusMetrics:
if len(self.savings_history) > 500:
self.savings_history = self.savings_history[-500:]
- if tokens_saved > 0:
- total_input_tokens, total_input_cost_usd = self._current_savings_tracker_totals()
- self.savings_tracker.record_compression_savings(
- model=model,
- tokens_saved=tokens_saved,
- total_input_tokens=total_input_tokens,
- total_input_cost_usd=total_input_cost_usd,
- )
+ total_input_tokens, total_input_cost_usd = self._current_savings_tracker_totals()
+ self.savings_tracker.record_request(
+ model=model,
+ input_tokens=input_tokens,
+ tokens_saved=tokens_saved,
+ cache_read_tokens=cache_read_tokens,
+ cache_write_tokens=cache_write_tokens,
+ uncached_input_tokens=uncached_input_tokens,
+ total_input_tokens=total_input_tokens,
+ total_input_cost_usd=total_input_cost_usd,
+ )
async def record_rate_limited(self):
async with self._lock:
@@ -3082,6 +3086,7 @@ class HeadroomProxy:
waste_signals=waste_signals_dict,
cache_read_tokens=cr_tokens,
cache_write_tokens=cw_tokens,
+ uncached_input_tokens=uncached_input_tokens,
)
# Log request
@@ -4843,6 +4848,7 @@ class HeadroomProxy:
pipeline_timing=pipeline_timing,
cache_read_tokens=cache_read_tokens,
cache_write_tokens=cache_write_tokens,
+ uncached_input_tokens=uncached_input_tokens,
)
return StreamingResponse(
@@ -7386,6 +7392,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
- Request metrics (total, cached, failed, by model/provider)
- Token usage and savings
- Cost tracking
+ - Canonical persisted display_session metrics for downstream dashboards
- Compression (CCR) statistics
- Telemetry/TOIN (data flywheel) statistics
- Cache and rate limiter stats
@@ -7483,6 +7490,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
cache_net_usd = prefix_cache_stats.get("totals", {}).get("net_savings_usd", 0.0)
total_tokens_all_layers = compression_tokens + cli_tokens_avoided
persistent_savings = m.savings_tracker.stats_preview()
+ display_session = persistent_savings.get("display_session", {})
return {
"summary": summary,
@@ -7558,6 +7566,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
else {},
"waste_signals": dict(m.waste_signals_total) if m.waste_signals_total else {},
"savings_history": m.savings_history[-100:], # Last 100 data points
+ "display_session": display_session,
"persistent_savings": persistent_savings,
"prefix_cache": prefix_cache_stats,
"cost": _merge_cost_stats(
@@ -7605,7 +7614,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
format: Literal["json", "csv"] = "json",
series: Literal["history", "hourly", "daily", "weekly", "monthly"] = "history",
):
- """Get durable proxy compression savings history for frontends."""
+ """Get durable proxy compression history plus display-session state."""
if format == "csv":
filename = f"headroom-stats-history-{series}.csv"
return Response(
diff --git a/tests/test_proxy_savings_history.py b/tests/test_proxy_savings_history.py
index fe1eac4bf..d354048b5 100644
--- a/tests/test_proxy_savings_history.py
+++ b/tests/test_proxy_savings_history.py
@@ -18,15 +18,21 @@ from headroom.proxy.savings_tracker import HEADROOM_SAVINGS_PATH_ENV_VAR, Saving
from headroom.proxy.server import ProxyConfig, create_app
-def _record_request(client: TestClient, *, model: str, tokens_saved: int) -> None:
+def _record_request(
+ client: TestClient,
+ *,
+ model: str,
+ tokens_saved: int,
+ input_tokens: int = 120,
+) -> None:
proxy = client.app.state.proxy
if proxy.cost_tracker:
- proxy.cost_tracker.record_tokens(model, tokens_saved, 120)
+ proxy.cost_tracker.record_tokens(model, tokens_saved, input_tokens)
asyncio.run(
proxy.metrics.record_request(
provider="openai",
model=model,
- input_tokens=120,
+ input_tokens=input_tokens,
output_tokens=24,
tokens_saved=tokens_saved,
latency_ms=15.0,
@@ -99,13 +105,15 @@ def test_savings_tracker_sanitizes_legacy_state_and_applies_retention(tmp_path):
tracker = SavingsTracker(path=str(path), max_history_points=1, max_history_age_days=2)
snapshot = tracker.snapshot()
- assert snapshot["schema_version"] == 1
+ assert snapshot["schema_version"] == 2
assert snapshot["lifetime"] == {
+ "requests": 0,
"tokens_saved": 30,
"compression_savings_usd": pytest.approx(0.03),
"total_input_tokens": 0,
"total_input_cost_usd": 0.0,
}
+ assert snapshot["display_session"] == savings_tracker_module._empty_display_session()
assert snapshot["history"] == [
{
"timestamp": "2026-03-27T09:00:00Z",
@@ -129,11 +137,13 @@ def test_non_dict_savings_state_resets_to_default(tmp_path):
snapshot = tracker.snapshot()
assert snapshot["lifetime"] == {
+ "requests": 0,
"tokens_saved": 0,
"compression_savings_usd": 0.0,
"total_input_tokens": 0,
"total_input_cost_usd": 0.0,
}
+ assert snapshot["display_session"] == savings_tracker_module._empty_display_session()
assert snapshot["history"] == []
@@ -223,9 +233,17 @@ def test_litellm_resolution_and_savings_estimation_fallbacks(monkeypatch):
assert savings_tracker_module._estimate_compression_savings_usd(
"claude-sonnet-4-6", 100
) == pytest.approx(0.2)
+ assert savings_tracker_module._estimate_input_cost_usd(
+ "claude-sonnet-4-6",
+ 100,
+ cache_read_tokens=10,
+ cache_write_tokens=5,
+ uncached_input_tokens=85,
+ ) == 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_input_cost_usd("gpt-4o", 100) == 0.0
monkeypatch.setattr(
fake_litellm,
@@ -237,6 +255,86 @@ def test_litellm_resolution_and_savings_estimation_fallbacks(monkeypatch):
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_input_cost_usd("gpt-4o", 100) == 0.0
+
+
+def test_display_session_rolls_after_inactivity_and_counts_zero_savings_requests(
+ tmp_path, monkeypatch
+):
+ path = tmp_path / "proxy_savings.json"
+ tracker = SavingsTracker(path=str(path), display_session_inactivity_minutes=30)
+ monkeypatch.setattr(
+ savings_tracker_module,
+ "_estimate_compression_savings_usd",
+ lambda model, tokens_saved: tokens_saved / 1000.0,
+ )
+ monkeypatch.setattr(
+ savings_tracker_module,
+ "_estimate_input_cost_usd",
+ lambda model, input_tokens, **kwargs: input_tokens / 1000.0,
+ )
+
+ tracker.record_request(
+ model="gpt-4o",
+ input_tokens=120,
+ tokens_saved=0,
+ timestamp="2026-03-27T09:00:00Z",
+ )
+ tracker.record_request(
+ model="gpt-4o",
+ input_tokens=80,
+ tokens_saved=20,
+ timestamp="2026-03-27T09:10:00Z",
+ )
+
+ monkeypatch.setattr(
+ savings_tracker_module,
+ "_utc_now",
+ lambda: datetime(2026, 3, 27, 9, 15, tzinfo=timezone.utc),
+ )
+ active_session = tracker.snapshot()["display_session"]
+ assert active_session == {
+ "requests": 2,
+ "tokens_saved": 20,
+ "compression_savings_usd": pytest.approx(0.02),
+ "total_input_tokens": 200,
+ "total_input_cost_usd": pytest.approx(0.2),
+ "savings_percent": pytest.approx(9.09),
+ "started_at": "2026-03-27T09:00:00Z",
+ "last_activity_at": "2026-03-27T09:10:00Z",
+ }
+
+ monkeypatch.setattr(
+ savings_tracker_module,
+ "_utc_now",
+ lambda: datetime(2026, 3, 27, 9, 45, tzinfo=timezone.utc),
+ )
+ assert tracker.snapshot()["display_session"] == savings_tracker_module._empty_display_session()
+
+ tracker.record_request(
+ model="gpt-4o",
+ input_tokens=50,
+ tokens_saved=5,
+ timestamp="2026-03-27T10:05:00Z",
+ )
+
+ monkeypatch.setattr(
+ savings_tracker_module,
+ "_utc_now",
+ lambda: datetime(2026, 3, 27, 10, 10, tzinfo=timezone.utc),
+ )
+ rolled = tracker.snapshot()
+ assert rolled["lifetime"]["requests"] == 3
+ assert rolled["display_session"] == {
+ "requests": 1,
+ "tokens_saved": 5,
+ "compression_savings_usd": pytest.approx(0.005),
+ "total_input_tokens": 50,
+ "total_input_cost_usd": pytest.approx(0.05),
+ "savings_percent": pytest.approx(9.09),
+ "started_at": "2026-03-27T10:05:00Z",
+ "last_activity_at": "2026-03-27T10:05:00Z",
+ }
def test_savings_tracker_rollups_preserve_spend_and_input_history(tmp_path, monkeypatch):
@@ -407,11 +505,15 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_p
history = client.get("/stats-history")
assert history.status_code == 200
history_data = history.json()
- assert history_data["schema_version"] == 1
+ assert history_data["schema_version"] == 2
assert history_data["storage_path"] == str(savings_path)
assert history_data["lifetime"]["tokens_saved"] == 40
assert history_data["lifetime"]["total_input_tokens"] == 120
assert history_data["lifetime"]["total_input_cost_usd"] == pytest.approx(0.24)
+ assert history_data["display_session"]["requests"] == 1
+ 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 history_data["exports"]["available_series"][-2:] == ["weekly", "monthly"]
assert history_data["series"]["hourly"][0]["total_input_tokens_delta"] == 120
@@ -419,10 +521,14 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_p
0.24
)
+ assert stats_data["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")
assert history.status_code == 200
assert history.json()["lifetime"]["tokens_saved"] == 40
+ assert history.json()["display_session"]["requests"] == 1
_record_request(client, model="gpt-4o", tokens_saved=15)
@@ -430,7 +536,12 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_p
assert updated["lifetime"]["tokens_saved"] == 55
assert updated["lifetime"]["total_input_tokens"] == 240
assert updated["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)
+ assert updated["lifetime"]["requests"] == 2
assert len(updated["history"]) == 2
+ assert updated["display_session"]["requests"] == 2
+ assert updated["display_session"]["tokens_saved"] == 55
+ assert updated["display_session"]["total_input_tokens"] == 240
+ assert updated["display_session"]["savings_percent"] == pytest.approx(18.64)
assert updated["series"]["daily"][0]["total_input_tokens_delta"] == 240
assert updated["series"]["daily"][0]["total_input_cost_usd_delta"] == pytest.approx(0.48)
@@ -438,6 +549,7 @@ def test_stats_history_persists_across_restarts_and_stats_stays_compatible(tmp_p
assert persisted["lifetime"]["tokens_saved"] == 55
assert persisted["lifetime"]["total_input_tokens"] == 240
assert persisted["lifetime"]["total_input_cost_usd"] == pytest.approx(0.48)
+ assert persisted["display_session"]["requests"] == 2
def test_stats_history_csv_export_is_frontend_friendly(tmp_path, monkeypatch):