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: add clean session summary to /stats and MCP headroom_stats

chopratejas04fecd7865fe
diff --git a/headroom/ccr/mcp_server.py b/headroom/ccr/mcp_server.py
index 4b4d0333c..833c4bc3d 100644
--- a/headroom/ccr/mcp_server.py
+++ b/headroom/ccr/mcp_server.py
@@ -69,6 +69,85 @@ logger = logging.getLogger("headroom.ccr.mcp")
DEFAULT_PROXY_URL = os.environ.get("HEADROOM_PROXY_URL", "http://127.0.0.1:8787")
+
+def _format_session_summary(summary: dict[str, Any], local_stats: dict[str, Any]) -> str:
+ """Format the proxy summary + local MCP stats into clean readable text."""
+ lines: list[str] = []
+ lines.append("Headroom Session Summary")
+ lines.append("=" * 40)
+
+ mode = summary.get("mode", "cost_savings")
+ api_reqs = summary.get("api_requests", 0)
+ model = summary.get("primary_model", "unknown")
+ lines.append(f"Mode: {mode} | {api_reqs} API requests | {model}")
+ lines.append("")
+
+ # Compression section
+ comp = summary.get("compression", {})
+ n_compressed = comp.get("requests_compressed", 0)
+ if n_compressed > 0:
+ lines.append(f"Compression ({n_compressed} requests compressed):")
+ lines.append(f" Avg compression: {comp.get('avg_compression_pct', 0)}%")
+ best = comp.get("best_compression_pct", 0)
+ detail = comp.get("best_detail", "")
+ if best > 0:
+ lines.append(f" Best compression: {best}% ({detail})")
+ removed = comp.get("total_tokens_removed", 0)
+ lines.append(f" Tokens removed: {removed:,}")
+ else:
+ lines.append("Compression: no requests compressed yet")
+ lines.append("")
+
+ # Uncompressed reasons
+ uncomp = summary.get("uncompressed_requests", {})
+ if uncomp:
+ total_uncomp = sum(uncomp.values())
+ lines.append(f"Uncompressed requests ({total_uncomp}):")
+ reason_labels = {
+ "prefix_frozen": "Prefix-frozen (cached by provider)",
+ "too_small": "Too small (< 500 tokens)",
+ "passthrough": "Passthrough (token counting)",
+ "no_compressible_content": "No compressible content (user/assistant only)",
+ }
+ for key, count in uncomp.items():
+ label = reason_labels.get(key, key)
+ lines.append(f" {label}: {count}")
+ lines.append("")
+
+ # Cost section
+ cost = summary.get("cost", {})
+ without = cost.get("without_headroom_usd", 0)
+ with_hr = cost.get("with_headroom_usd", 0)
+ saved = cost.get("total_saved_usd", 0)
+ pct = cost.get("savings_pct", 0)
+ if without > 0:
+ lines.append("Cost Impact:")
+ lines.append(f" Without Headroom: ${without:.2f}")
+ lines.append(f" With Headroom: ${with_hr:.2f}")
+ lines.append(f" You saved: ${saved:.2f} ({pct}%)")
+ breakdown = cost.get("breakdown", {})
+ cache_s = breakdown.get("cache_savings_usd", 0)
+ comp_s = breakdown.get("compression_savings_usd", 0)
+ if cache_s > 0 or comp_s > 0:
+ lines.append(f" Cache savings: ${cache_s:.2f}")
+ lines.append(f" Compression savings: ${comp_s:.2f}")
+ lines.append("")
+
+ # MCP-local stats (compressions done by MCP tool directly)
+ local_compressions = local_stats.get("compressions", 0)
+ local_saved = local_stats.get("total_tokens_saved", 0)
+ if local_compressions > 0:
+ lines.append(f"MCP Tool: {local_compressions} compressions, {local_saved:,} tokens saved")
+ lines.append("")
+
+ # Tip
+ tip = summary.get("tip")
+ if tip:
+ lines.append(f"Tip: {tip}")
+
+ return "\n".join(lines)
+
+
# Session-scoped TTL: content persists for the session (1 hour), not 5 minutes.
# The MCP server process lives as long as the coding session.
MCP_SESSION_TTL = 3600
@@ -542,45 +621,55 @@ class HeadroomMCPServer:
"estimated_cost_saved_usd": round(all_saved * 3.0 / 1_000_000, 4),
}
- # Fetch proxy stats (prefix cache hits, etc.) if proxy is reachable
+ # Fetch proxy stats and format summary if proxy is reachable
if self.check_proxy and HTTPX_AVAILABLE:
- proxy_stats = await self._fetch_proxy_stats()
- if proxy_stats:
- stats["proxy"] = proxy_stats
+ proxy_data = await self._fetch_full_proxy_stats()
+ if proxy_data:
+ summary = proxy_data.get("summary")
+ if summary:
+ # Return clean formatted summary instead of raw JSON
+ formatted = _format_session_summary(summary, stats)
+ return [TextContent(type="text", text=formatted)]
+ # Fallback: add proxy stats to local stats
+ proxy_stats = self._extract_proxy_stats(proxy_data)
+ if proxy_stats:
+ stats["proxy"] = proxy_stats
return [TextContent(type="text", text=json.dumps(stats, indent=2))]
- async def _fetch_proxy_stats(self) -> dict[str, Any] | None:
- """Fetch stats from the proxy, including prefix cache hit info."""
+ async def _fetch_full_proxy_stats(self) -> dict[str, Any] | None:
+ """Fetch full stats from the proxy (includes summary)."""
try:
if self._http_client is None:
self._http_client = httpx.AsyncClient(timeout=15.0)
response = await self._http_client.get(f"{self.proxy_url}/stats")
if response.status_code != 200:
return None
- data = response.json()
- # Extract the most useful fields
- result: dict[str, Any] = {}
- if "requests_total" in data:
- result["requests_total"] = data["requests_total"]
- if "tokens_saved_total" in data:
- result["tokens_saved_total"] = data["tokens_saved_total"]
- # Prefix cache stats
- cache = data.get("cache", data.get("caching", {}))
- if cache:
- result["cache"] = {
- "hits": cache.get("hits", cache.get("cache_hits", 0)),
- "misses": cache.get("misses", cache.get("cache_misses", 0)),
- "hit_rate": cache.get("hit_rate", cache.get("cache_hit_rate", 0)),
- }
- # Cost tracking
- cost = data.get("cost", {})
- if cost:
- result["cost_saved_usd"] = cost.get("total_saved", cost.get("saved", 0))
- return result if result else None
+ result: dict[str, Any] = response.json()
+ return result
except Exception:
return None
+ @staticmethod
+ def _extract_proxy_stats(data: dict[str, Any]) -> dict[str, Any] | None:
+ """Extract key fields from full proxy stats (fallback when no summary)."""
+ result: dict[str, Any] = {}
+ if "requests_total" in data:
+ result["requests_total"] = data["requests_total"]
+ if "tokens_saved_total" in data:
+ result["tokens_saved_total"] = data["tokens_saved_total"]
+ cache = data.get("cache", data.get("caching", {}))
+ if cache:
+ result["cache"] = {
+ "hits": cache.get("hits", cache.get("cache_hits", 0)),
+ "misses": cache.get("misses", cache.get("cache_misses", 0)),
+ "hit_rate": cache.get("hit_rate", cache.get("cache_hit_rate", 0)),
+ }
+ cost = data.get("cost", {})
+ if cost:
+ result["cost_saved_usd"] = cost.get("total_saved", cost.get("saved", 0))
+ return result if result else None
+
async def run_stdio(self) -> None:
"""Run the server with stdio transport."""
async with stdio_server() as (read_stream, write_stream):
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 79cb576e8..ebf70ed97 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -412,6 +412,116 @@ def _merge_cost_stats(
}
+def _build_session_summary(
+ proxy: HeadroomProxy,
+ metrics: Any,
+ prefix_cache_stats: dict,
+ cli_tokens_avoided: int,
+ total_tokens_before: int,
+) -> dict[str, Any]:
+ """Build a human-readable session summary from metrics and request logs.
+
+ This is the headline view users see first in /stats — designed to answer
+ "is Headroom working?" at a glance.
+ """
+ # Analyze per-request compression from the logger
+ compressed_requests: list[dict] = []
+ uncompressed_reasons: dict[str, int] = {
+ "prefix_frozen": 0,
+ "too_small": 0,
+ "passthrough": 0,
+ "no_compressible_content": 0,
+ }
+
+ if proxy.logger:
+ for entry in proxy.logger._logs:
+ if entry.model and "count_tokens" in entry.model:
+ uncompressed_reasons["passthrough"] += 1
+ continue
+ if entry.tokens_saved > 0 and entry.savings_percent > 0:
+ compressed_requests.append(
+ {
+ "savings_pct": round(entry.savings_percent, 1),
+ "tokens_saved": entry.tokens_saved,
+ "original": entry.input_tokens_original,
+ "optimized": entry.input_tokens_optimized,
+ }
+ )
+ elif entry.input_tokens_original > 0:
+ # Categorize why it wasn't compressed
+ transforms = entry.transforms_applied or []
+ if not transforms:
+ # Pipeline returned unchanged — likely all frozen
+ uncompressed_reasons["prefix_frozen"] += 1
+ elif all("excluded" in t or "protected" in t for t in transforms):
+ uncompressed_reasons["no_compressible_content"] += 1
+ elif entry.input_tokens_original < 500:
+ uncompressed_reasons["too_small"] += 1
+ else:
+ uncompressed_reasons["prefix_frozen"] += 1
+
+ # Compute compression stats for requests that DID compress
+ avg_compression = 0.0
+ best_compression = 0.0
+ best_detail = ""
+ if compressed_requests:
+ avg_compression = round(
+ sum(r["savings_pct"] for r in compressed_requests) / len(compressed_requests),
+ 1,
+ )
+ best = max(compressed_requests, key=lambda r: r["savings_pct"])
+ best_compression = best["savings_pct"]
+ best_detail = f"{best['original']:,} → {best['optimized']:,} tokens"
+
+ # Cost summary
+ cost_stats = proxy.cost_tracker.stats() if proxy.cost_tracker else {}
+ cost_without = cost_stats.get("cost_without_headroom_usd", 0.0)
+ cache_net = prefix_cache_stats.get("totals", {}).get("net_savings_usd", 0.0)
+ compression_savings = cost_stats.get("savings_usd", 0.0) if cost_stats else 0.0
+ total_saved_usd = round(compression_savings + cache_net, 2)
+ cost_with = round(cost_without - total_saved_usd, 2) if cost_without else 0.0
+ savings_pct_cost = round(total_saved_usd / cost_without * 100, 1) if cost_without > 0 else 0.0
+
+ # Primary models used
+ models = dict(metrics.requests_by_model)
+ primary_model = max(models, key=lambda k: models[k]) if models else "unknown"
+ api_requests = sum(v for k, v in models.items() if "count_tokens" not in k)
+
+ # Build the summary
+ summary: dict[str, Any] = {
+ "mode": proxy.config.mode,
+ "api_requests": api_requests,
+ "primary_model": primary_model,
+ "compression": {
+ "requests_compressed": len(compressed_requests),
+ "avg_compression_pct": avg_compression,
+ "best_compression_pct": best_compression,
+ "best_detail": best_detail,
+ "total_tokens_removed": metrics.tokens_saved_total,
+ },
+ "uncompressed_requests": {k: v for k, v in uncompressed_reasons.items() if v > 0},
+ "cost": {
+ "without_headroom_usd": round(cost_without, 2),
+ "with_headroom_usd": cost_with,
+ "total_saved_usd": total_saved_usd,
+ "savings_pct": savings_pct_cost,
+ "breakdown": {
+ "cache_savings_usd": round(cache_net, 2),
+ "compression_savings_usd": round(compression_savings, 2),
+ },
+ },
+ }
+
+ # Add tip if token_headroom mode would help
+ if proxy.config.mode == "cost_savings" and uncompressed_reasons["prefix_frozen"] > 10:
+ summary["tip"] = (
+ "Most requests are prefix-frozen. Set HEADROOM_MODE=token_headroom "
+ "to compress frozen messages and extend your session by ~25-35%."
+ )
+
+ return summary
+
+
# Maximum request body size (100MB - increased to support image-heavy requests)
MAX_REQUEST_BODY_SIZE = 100 * 1024 * 1024
@@ -6398,6 +6508,11 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
# Calculate total tokens before compression
total_tokens_before = m.tokens_input_total + m.tokens_saved_total
+ # Build human-readable summary
+ summary = _build_session_summary(
+ proxy, m, prefix_cache_stats, cli_tokens_avoided, total_tokens_before
+ )
+
# Compression cache stats (token_headroom mode)
compression_cache_stats: dict = {}
if proxy.config.mode == "token_headroom" and proxy._compression_caches:
@@ -6429,6 +6544,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
total_tokens_all_layers = compression_tokens + cli_tokens_avoided
return {
+ "summary": summary,
"savings": {
"total_tokens": total_tokens_all_layers,
"by_layer": {