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.

feat: persist proxy savings history

Garm69080be9668e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1a68f4ac2..66285057f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- **Durable proxy savings history**
+ - Persists proxy compression savings history locally at `~/.headroom/proxy_savings.json`
+ - Supports `HEADROOM_SAVINGS_PATH` to override the storage location
+ - Adds `/stats-history` with lifetime totals plus hourly/daily rollups for frontends
+ - Extends `/stats` with a `persistent_savings` block while keeping `savings_history` backward compatible
+ - Adds a historical mode to `/dashboard` backed by `/stats-history`
- **`headroom learn`** — Offline failure learning for coding agents
- Analyzes past conversation history (Claude Code, extensible to Cursor/Codex)
- **Success correlation**: for each failure, finds what succeeded after and extracts the specific correction
diff --git a/docs/metrics.md b/docs/metrics.md
index 5c41571cd..ade1ba9b0 100644
--- a/docs/metrics.md
+++ b/docs/metrics.md
@@ -12,6 +12,19 @@ curl http://localhost:8787/stats
```json
{
+ "persistent_savings": {
+ "lifetime": {
+ "tokens_saved": 12500,
+ "compression_savings_usd": 0.04
+ },
+ "recent_history": [
+ {
+ "timestamp": "2026-03-27T09:00:00Z",
+ "total_tokens_saved": 12500,
+ "compression_savings_usd": 0.04
+ }
+ ]
+ },
"requests": {
"total": 42,
"cached": 5,
@@ -35,6 +48,43 @@ curl http://localhost:8787/stats
}
```
+`/stats` keeps the existing live/session fields, including `savings_history`,
+for backward compatibility. The new `persistent_savings` block is durable local
+proxy compression history stored by default at `~/.headroom/proxy_savings.json`.
+Use `HEADROOM_SAVINGS_PATH` to override the file location.
+
+### Historical Savings Endpoint
+
+```bash
+curl http://localhost:8787/stats-history
+```
+
+```json
+{
+ "schema_version": 1,
+ "generated_at": "2026-03-27T09:10:00Z",
+ "lifetime": {
+ "tokens_saved": 12500,
+ "compression_savings_usd": 0.04
+ },
+ "history": [
+ {
+ "timestamp": "2026-03-27T09:00:00Z",
+ "total_tokens_saved": 12000,
+ "compression_savings_usd": 0.038
+ }
+ ],
+ "series": {
+ "hourly": [],
+ "daily": []
+ }
+}
+```
+
+`/stats-history` is the stable frontend-facing API for durable proxy
+compression history. It survives proxy restarts, tolerates missing or malformed
+state files, and powers the historical view in `/dashboard`.
+
### Prometheus Metrics
```bash
diff --git a/docs/proxy.md b/docs/proxy.md
index ef805df17..9b10a50b6 100644
--- a/docs/proxy.md
+++ b/docs/proxy.md
@@ -104,6 +104,28 @@ Response:
curl http://localhost:8787/stats
```
+`/stats` remains the live/session-oriented endpoint and now also includes a
+`persistent_savings` block with durable proxy compression lifetime totals plus a
+small recent preview. The existing `savings_history` field is still present and
+remains session-scoped for backward compatibility.
+
+### Historical Savings
+
+```bash
+curl http://localhost:8787/stats-history
+```
+
+`/stats-history` exposes durable proxy compression history for dashboards and
+other Headroom frontends. It returns:
+
+- lifetime proxy compression totals
+- bounded persisted checkpoint history
+- derived hourly and daily rollups for charts
+- UTC timestamps throughout
+
+By default the proxy stores this history at `~/.headroom/proxy_savings.json`.
+Set `HEADROOM_SAVINGS_PATH` to override the location.
+
### Prometheus Metrics
```bash
diff --git a/headroom/dashboard/templates/dashboard.html b/headroom/dashboard/templates/dashboard.html
index ee3a59c0e..bfc8dea97 100644
--- a/headroom/dashboard/templates/dashboard.html
+++ b/headroom/dashboard/templates/dashboard.html
@@ -54,6 +54,29 @@
</header>
<main class="p-6 max-w-7xl mx-auto">
+ <div class="flex flex-col gap-3 md:flex-row md:items-center md:justify-between mb-6">
+ <div>
+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-2">Dashboard View</div>
+ <div class="inline-flex rounded-lg border border-border bg-surface p-1">
+ <button class="px-3 py-1.5 text-sm rounded-md transition-colors"
+ :class="viewMode === 'live' ? 'bg-accent text-black' : 'text-gray-400 hover:text-gray-200'"
+ @click="viewMode = 'live'">
+ Current / Live
+ </button>
+ <button class="px-3 py-1.5 text-sm rounded-md transition-colors"
+ :class="viewMode === 'history' ? 'bg-accent text-black' : 'text-gray-400 hover:text-gray-200'"
+ @click="viewMode = 'history'">
+ Historical
+ </button>
+ </div>
+ </div>
+ <div class="text-xs text-gray-500" x-show="viewMode === 'history'">
+ Stored at <span class="font-mono text-gray-400" x-text="historyStats.storage_path || '~/.headroom/proxy_savings.json'"></span>
+ </div>
+ </div>
+
+ <template x-if="viewMode === 'live'">
+ <div>
<!-- Hero Metrics (reordered: Savings $ -> Tokens Saved % -> Quality Confidence -> Overhead) -->
<div class="grid grid-cols-2 md:grid-cols-4 gap-4 mb-6">
<!-- Savings ($) - Combined: compression + prefix cache -->
@@ -507,6 +530,172 @@
</table>
</div>
</div>
+ </div>
+ </template>
+
+ <template x-if="viewMode === 'history'">
+ <div>
+ <div class="grid grid-cols-2 md:grid-cols-4 gap-4 mb-6">
+ <div class="bg-surface rounded-lg p-4 border border-border">
+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Lifetime Compression Savings</div>
+ <div class="flex items-baseline gap-2">
+ <span class="text-3xl font-light tabular-nums text-emerald-400"
+ x-text="'$' + formatCurrency(historyStats.lifetime?.compression_savings_usd || 0)"></span>
+ </div>
+ <div class="mt-2 text-xs text-gray-500">
+ Proxy compression only
+ </div>
+ </div>
+
+ <div class="bg-surface rounded-lg p-4 border border-border">
+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Lifetime Tokens Saved</div>
+ <div class="flex items-baseline gap-2">
+ <span class="text-3xl font-light tabular-nums text-accent"
+ x-text="formatNumber(historyStats.lifetime?.tokens_saved || 0)"></span>
+ </div>
+ <div class="mt-2 text-xs text-gray-500"
+ x-text="formatNumber((historyStats.history || []).length) + ' recorded checkpoints'"></div>
+ </div>
+
+ <div class="bg-surface rounded-lg p-4 border border-border">
+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Active Days</div>
+ <div class="flex items-baseline gap-2">
+ <span class="text-3xl font-light tabular-nums"
+ x-text="formatNumber((historyStats.series?.daily || []).length)"></span>
+ </div>
+ <div class="mt-2 text-xs text-gray-500" x-text="historyWindowLabel"></div>
+ </div>
+
+ <div class="bg-surface rounded-lg p-4 border border-border">
+ <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Average Saved / Day</div>
+ <div class="flex items-baseline gap-2">
+ <span class="text-3xl font-light tabular-nums"
+ x-text="formatNumber(historyAverageTokensPerDay)"></span>
+ </div>
+ <div class="mt-2 text-xs text-gray-500">Based on persisted daily buckets</div>
+ </div>
+ </div>
+
+ <template x-if="hasHistoricalData">
+ <div>
+ <div class="grid grid-cols-1 lg:grid-cols-3 gap-4 mb-6">
+ <div class="bg-surface rounded-lg p-4 border border-border lg:col-span-2">
+ <div class="flex justify-between items-center mb-4">
+ <span class="text-sm font-medium text-gray-300">Historical Savings Trend</span>
+ <span class="text-xs text-gray-500 font-mono" x-text="historyTrendLabel"></span>
+ </div>
+ <template x-if="historicalTrend.length >= 2">
+ <div class="h-48">
+ <svg class="w-full h-full" viewBox="0 0 200 64" preserveAspectRatio="none">
+ <defs>
+ <linearGradient id="history-trend-gradient" x1="0%" y1="0%" x2="0%" y2="100%">
+ <stop offset="0%" style="stop-color:#22d3ee;stop-opacity:0.2"/>
+ <stop offset="100%" style="stop-color:#22d3ee;stop-opacity:0"/>
+ </linearGradient>
+ </defs>
+ <path :d="getObjectTrendArea(historicalTrend, 'total_tokens_saved')"
+ fill="url(#history-trend-gradient)"></path>
+ <path class="trend-line"
+ :d="getObjectTrendLine(historicalTrend, 'total_tokens_saved')"></path>
+ </svg>
+ </div>
+ </template>
+ <template x-if="historicalTrend.length < 2">
+ <div class="h-48 flex items-center justify-center text-sm text-gray-500 italic">
+ Historical trend data will appear after more saved checkpoints.
+ </div>
+ </template>
+ </div>
+
+ <div class="bg-surface rounded-lg p-4 border border-border">
+ <div class="text-sm font-medium mb-4 text-gray-300">Historical Summary</div>
+ <div class="space-y-3">
+ <div class="flex justify-between items-center">
+ <span class="text-sm text-gray-400">Latest total</span>
+ <span class="font-mono text-sm"
+ x-text="formatNumber(historyStats.lifetime?.tokens_saved || 0) + ' tokens'"></span>
+ </div>
+ <div class="flex justify-between items-center">
+ <span class="text-sm text-gray-400">Hourly buckets</span>
+ <span class="font-mono text-sm"
+ x-text="formatNumber((historyStats.series?.hourly || []).length)"></span>
+ </div>
+ <div class="flex justify-between items-center">
+ <span class="text-sm text-gray-400">Daily buckets</span>
+ <span class="font-mono text-sm"
+ x-text="formatNumber((historyStats.series?.daily || []).length)"></span>
+ </div>
+ <div class="flex justify-between items-center">
+ <span class="text-sm text-gray-400">Retention</span>
+ <span class="font-mono text-sm"
+ x-text="(historyStats.retention?.max_history_age_days || 0) + 'd / ' + formatNumber(historyStats.retention?.max_history_points || 0)"></span>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div class="grid grid-cols-1 lg:grid-cols-2 gap-4">
+ <div class="bg-surface rounded-lg p-4 border border-border">
+ <div class="text-sm font-medium mb-4 text-gray-300">Daily Savings</div>
+ <template x-if="(historyStats.series?.daily || []).length > 0">
+ <div class="space-y-3">
+ <template x-for="point in recentDailyHistory" :key="point.timestamp">
+ <div class="flex items-center justify-between">
+ <div>
+ <div class="text-sm text-gray-300" x-text="formatDate(point.timestamp)"></div>
+ <div class="text-xs text-gray-500"
+ x-text="formatNumber(point.total_tokens_saved) + ' cumulative'"></div>
+ </div>
+ <div class="text-right">
+ <div class="font-mono text-sm text-accent"
+ x-text="formatNumber(point.tokens_saved) + ' tokens'"></div>
+ <div class="text-xs text-emerald-400"
+ x-text="'$' + formatCurrency(point.compression_savings_usd_delta || 0)"></div>
+ </div>
+ </div>
+ </template>
+ </div>
+ </template>
+ <template x-if="(historyStats.series?.daily || []).length === 0">
+ <div class="text-sm text-gray-500 italic py-8 text-center">
+ Daily rollups will appear after persisted history spans at least one checkpoint.
+ </div>
+ </template>
+ </div>
+
+ <div class="bg-surface rounded-lg p-4 border border-border">
+ <div class="text-sm font-medium mb-4 text-gray-300">Recent Historical Checkpoints</div>
+ <div class="space-y-3">
+ <template x-for="point in recentHistoricalPoints" :key="point.timestamp">
+ <div class="flex items-center justify-between">
+ <div>
+ <div class="text-sm text-gray-300" x-text="formatDateTime(point.timestamp)"></div>
+ <div class="text-xs text-gray-500">Cumulative proxy compression savings</div>
+ </div>
+ <div class="text-right">
+ <div class="font-mono text-sm text-accent"
+ x-text="formatNumber(point.total_tokens_saved) + ' tokens'"></div>
+ <div class="text-xs text-emerald-400"
+ x-text="'$' + formatCurrency(point.compression_savings_usd || 0)"></div>
+ </div>
+ </div>
+ </template>
+ </div>
+ </div>
+ </div>
+ </div>
+ </template>
+
+ <template x-if="!hasHistoricalData">
+ <div class="bg-surface rounded-lg border border-border p-10 text-center">
+ <div class="text-lg text-gray-300 mb-2">No persisted savings history yet</div>
+ <div class="text-sm text-gray-500 max-w-2xl mx-auto">
+ Historical data is written locally after proxy requests save tokens. Keep using Headroom and this view will fill in automatically across restarts.
+ </div>
+ </div>
+ </template>
+ </div>
+ </template>
</main>
@@ -526,9 +715,11 @@
function dashboard() {
return {
stats: {},
+ historyStats: {},
healthy: true,
version: '0.3.0',
lastUpdate: 'never',
+ viewMode: 'live',
requestHistory: [],
savingsHistory: [],
expandedRows: {},
@@ -548,12 +739,14 @@
async fetchStats() {
try {
- const [statsRes, healthRes] = await Promise.all([
+ const [statsRes, historyRes, healthRes] = await Promise.all([
fetch('/stats'),
+ fetch('/stats-history'),
fetch('/health')
]);
this.stats = await statsRes.json();
+ this.historyStats = await historyRes.json();
const health = await healthRes.json();
this.healthy = health.status === 'healthy';
this.version = health.version || '0.3.0';
@@ -600,6 +793,24 @@
return d.toLocaleTimeString();
},
+ formatDate(ts) {
+ if (!ts) return '-';
+ return new Date(ts).toLocaleDateString(undefined, {
+ month: 'short',
+ day: 'numeric',
+ });
+ },
+
+ formatDateTime(ts) {
+ if (!ts) return '-';
+ return new Date(ts).toLocaleString(undefined, {
+ month: 'short',
+ day: 'numeric',
+ hour: '2-digit',
+ minute: '2-digit',
+ });
+ },
+
truncateModel(model) {
if (!model) return '-';
return model.replace(/^(anthropic\.|openai\.|bedrock\/)/, '')
@@ -607,6 +818,52 @@
.substring(0, 20);
},
+ // --- Historical View ---
+
+ get hasHistoricalData() {
+ return (this.historyStats.history || []).length > 0;
+ },
+
+ get historicalTrend() {
+ const daily = this.historyStats.series?.daily || [];
+ if (daily.length >= 2) return daily;
+ const hourly = this.historyStats.series?.hourly || [];
+ if (hourly.length >= 2) return hourly;
+ return this.historyStats.history || [];
+ },
+
+ get historyTrendLabel() {
+ const daily = this.historyStats.series?.daily || [];
+ if (daily.length >= 2) return 'Daily cumulative savings';
+ const hourly = this.historyStats.series?.hourly || [];
+ if (hourly.length >= 2) return 'Hourly cumulative savings';
+ return 'Checkpoint history';
+ },
+
+ get historyWindowLabel() {
+ const history = this.historyStats.history || [];
+ if (history.length === 0) return 'Waiting for saved requests';
+ const first = history[0]?.timestamp;
+ const last = history[history.length - 1]?.timestamp;
+ if (!first || !last) return 'Persisted locally';
+ return this.formatDate(first) + ' to ' + this.formatDate(last);
+ },
+
+ get historyAverageTokensPerDay() {
+ const daily = this.historyStats.series?.daily || [];
+ const lifetime = this.historyStats.lifetime?.tokens_saved || 0;
+ if (daily.length === 0) return 0;
+ return Math.round(lifetime / daily.length);
+ },
+
+ get recentDailyHistory() {
+ return [...(this.historyStats.series?.daily || [])].slice(-7).reverse();
+ },
+
+ get recentHistoricalPoints() {
+ return [...(this.historyStats.history || [])].slice(-8).reverse();
+ },
+
// --- Prefix Cache ---
get cacheSavingsPercent() {
@@ -759,7 +1016,7 @@
getTrendLine(history) {
if (!history || history.length < 2) return '';
- const values = history.map(h => h[1]);
+ const values = history.map(h => Array.isArray(h) ? h[1] : (h?.total_tokens_saved || 0));
const min = Math.min(...values);
const max = Math.max(...values);
const range = max - min || 1;
@@ -779,6 +1036,29 @@
if (!line) return '';
return line + ` L200,64 L0,64 Z`;
},
+
+ getObjectTrendLine(history, valueKey) {
+ if (!history || history.length < 2) return '';
+ const values = history.map(point => point?.[valueKey] || 0);
+ const min = Math.min(...values);
+ const max = Math.max(...values);
+ const range = max - min || 1;
+
+ const points = values.map((value, index) => {
+ const x = (index / (values.length - 1)) * 200;
+ const y = 60 - ((value - min) / range) * 56;
+ return `${x},${y}`;
+ });
+
+ return 'M' + points.join(' L');
+ },
+
+ getObjectTrendArea(history, valueKey) {
+ if (!history || history.length < 2) return '';
+ const line = this.getObjectTrendLine(history, valueKey);
+ if (!line) return '';
+ return line + ` L200,64 L0,64 Z`;
+ },
};
}
</script>
diff --git a/headroom/proxy/savings_tracker.py b/headroom/proxy/savings_tracker.py
new file mode 100644
index 000000000..b92987fb5
--- /dev/null
+++ b/headroom/proxy/savings_tracker.py
@@ -0,0 +1,427 @@
+"""Durable proxy savings history 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.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+import threading
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+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
+DEFAULT_MAX_HISTORY_POINTS = 5000
+DEFAULT_MAX_HISTORY_AGE_DAYS = 365
+
+try:
+ import litellm
+
+ LITELLM_AVAILABLE = True
+except ImportError:
+ LITELLM_AVAILABLE = False
+
+
+def get_default_savings_storage_path() -> str:
+ """Return the configured savings storage path."""
+ env_path = os.environ.get(HEADROOM_SAVINGS_PATH_ENV_VAR, "").strip()
+ if env_path:
+ return env_path
+ return str(Path.home() / DEFAULT_SAVINGS_DIR / DEFAULT_SAVINGS_FILE)
+
+
+def _utc_now() -> datetime:
+ return datetime.now(UTC)
+
+
+def _to_utc_iso(dt: datetime) -> str:
+ return dt.astimezone(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _parse_timestamp(value: Any) -> datetime | None:
+ if not isinstance(value, str) or not value:
+ return None
+
+ normalized = value.replace("Z", "+00:00")
+ try:
+ dt = datetime.fromisoformat(normalized)
+ except ValueError:
+ return None
+
+ if dt.tzinfo is None:
+ dt = dt.replace(tzinfo=UTC)
+ return dt.astimezone(UTC)
+
+
+def _coerce_int(value: Any, default: int = 0) -> int:
+ try:
+ return max(int(value), 0)
+ except (TypeError, ValueError):
+ return default
+
+
+def _coerce_float(value: Any, default: float = 0.0) -> float:
+ try:
+ return max(float(value), 0.0)
+ except (TypeError, ValueError):
+ return default
+
+
+def _resolve_litellm_model(model: str) -> str:
+ """Resolve model name to one LiteLLM recognizes."""
+ if not LITELLM_AVAILABLE:
+ return model
+
+ try:
+ litellm.cost_per_token(model=model, prompt_tokens=1, completion_tokens=0)
+ return model
+ except Exception:
+ pass
+
+ prefixes = {
+ "claude-": "anthropic/",
+ "gpt-": "openai/",
+ "o1-": "openai/",
+ "o3-": "openai/",
+ "o4-": "openai/",
+ "gemini-": "google/",
+ }
+ for pattern, prefix in prefixes.items():
+ if model.startswith(pattern):
+ candidate = f"{prefix}{model}"
+ try:
+ litellm.cost_per_token(model=candidate, prompt_tokens=1, completion_tokens=0)
+ return candidate
+ except Exception:
+ break
+
+ return model
+
+
+def _estimate_compression_savings_usd(model: str, tokens_saved: int) -> float:
+ """Estimate compression savings in USD from saved input tokens."""
+ if tokens_saved <= 0 or not LITELLM_AVAILABLE:
+ return 0.0
+
+ 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
+ return float(tokens_saved) * 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
+ total_tokens_saved = 0
+ compression_savings_usd = 0.0
+
+ 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"))
+ elif isinstance(entry, (list, tuple)) and len(entry) >= 2:
+ timestamp = _parse_timestamp(entry[0])
+ total_tokens_saved = _coerce_int(entry[1])
+ if len(entry) >= 3:
+ compression_savings_usd = _coerce_float(entry[2])
+ else:
+ return None
+
+ if timestamp is None:
+ return None
+
+ return {
+ "timestamp": _to_utc_iso(timestamp),
+ "total_tokens_saved": total_tokens_saved,
+ "compression_savings_usd": round(compression_savings_usd, 6),
+ }
+
+
+class SavingsTracker:
+ """Persist bounded proxy compression savings history."""
+
+ def __init__(
+ self,
+ path: str | None = None,
+ max_history_points: int = DEFAULT_MAX_HISTORY_POINTS,
+ max_history_age_days: int = DEFAULT_MAX_HISTORY_AGE_DAYS,
+ ) -> 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._lock = threading.Lock()
+ self._state = self._load_state()
+
+ @property
+ def storage_path(self) -> str:
+ return str(self._path)
+
+ def record_compression_savings(
+ self,
+ *,
+ model: str,
+ tokens_saved: int,
+ timestamp: datetime | str | None = None,
+ ) -> bool:
+ """Persist a cumulative savings checkpoint when compression changed totals."""
+ delta_tokens = _coerce_int(tokens_saved)
+ if delta_tokens <= 0:
+ return False
+
+ timestamp_dt = (
+ _parse_timestamp(timestamp)
+ if isinstance(timestamp, str)
+ else timestamp.astimezone(UTC)
+ if isinstance(timestamp, datetime)
+ else _utc_now()
+ )
+ if timestamp_dt is None:
+ timestamp_dt = _utc_now()
+
+ delta_usd = _estimate_compression_savings_usd(model, delta_tokens)
+
+ with self._lock:
+ lifetime = self._state["lifetime"]
+ lifetime["tokens_saved"] += delta_tokens
+ lifetime["compression_savings_usd"] = round(
+ lifetime["compression_savings_usd"] + delta_usd, 6
+ )
+
+ self._state["history"].append(
+ {
+ "timestamp": _to_utc_iso(timestamp_dt),
+ "total_tokens_saved": lifetime["tokens_saved"],
+ "compression_savings_usd": lifetime["compression_savings_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()
+ return {
+ "schema_version": snapshot["schema_version"],
+ "storage_path": snapshot["storage_path"],
+ "lifetime": snapshot["lifetime"],
+ "history_points": len(snapshot["history"]),
+ "recent_history": snapshot["history"][-recent_points:],
+ "retention": snapshot["retention"],
+ }
+
+ def history_response(self) -> dict[str, Any]:
+ """Return frontend-friendly historical data for `/stats-history`."""
+ snapshot = self.snapshot()
+ history = snapshot["history"]
+ return {
+ "schema_version": snapshot["schema_version"],
+ "generated_at": _to_utc_iso(_utc_now()),
+ "storage_path": snapshot["storage_path"],
+ "lifetime": snapshot["lifetime"],
+ "history": history,
+ "series": {
+ "hourly": self._build_rollup(history, bucket="hour"),
+ "daily": self._build_rollup(history, bucket="day"),
+ },
+ "retention": snapshot["retention"],
+ }
+
+ def snapshot(self) -> dict[str, Any]:
+ with self._lock:
+ history = [dict(item) for item in self._state["history"]]
+ return {
+ "schema_version": SCHEMA_VERSION,
+ "storage_path": str(self._path),
+ "lifetime": dict(self._state["lifetime"]),
+ "history": history,
+ "retention": {
+ "max_history_points": self._max_history_points,
+ "max_history_age_days": self._max_history_age_days,
+ },
+ }
+
+ def _default_state(self) -> dict[str, Any]:
+ return {
+ "schema_version": SCHEMA_VERSION,
+ "lifetime": {"tokens_saved": 0, "compression_savings_usd": 0.0},
+ "history": [],
+ }
+
+ def _load_state(self) -> dict[str, Any]:
+ if not self._path.exists():
+ return self._default_state()
+
+ try:
+ with open(self._path, encoding="utf-8") as f:
+ raw = json.load(f)
+ except (json.JSONDecodeError, OSError) as e:
+ logger.warning("Failed to load savings history from %s: %s", self._path, e)
+ return self._default_state()
+
+ return self._sanitize_state(raw)
+
+ def _sanitize_state(self, raw: Any) -> dict[str, Any]:
+ if not isinstance(raw, dict):
+ return self._default_state()
+
+ history_raw = raw.get("history", [])
+ normalized_history = []
+ if isinstance(history_raw, list):
+ for item in history_raw:
+ normalized = _normalize_history_entry(item)
+ if normalized is not None:
+ normalized_history.append(normalized)
+
+ normalized_history.sort(key=lambda item: item["timestamp"])
+
+ lifetime_raw = raw.get("lifetime", {})
+ lifetime_tokens_saved = 0
+ lifetime_savings_usd = 0.0
+ if isinstance(lifetime_raw, dict):
+ lifetime_tokens_saved = _coerce_int(lifetime_raw.get("tokens_saved"))
+ lifetime_savings_usd = _coerce_float(lifetime_raw.get("compression_savings_usd"))
+
+ if normalized_history:
+ last = normalized_history[-1]
+ lifetime_tokens_saved = max(lifetime_tokens_saved, last["total_tokens_saved"])
+ lifetime_savings_usd = max(
+ lifetime_savings_usd,
+ _coerce_float(last["compression_savings_usd"]),
+ )
+
+ state = {
+ "schema_version": SCHEMA_VERSION,
+ "lifetime": {
+ "tokens_saved": lifetime_tokens_saved,
+ "compression_savings_usd": round(lifetime_savings_usd, 6),
+ },
+ "history": normalized_history,
+ }
+
+ if normalized_history:
+ 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:
+ self._trim_history_locked(reference_time=reference_time)
+ state = self._state
+ finally:
+ if original_state is not None:
+ self._state = original_state
+
+ return state
+
+ def _trim_history_locked(self, reference_time: datetime | None = None) -> None:
+ history = self._state["history"]
+ if not history:
+ return
+
+ if self._max_history_age_days > 0:
+ cutoff = (reference_time or _utc_now()) - timedelta(days=self._max_history_age_days)
+ filtered = [
+ item
+ for item in history
+ if (_parse_timestamp(item["timestamp"]) or _utc_now()) >= cutoff
+ ]
+ if not filtered:
+ filtered = [history[-1]]
+ history = filtered
+
+ if self._max_history_points > 0 and len(history) > self._max_history_points:
+ history = history[-self._max_history_points :]
+
+ self._state["history"] = history
+
+ def _save_locked(self) -> None:
+ try:
+ self._path.parent.mkdir(parents=True, exist_ok=True)
+ payload = {
+ "schema_version": SCHEMA_VERSION,
+ "lifetime": self._state["lifetime"],
+ "history": self._state["history"],
+ }
+ json_data = json.dumps(payload, indent=2)
+
+ fd, tmp_path = tempfile.mkstemp(
+ dir=self._path.parent,
+ prefix=".proxy_savings_",
+ suffix=".tmp",
+ )
+ try:
+ with os.fdopen(fd, "w", encoding="utf-8") as f:
+ f.write(json_data)
+ f.flush()
+ os.fsync(f.fileno())
+ Path(tmp_path).replace(self._path)
+ except Exception:
+ try:
+ Path(tmp_path).unlink()
+ except OSError:
+ pass
+ raise
+ except OSError as e:
+ logger.warning("Failed to save savings history to %s: %s", self._path, e)
+
+ def _build_rollup(self, history: list[dict[str, Any]], bucket: str) -> list[dict[str, Any]]:
+ if not history:
+ return []
+
+ aggregated: dict[str, dict[str, Any]] = {}
+ prev_total_tokens = 0
+ prev_total_usd = 0.0
+
+ for point in history:
+ timestamp = _parse_timestamp(point["timestamp"])
+ if timestamp is None:
+ continue
+
+ if bucket == "hour":
+ bucket_start = timestamp.replace(minute=0, second=0, microsecond=0)
+ else:
+ bucket_start = timestamp.replace(hour=0, minute=0, second=0, microsecond=0)
+
+ bucket_key = _to_utc_iso(bucket_start)
+ total_tokens_saved = _coerce_int(point.get("total_tokens_saved"))
+ total_usd = _coerce_float(point.get("compression_savings_usd"))
+ delta_tokens = max(total_tokens_saved - prev_total_tokens, 0)
+ delta_usd = max(total_usd - prev_total_usd, 0.0)
+
+ prev_total_tokens = total_tokens_saved
+ prev_total_usd = total_usd
+
+ entry = aggregated.setdefault(
+ bucket_key,
+ {
+ "timestamp": bucket_key,
+ "tokens_saved": 0,
+ "compression_savings_usd_delta": 0.0,
+ "total_tokens_saved": total_tokens_saved,
+ "compression_savings_usd": total_usd,
+ },
+ )
+ entry["tokens_saved"] += delta_tokens
+ entry["compression_savings_usd_delta"] = round(
+ entry["compression_savings_usd_delta"] + delta_usd,
+ 6,
+ )
+ entry["total_tokens_saved"] = total_tokens_saved
+ entry["compression_savings_usd"] = round(total_usd, 6)
+
+ return list(aggregated.values())
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index a5a62c3a2..6aa78ee83 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -89,6 +89,7 @@ from headroom.config import (
from headroom.dashboard import get_dashboard_html
from headroom.providers import AnthropicProvider, OpenAIProvider
from headroom.proxy.memory_handler import MemoryConfig, MemoryHandler
+from headroom.proxy.savings_tracker import SavingsTracker
from headroom.telemetry import get_telemetry_collector
from headroom.telemetry.toin import get_toin
from headroom.tokenizers import get_tokenizer
@@ -1252,7 +1253,7 @@ class CostTracker:
class PrometheusMetrics:
"""Prometheus-compatible metrics."""
- def __init__(self):
+ def __init__(self, savings_tracker: SavingsTracker | None = None):
self.requests_total = 0
self.requests_by_provider: dict[str, int] = defaultdict(int)
self.requests_by_model: dict[str, int] = defaultdict(int)
@@ -1315,6 +1316,7 @@ class PrometheusMetrics:
# Cumulative savings history (timestamp → cumulative tokens saved)
self.savings_history: list[tuple[str, int]] = []
+ self.savings_tracker = savings_tracker or SavingsTracker()
self._lock = asyncio.Lock()
@@ -1406,6 +1408,12 @@ class PrometheusMetrics:
if len(self.savings_history) > 500:
self.savings_history = self.savings_history[-500:]
+ if tokens_saved > 0:
+ self.savings_tracker.record_compression_savings(
+ model=model,
+ tokens_saved=tokens_saved,
+ )
+
async def record_rate_limited(self):
async with self._lock:
self.requests_rate_limited += 1
@@ -2006,6 +2014,7 @@ class HeadroomProxy:
logger.info(f"CCR (Compress-Cache-Retrieve): ENABLED ({', '.join(ccr_features)})")
else:
logger.info("CCR: DISABLED")
+ logger.info(f"Savings history: {self.metrics.savings_tracker.storage_path}")
async def shutdown(self):
"""Cleanup async resources."""
@@ -6997,6 +7006,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
version=__version__,
lifespan=lifespan,
)
+ app.state.proxy = proxy
# CORS
app.add_middleware(
@@ -7124,6 +7134,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
compression_tokens = m.tokens_saved_total
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()
return {
"summary": summary,
@@ -7199,6 +7210,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
+ "persistent_savings": persistent_savings,
"prefix_cache": prefix_cache_stats,
"cost": _merge_cost_stats(
proxy.cost_tracker.stats() if proxy.cost_tracker else None,
@@ -7240,6 +7252,11 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
"recent_requests": proxy.logger.get_recent(10) if proxy.logger else [],
}
+ @app.get("/stats-history")
+ async def stats_history():
+ """Get durable proxy compression savings history for frontends."""
+ return proxy.metrics.savings_tracker.history_response()
+
@app.get("/metrics")
async def metrics():
"""Prometheus metrics endpoint."""
diff --git a/tests/test_proxy_savings_history.py b/tests/test_proxy_savings_history.py
new file mode 100644
index 000000000..a74fcad0f
--- /dev/null
+++ b/tests/test_proxy_savings_history.py
@@ -0,0 +1,171 @@
+"""Tests for durable proxy savings history."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import pytest
+
+pytest.importorskip("fastapi")
+
+from fastapi.testclient import TestClient
+
+from headroom.proxy.savings_tracker import SavingsTracker
+from headroom.proxy.server import ProxyConfig, create_app
+
+
+def _record_request(client: TestClient, *, model: str, tokens_saved: int) -> None:
+ proxy = client.app.state.proxy
+ asyncio.run(
+ proxy.metrics.record_request(
+ provider="openai",
+ model=model,
+ input_tokens=120,
+ output_tokens=24,
+ tokens_saved=tokens_saved,
+ latency_ms=15.0,
+ )
+ )
+
+
+def test_savings_tracker_rollups_are_chart_friendly(tmp_path, monkeypatch):
+ path = tmp_path / "proxy_savings.json"
+ 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,
+ )
+
+ tracker.record_compression_savings(
+ model="gpt-4o",
+ tokens_saved=100,
+ timestamp="2026-03-27T09:10:00Z",
+ )
+ tracker.record_compression_savings(
+ model="gpt-4o",
+ tokens_saved=50,
+ timestamp="2026-03-27T09:40:00Z",
+ )
+ tracker.record_compression_savings(
+ model="gpt-4o",
+ tokens_saved=25,
+ timestamp="2026-03-27T10:05:00Z",
+ )
+ tracker.record_compression_savings(
+ model="gpt-4o",
+ tokens_saved=10,
+ timestamp="2026-03-28T08:00:00Z",
+ )
+
+ response = tracker.history_response()
+
+ assert response["lifetime"]["tokens_saved"] == 185
+ assert response["lifetime"]["compression_savings_usd"] == pytest.approx(0.185)
+ assert len(response["history"]) == 4
+
+ hourly = response["series"]["hourly"]
+ assert [point["timestamp"] for point in hourly] == [
+ "2026-03-27T09:00:00Z",
+ "2026-03-27T10:00:00Z",
+ "2026-03-28T08:00:00Z",
+ ]
+ assert hourly[0]["tokens_saved"] == 150
+ assert hourly[0]["total_tokens_saved"] == 150
+ assert hourly[1]["tokens_saved"] == 25
+ assert hourly[1]["total_tokens_saved"] == 175
+ assert hourly[2]["tokens_saved"] == 10
+ assert hourly[2]["total_tokens_saved"] == 185
+
+ daily = response["series"]["daily"]
+ assert [point["timestamp"] for point in daily] == [
+ "2026-03-27T00:00:00Z",
+ "2026-03-28T00:00:00Z",
+ ]
+ assert daily[0]["tokens_saved"] == 175
+ assert daily[0]["total_tokens_saved"] == 175
+ assert daily[1]["tokens_saved"] == 10
+ assert daily[1]["total_tokens_saved"] == 185
+
+
+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))
+
+ config = ProxyConfig(
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ log_requests=False,
+ )
+
+ with TestClient(create_app(config)) as client:
+ _record_request(client, model="gpt-4o", tokens_saved=40)
+
+ stats = client.get("/stats")
+ assert stats.status_code == 200
+ stats_data = stats.json()
+ assert "savings_history" in stats_data
+ assert "persistent_savings" in stats_data
+ assert all(len(point) == 2 for point in stats_data["savings_history"])
+ assert stats_data["persistent_savings"]["lifetime"]["tokens_saved"] == 40
+ assert stats_data["persistent_savings"]["storage_path"] == str(savings_path)
+
+ history = client.get("/stats-history")
+ assert history.status_code == 200
+ history_data = history.json()
+ assert history_data["schema_version"] == 1
+ assert history_data["storage_path"] == str(savings_path)
+ assert history_data["lifetime"]["tokens_saved"] == 40
+ assert list(history_data["series"].keys()) == ["hourly", "daily"]
+
+ with TestClient(create_app(config)) as client:
+ history = client.get("/stats-history")
+ assert history.status_code == 200
+ assert history.json()["lifetime"]["tokens_saved"] == 40
+
+ _record_request(client, model="gpt-4o", tokens_saved=15)
+
+ updated = client.get("/stats-history").json()
+ assert updated["lifetime"]["tokens_saved"] == 55
+ assert len(updated["history"]) == 2
+
+ persisted = json.loads(savings_path.read_text())
+ assert persisted["lifetime"]["tokens_saved"] == 55
+
+
+def test_malformed_savings_state_is_ignored_safely(tmp_path, monkeypatch):
+ savings_path = tmp_path / "proxy_savings.json"
+ savings_path.write_text("{not valid json", encoding="utf-8")
+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
+
+ config = ProxyConfig(
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ log_requests=False,
+ )
+
+ with TestClient(create_app(config)) as client:
+ response = client.get("/stats-history")
+ assert response.status_code == 200
+ data = response.json()
+ assert data["lifetime"]["tokens_saved"] == 0
+ assert data["history"] == []
+
+
+def test_dashboard_includes_history_toggle_and_endpoint(tmp_path, monkeypatch):
+ savings_path = tmp_path / "proxy_savings.json"
+ monkeypatch.setenv("HEADROOM_SAVINGS_PATH", str(savings_path))
+
+ config = ProxyConfig(
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ log_requests=False,
+ )
+
+ with TestClient(create_app(config)) as client:
+ response = client.get("/dashboard")
+ assert response.status_code == 200
+ html = response.text
+ assert "Current / Live" in html
+ assert "Historical" in html
+ assert "fetch('/stats-history')" in html