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
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.pyindex 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 reachableif 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_statsreturn [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 resultexcept 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.pyindex 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 compressiontotal_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_avoidedreturn {+ "summary": summary,"savings": {"total_tokens": total_tokens_all_layers,"by_layer": {