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
docs: correct the published site against the code (#3388)
Tejas Chopra4bca514acd29
diff --git a/benchmarks/index_proof_table.py b/benchmarks/index_proof_table.pynew file mode 100644index 000000000..d415febca--- /dev/null+++ b/benchmarks/index_proof_table.py@@ -0,0 +1,147 @@+"""Regenerate the "Proof" savings table published on the docs landing page.++WHY THIS EXISTS+---------------+docs/content/docs/index.mdx published four precise before/after token counts+with no reproducible source. The nearest harness,+``real_world_agent_benchmark.py``, seeded nothing, so its corpus differed on+every run and the published figures could not be reproduced by anyone,+including us. A number on the front page of the docs that nobody can+regenerate is a liability, not evidence.++This script fixes the reproducibility half. It seeds the generators, builds the+same scenarios, and measures tokens through the real tokenizer and the real+``compress()`` path. No network, no API key, no model call: the table is a+statement about token counts, and token counts are computable locally.++ uv run python benchmarks/index_proof_table.py++Deterministic: same seed in, same numbers out, on any machine.+"""++from __future__ import annotations++import argparse+import json++from real_world_agent_benchmark import ( # noqa: E402+ DEFAULT_SEED,+ create_codebase_exploration_scenario,+ create_issue_triage_scenario,+ create_sre_debugging_scenario,+ generate_github_code_search,+ seed_everything,+)++from headroom import CompressConfig, compress+from headroom.providers.openai_compatible import OpenAICompatibleTokenCounter++MODEL = "gpt-5.6"+++def _tool_messages(tools: list[dict]) -> list[dict]:+ """The tool payloads as the proxy would actually see them on the wire."""+ return [+ {+ "role": "tool",+ "tool_call_id": f"call_{i}",+ "content": json.dumps(t["result"]),+ }+ for i, t in enumerate(tools)+ ]+++def measure(label: str, tools: list[dict], tok, config: CompressConfig) -> dict:+ msgs = [+ {"role": "system", "content": "You are a helpful assistant."},+ {"role": "user", "content": "Analyse the tool output and answer."},+ *_tool_messages(tools),+ ]+ before = sum(tok.count_text(m["content"]) for m in msgs if m["role"] == "tool")+ result = compress(msgs, model=MODEL, config=config)+ after = sum(+ tok.count_text(m["content"])+ for m in result.messages+ if m.get("role") == "tool" and isinstance(m.get("content"), str)+ )+ saved = before - after+ return {+ "scenario": label,+ "before": before,+ "after": after,+ "saved": saved,+ "savings_pct": (saved / before * 100) if before else 0.0,+ "transforms": sorted(set(result.transforms_applied)),+ }+++def main() -> int:+ ap = argparse.ArgumentParser()+ ap.add_argument("--seed", type=int, default=DEFAULT_SEED)+ args = ap.parse_args()++ tok = OpenAICompatibleTokenCounter(model=MODEL)++ # Two configurations, because the default protects the tail of the+ # conversation and these scenarios are only 3-5 messages long. Under the+ # default, protect_recent=4 shields almost every tool result and the+ # measurement says more about the guard than about the compressor.+ #+ # "default" - what a coding agent actually gets out of the box.+ # "full" - protect_recent=0, every tool result eligible. This is the+ # honest number for "how far can this payload compress",+ # and it is the one a benchmark table should quote, LABELLED.+ configs = {+ "default (protect_recent=4)": CompressConfig(),+ "full corpus (protect_recent=0)": CompressConfig(protect_recent=0),+ }++ # Built in a fixed order: every generator draws from the same global RNG,+ # so re-ordering these lines changes every number below.+ print(f"seed={args.seed} model={MODEL} tokenizer={type(tok._tokenizer).__name__}")++ out: dict[str, list[dict]] = {}+ for cname, cfg in configs.items():+ # Reseed per configuration so both see a byte-identical corpus.+ seed_everything(args.seed)+ rows = [+ measure(+ "Code search (100 results)",+ [generate_github_code_search("JWT authentication middleware", num_results=100)],+ tok,+ cfg,+ ),+ measure("SRE incident debugging", create_sre_debugging_scenario().tools, tok, cfg),+ measure("Codebase exploration", create_codebase_exploration_scenario().tools, tok, cfg),+ measure("GitHub issue triage", create_issue_triage_scenario().tools, tok, cfg),+ ]+ out[cname] = rows++ print(f"\n=== {cname} ===")+ print(f"{'Scenario':<30} {'Before':>10} {'After':>10} {'Savings':>9}")+ print("-" * 62)+ for r in rows:+ print(+ f"{r['scenario']:<30} {r['before']:>10,} {r['after']:>10,} "+ f"{r['savings_pct']:>8.0f}%"+ )+ tb = sum(r["before"] for r in rows)+ ta = sum(r["after"] for r in rows)+ print("-" * 62)+ print(f"{'TOTAL':<30} {tb:>10,} {ta:>10,} {(tb - ta) / tb * 100:>8.0f}%")++ print(+ "\n\nMarkdown for docs/content/docs/index.mdx "+ "(full-corpus config, which must be stated on the page):\n"+ )+ print("| Scenario | Before | After | Savings |")+ print("|---|---|---|---|")+ for r in out["full corpus (protect_recent=0)"]:+ print(+ f"| {r['scenario']} | {r['before']:,} | {r['after']:,} | **{r['savings_pct']:.0f}%** |"+ )+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/benchmarks/real_world_agent_benchmark.py b/benchmarks/real_world_agent_benchmark.pyindex cb64c65d4..652b88568 100644--- a/benchmarks/real_world_agent_benchmark.py+++ b/benchmarks/real_world_agent_benchmark.py@@ -12,6 +12,15 @@ We measure:- Answer quality (does compression hurt agent performance?)This is NOT synthetic data - these are actual output formats from production MCP servers.++DETERMINISM+-----------+The generators below draw heavily on ``random``. Until a seed was added, every+run produced different tool output, so any figure published from this harness+could not be reproduced by anyone, including us. ``DEFAULT_SEED`` and+``seed_everything()`` fix that: seed once before generating scenarios and the+corpus is byte-identical across runs and machines. Any number quoted from this+file must name the seed that produced it."""import hashlib@@ -39,6 +48,17 @@ except ImportError:HEADROOM_AVAILABLE = False+#: Seed for the scenario generators. Published figures must cite this value;+#: changing it changes every number this harness reports.+DEFAULT_SEED = 20260902+++def seed_everything(seed: int = DEFAULT_SEED) -> int:+ """Make scenario generation reproducible. Call BEFORE building scenarios."""+ random.seed(seed)+ return seed++# =============================================================================# REALISTIC MCP TOOL OUTPUT GENERATORS# Based on actual MCP server output formats@@ -613,7 +633,7 @@ def run_agent_scenario()-def run_full_benchmark(api_key: str = None) -> dict:+def run_full_benchmark(api_key: str = None, seed: int = DEFAULT_SEED) -> dict:"""Run complete benchmark comparing baseline vs Headroom."""if api_key is None:@@ -641,6 +661,8 @@ def run_full_benchmark(api_key: str = None) -> dict:default_mode="optimize",)+ seed_everything(seed)+scenarios = [create_sre_debugging_scenario(),create_codebase_exploration_scenario(),diff --git a/docs/app/layout.tsx b/docs/app/layout.tsxindex 6850d0d6d..38a9cb587 100644--- a/docs/app/layout.tsx+++ b/docs/app/layout.tsx@@ -10,10 +10,12 @@ const inter = Inter({// Canonical URL for the live docs. ``metadataBase`` resolves the og:url// and twitter:url for every page; pointing it at the actual live site// is what lets crawlers (search + LLM) follow the right canonical and-// pick up ``/llms.txt`` / ``/sitemap.xml`` / og images. Override at-// build time via ``NEXT_PUBLIC_SITE_URL`` (e.g. when promoting to a-// custom domain).-const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://headroom-docs.vercel.app';+// pick up ``/llms.txt`` / ``/sitemap.xml`` / og images. The site now+// serves from the custom domain below; the old *.vercel.app host is+// kept out of here deliberately, because when this fell back to it the+// live site advertised a sitemap and ``Host:`` on the wrong domain.+// Override at build time via ``NEXT_PUBLIC_SITE_URL`` for previews.+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://docs.headroomlabs.ai';export const metadata: Metadata = {title: {diff --git a/docs/app/robots.ts b/docs/app/robots.tsindex a316c6dc6..3c46585ae 100644--- a/docs/app/robots.ts+++ b/docs/app/robots.ts@@ -10,7 +10,7 @@import type { MetadataRoute } from 'next';-const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://headroom-docs.vercel.app';+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://docs.headroomlabs.ai';export default function robots(): MetadataRoute.Robots {return {diff --git a/docs/app/sitemap.ts b/docs/app/sitemap.tsindex b96d26d40..1d36e5e0e 100644--- a/docs/app/sitemap.ts+++ b/docs/app/sitemap.ts@@ -9,7 +9,7 @@import type { MetadataRoute } from 'next';import { source } from '@/lib/source';-const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://headroom-docs.vercel.app';+const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://docs.headroomlabs.ai';export default function sitemap(): MetadataRoute.Sitemap {const now = new Date();diff --git a/docs/content/docs/agno.mdx b/docs/content/docs/agno.mdxindex 292c30c69..541ad7b87 100644--- a/docs/content/docs/agno.mdx+++ b/docs/content/docs/agno.mdx@@ -18,14 +18,15 @@ from agno.agent import Agentfrom agno.models.openai import OpenAIChatfrom headroom.integrations.agno import HeadroomAgnoModel-model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))+model = HeadroomAgnoModel(wrapped_model=OpenAIChat(id="gpt-4o"))agent = Agent(model=model)response = agent.run("What's the capital of France?")print(f"Tokens saved: {model.total_tokens_saved}")print(model.get_savings_summary())-# {'total_requests': 1, 'total_tokens_saved': 245, 'average_savings_percent': 12.3}+# {'total_requests': 1, 'total_tokens_saved': 245, 'average_savings_percent': 12.3,+# 'total_tokens_before': 1990, 'total_tokens_after': 1745}```Works with any Agno provider:@@ -34,8 +35,8 @@ Works with any Agno provider:from agno.models.anthropic import Claudefrom agno.models.google import Gemini-claude_model = HeadroomAgnoModel(Claude(id="claude-sonnet-4-20250514"))-gemini_model = HeadroomAgnoModel(Gemini(id="gemini-2.0-flash"))+claude_model = HeadroomAgnoModel(wrapped_model=Claude(id="claude-sonnet-4-20250514"))+gemini_model = HeadroomAgnoModel(wrapped_model=Gemini(id="gemini-2.0-flash"))```## Observability hooks@@ -49,7 +50,7 @@ from headroom.integrations.agno import (HeadroomPostHook,)-model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))+model = HeadroomAgnoModel(wrapped_model=OpenAIChat(id="gpt-4o"))pre_hook = HeadroomPreHook()post_hook = HeadroomPostHook(token_alert_threshold=10000)@@ -85,7 +86,7 @@ Tool outputs (JSON, logs, search results) see the biggest compression gains at 7```pythonfrom agno.tools.duckduckgo import DuckDuckGoTools-model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))+model = HeadroomAgnoModel(wrapped_model=OpenAIChat(id="gpt-4o"))agent = Agent(model=model,@@ -103,7 +104,7 @@ print(f"Tokens saved: {model.total_tokens_saved}")import asyncioasync def process():- model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))+ model = HeadroomAgnoModel(wrapped_model=OpenAIChat(id="gpt-4o"))response = await model.aresponse(messages)@@ -129,7 +130,7 @@ print(f"Tokens saved: {metrics['tokens_saved']}")Reset metrics between sessions:```python-model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))+model = HeadroomAgnoModel(wrapped_model=OpenAIChat(id="gpt-4o"))# Session 1agent.run("First conversation...")diff --git a/docs/content/docs/api-reference.mdx b/docs/content/docs/api-reference.mdxindex 0fbcb631c..d6cf14651 100644--- a/docs/content/docs/api-reference.mdx+++ b/docs/content/docs/api-reference.mdx@@ -44,21 +44,24 @@ const client = new HeadroomClient({provider: { type: 'Provider', description: 'Token counting provider', default: 'Auto-detected' },default_mode: { type: '"audit" | "optimize"', description: 'Default compression mode', default: '"audit"' },store_url: { type: 'str | None', description: 'Storage URL for metrics database', default: 'None' },- smart_crusher_config: { type: 'SmartCrusherConfig', description: 'Compression settings', default: 'Default config' },- cache_aligner_config: { type: 'CacheAlignerConfig', description: 'Cache alignment settings', default: 'Default config' },+ config: { type: 'HeadroomConfig | None', description: 'Compression and cache alignment settings (set config.smart_crusher / config.cache_aligner)', default: 'Default config' },enable_cache_optimizer: { type: 'bool', description: 'Enable provider-specific cache optimization', default: 'True' },enable_semantic_cache: { type: 'bool', description: 'Enable query-level semantic caching', default: 'False' },model_context_limits: { type: 'dict[str, int]', description: 'Override context limits per model', default: '{}' },}} />```python-from headroom import HeadroomClient, OpenAIProvider+from headroom import HeadroomClient, OpenAIProvider, HeadroomConfig, SmartCrusherConfig, CacheAlignerConfigfrom openai import OpenAIclient = HeadroomClient(original_client=OpenAI(),provider=OpenAIProvider(),default_mode="optimize",+ config=HeadroomConfig(+ smart_crusher=SmartCrusherConfig(min_tokens_to_crush=100),+ cache_aligner=CacheAlignerConfig(enabled=True),+ ),)```@@ -95,7 +98,6 @@ Accepts all standard OpenAI/Anthropic parameters plus Headroom-specific overrideheadroom_query: { type: 'str', description: 'Query for relevance scoring', default: 'None' },headroom_output_buffer_tokens: { type: 'int', description: 'Reserve tokens for output', default: '4000' },headroom_keep_turns: { type: 'int', description: 'Keep last N turns uncompressed', default: '2' },- headroom_tool_profiles: { type: 'dict', description: 'Per-tool compression overrides', default: '{}' },}} />```python@@ -104,12 +106,18 @@ response = client.chat.completions.create(messages=[...],headroom_mode="optimize",headroom_keep_turns=5,- headroom_tool_profiles={- "important_tool": {"skip_compression": True},- },)```+<Callout type="warning" title="headroom_tool_profiles has no effect in 0.37.0">+ `headroom_tool_profiles` is accepted but not currently wired through+ `TransformPipeline.apply()`, so passing it changes nothing. To keep+ specific tool outputs from being compressed as aggressively, use+ `config.smart_crusher.max_items_after_crush` or+ `config.smart_crusher.enabled = False` instead — see+ [Compression Too Aggressive](/docs/troubleshooting#compression-too-aggressive).+</Callout>+</Tab></Tabs>@@ -124,8 +132,8 @@ plan = client.chat.completions.simulate()print(f"Tokens: {plan.tokens_before} -> {plan.tokens_after}")-print(f"Savings: {plan.savings_percent:.1f}%")-print(f"Transforms: {plan.transforms_applied}")+print(f"Savings: {plan.tokens_saved/plan.tokens_before*100:.1f}%")+print(f"Transforms: {plan.transforms}")```**Returns:** `SimulationResult`@@ -187,8 +195,9 @@ Aggregate statistics across all stored metrics.```pythonsummary = client.get_summary()-# Returns dict with total_requests, total_tokens_saved,-# avg_compression_ratio, total_cost_saved_usd+# Returns dict with total_requests, total_tokens_before, total_tokens_after,+# total_tokens_saved, avg_tokens_saved, avg_cache_alignment,+# audit_count, optimize_count```### validate_setup()@@ -197,9 +206,12 @@ Validate that the client is configured correctly.```pythonresult = client.validate_setup()+# Returns {"valid": bool, "provider": {...}, "storage": {...},+# "config": {...}, "cache_optimizer": {...}}, each with "ok"/"error"if not result["valid"]:- for issue in result["issues"]:- print(f" - {issue}")+ for key in ("provider", "storage", "config", "cache_optimizer"):+ if not result[key]["ok"]:+ print(f" - {key}: {result[key]['error']}")```---@@ -282,10 +294,14 @@ config = SmartCrusherConfig(<TypeTable type={{enabled: { type: 'bool', description: 'Enable/disable cache alignment (off by default)', default: 'False' },- extract_dates: { type: 'bool', description: 'Extract date patterns from system prompt', default: 'True' },+ use_dynamic_detector: { type: 'bool', description: 'Use the dynamic content detector', default: 'True' },+ detection_tiers: { type: "list[Literal['regex', 'ner', 'semantic']]", description: 'Detection tiers to apply', default: "['regex']" },+ extra_dynamic_labels: { type: 'list[str]', description: 'Additional labels for dynamic content detection', default: '[]' },+ entropy_threshold: { type: 'float', description: 'Entropy threshold for dynamic detection', default: '0.7' },+ date_patterns: { type: 'list[str]', description: 'Regex patterns for date extraction', default: '[...]' },normalize_whitespace: { type: 'bool', description: 'Normalize whitespace for stable prefix', default: 'True' },- stable_prefix_min_tokens: { type: 'int', description: 'Minimum prefix tokens for caching', default: '100' },- dynamic_patterns: { type: 'list[str]', description: 'Regex patterns to extract as dynamic content', default: '[]' },+ collapse_blank_lines: { type: 'bool', description: 'Collapse consecutive blank lines', default: 'True' },+ dynamic_tail_separator: { type: 'str', description: 'Separator between static and dynamic content', default: "'\\n\\n---\\n[Dynamic Context]\\n'" },}} />```python@@ -293,9 +309,9 @@ from headroom import CacheAlignerConfigconfig = CacheAlignerConfig(enabled=True,- extract_dates=True,+ use_dynamic_detector=True,normalize_whitespace=True,- stable_prefix_min_tokens=100,+ entropy_threshold=0.7,)```@@ -304,7 +320,7 @@ config = CacheAlignerConfig(### Context management-Context management is now handled automatically inside the pipeline (live-zone-only compression). Headroom never drops messages from the conversation history; it compresses only the newest content blocks (latest user message, latest tool result) and keeps the cache hot zone — system prompt, tools, and older turns — untouched. Use the `headroom_keep_turns` / `headroom_output_buffer_tokens` per-request overrides to tune behavior. The `RollingWindowConfig`, `IntelligentContextConfig`, and `ScoringWeights` classes are no longer part of Headroom.+Context management is now handled automatically inside the pipeline (live-zone-only compression). Headroom never drops messages from the conversation history; it compresses only the newest content blocks (latest user message, latest tool result) and keeps the cache hot zone — system prompt, tools, and older turns — untouched. Use the `headroom_keep_turns` / `headroom_output_buffer_tokens` per-request overrides to tune behavior. The `RollingWindowConfig`, `IntelligentContextConfig`, and `ScoringWeights` classes have been retired from the Python package (`from headroom import RollingWindowConfig` fails) and from the compression pipeline itself; the TypeScript SDK's `HeadroomConfig` type still exports the equivalent field names as unused legacy type surface, wired to nothing.### HeadroomConfig@@ -360,9 +376,13 @@ config.cache_aligner.enabled = True<Tab value="Python"><TypeTable type={{- scorer_type: { type: '"bm25" | "embedding" | "hybrid"', description: 'Scoring method', default: '"bm25"' },- embedding_model: { type: 'str | None', description: 'Model name for embedding scorer', default: 'None' },+ tier: { type: '"bm25" | "embedding" | "hybrid"', description: 'Scoring method', default: '"hybrid"' },+ bm25_k1: { type: 'float', description: 'BM25 k1 parameter (term frequency saturation)', default: '1.5' },+ bm25_b: { type: 'float', description: 'BM25 b parameter (length normalization)', default: '0.75' },+ embedding_model: { type: 'str', description: 'Model name for embedding scorer', default: "'all-MiniLM-L6-v2'" },hybrid_alpha: { type: 'float', description: 'Weight for hybrid scoring (0=embedding, 1=bm25)', default: '0.5' },+ adaptive_alpha: { type: 'bool', description: 'Automatically adapt alpha based on query type', default: 'True' },+ relevance_threshold: { type: 'float', description: 'Minimum relevance score to keep', default: '0.25' },}} /></Tab>@@ -391,19 +411,23 @@ config.cache_aligner.enabled = Truetokens_before: { type: 'int', description: 'Token count before compression' },tokens_after: { type: 'int', description: 'Token count after compression' },tokens_saved: { type: 'int', description: 'Tokens removed by compression' },- savings_percent: { type: 'float', description: 'Percentage of tokens saved' },- transforms_applied: { type: 'list[str]', description: 'Names of transforms that were applied' },- waste_signals: { type: 'WasteSignals', description: 'Detected waste in the request' },+ transforms: { type: 'list[str]', description: 'Names of transforms that were applied' },+ waste_signals: { type: 'dict[str, int]', description: 'Detected waste in the request (see WasteSignals below)' },}} />### WasteSignals (Python)+`plan.waste_signals` is a plain `dict[str, int]`, not a class instance:+<TypeTable type={{- json_bloat_tokens: { type: 'int', description: 'Tokens from JSON formatting waste' },- html_noise_tokens: { type: 'int', description: 'Tokens from HTML tags and noise' },- whitespace_tokens: { type: 'int', description: 'Tokens from excessive whitespace' },- dynamic_date_tokens: { type: 'int', description: 'Tokens from dynamic date strings' },- repetition_tokens: { type: 'int', description: 'Tokens from repeated content' },+ json_bloat: { type: 'int', description: 'Tokens from JSON blocks over 500 tokens' },+ html_noise: { type: 'int', description: 'Tokens from HTML tags and comments' },+ base64: { type: 'int', description: 'Tokens from base64-encoded blobs' },+ whitespace: { type: 'int', description: 'Tokens from repeated whitespace' },+ dynamic_date: { type: 'int', description: 'Tokens from dynamic dates in the system prompt' },+ repetition: { type: 'int', description: 'Tokens from repeated content' },+ reread: { type: 'int', description: 'Tokens from tool results re-served after already appearing earlier' },+ reread_compressed: { type: 'int', description: 'Subset of reread whose first serve was already compressed away' },}} />### RequestMetrics (Python)@@ -415,11 +439,11 @@ config.cache_aligner.enabled = Truetokens_input_before: { type: 'int', description: 'Input tokens before compression' },tokens_input_after: { type: 'int', description: 'Input tokens after compression' },tokens_output: { type: 'int', description: 'Output tokens from the model' },- cost_before: { type: 'float', description: 'Cost before compression (USD)' },- cost_after: { type: 'float', description: 'Cost after compression (USD)' },transforms_applied: { type: 'list[str]', description: 'Transforms that were applied' },}} />+Cost estimates are computed on demand inside `HeadroomClient` (`estimate_cost()` on the provider) rather than stored on `RequestMetrics`.+---## Providers@@ -429,9 +453,7 @@ config.cache_aligner.enabled = True```pythonfrom headroom import OpenAIProvider-provider = OpenAIProvider(- enable_prefix_caching=True,-)+provider = OpenAIProvider()counter = provider.get_token_counter("gpt-4o")tokens = counter.count_text("Hello, world!")@@ -447,7 +469,6 @@ from anthropic import Anthropicprovider = AnthropicProvider(client=Anthropic(),- enable_cache_control=True,)counter = provider.get_token_counter("claude-3-5-sonnet-latest")@@ -459,9 +480,7 @@ tokens = counter.count_messages(messages) # Accurate count via API```pythonfrom headroom.providers import GoogleProvider-provider = GoogleProvider(- enable_context_caching=True,-)+provider = GoogleProvider()```---@@ -479,7 +498,7 @@ from headroom import create_scorerscorer = create_scorer()# Explicitly choose type-scorer = create_scorer(scorer_type="hybrid", alpha=0.7)+scorer = create_scorer(tier="hybrid", alpha=0.7)```### BM25Scorer@@ -490,7 +509,7 @@ Fast keyword-based scoring (zero dependencies):from headroom import BM25Scorerscorer = BM25Scorer()-scores = scorer.score_items(items=["item 1", "item 2"], query="search query")+scores = scorer.score_batch(["item 1", "item 2"], "search query")```### EmbeddingScorer@@ -502,7 +521,7 @@ from headroom import EmbeddingScorer, embedding_availableif embedding_available():scorer = EmbeddingScorer(model_name="BAAI/bge-small-en-v1.5")- scores = scorer.score_items(items, query)+ scores = scorer.score_batch(items, query)```### HybridScorer@@ -513,7 +532,7 @@ Combines BM25 and embeddings:from headroom import HybridScorerscorer = HybridScorer(alpha=0.5) # 50% BM25, 50% embedding-scores = scorer.score_items(items, query)+scores = scorer.score_batch(items, query)```---@@ -524,31 +543,37 @@ scores = scorer.score_items(items, query)```pythonfrom headroom import SmartCrusher+import jsoncrusher = SmartCrusher()-result = crusher.crush(data={"results": [...]}, query="user query")+result = crusher.crush(content=json.dumps({"results": [...]}), query="user query")```### CacheAligner```python-from headroom import CacheAligner+from headroom import CacheAligner, Tokenizer, OpenAIProvider++provider = OpenAIProvider()+tokenizer = Tokenizer(provider.get_token_counter("gpt-4o"), "gpt-4o")aligner = CacheAligner()-result = aligner.align(messages)+result = aligner.apply(messages, tokenizer)```### TransformPipeline```python-from headroom import TransformPipeline+from headroom import TransformPipeline, SmartCrusher, CacheAligner-pipeline = TransformPipeline([+pipeline = TransformPipeline(transforms=[SmartCrusher(),CacheAligner(),])-result = pipeline.transform(messages)+# model_limit is required for direct pipeline use — HeadroomClient+# supplies it automatically from the provider's context limits+result = pipeline.apply(messages, "gpt-4o", model_limit=128_000)```---@@ -598,13 +623,16 @@ All exceptions include a `details` dict with additional context.### Tokenizer```python-from headroom import Tokenizer, count_tokens_text, count_tokens_messages+from headroom import Tokenizer, count_tokens_text, count_tokens_messages, OpenAIProvider++provider = OpenAIProvider()+token_counter = provider.get_token_counter("gpt-4o")# Quick counting-tokens = count_tokens_text("Hello, world!", model="gpt-4o")+tokens = count_tokens_text("Hello, world!", token_counter)# With tokenizer instance-tokenizer = Tokenizer(model="gpt-4o")+tokenizer = Tokenizer(token_counter, "gpt-4o")tokens = tokenizer.count_text("Hello")tokens = tokenizer.count_messages(messages)```diff --git a/docs/content/docs/architecture.mdx b/docs/content/docs/architecture.mdxindex d8f754372..58439a26c 100644--- a/docs/content/docs/architecture.mdx+++ b/docs/content/docs/architecture.mdx@@ -38,7 +38,7 @@ Headroom can be used three ways, all feeding the same compression pipeline:| Entry point | How it works | Code changes ||-------------|-------------|--------------|| **Proxy mode** | Run `headroom proxy` and point your client's base URL at it | Zero — just change the base URL |-| **SDK mode** | Call `compress()` (Python or TypeScript) on your messages before you send them | Minimal — one function call |+| **SDK mode** | Call `compress()` (Python or TypeScript) on your messages before you send them, or wrap an existing client with `HeadroomClient` for automatic per-call optimization and stats | Minimal — one function call, or a client wrapper || **Integrations** | LangChain, Vercel AI SDK, Agno, Strands, LiteLLM, MCP adapters | Framework-specific setup |In proxy mode the server is a FastAPI app with per-provider handlers (Anthropic, OpenAI, Gemini, Bedrock) that each run the same compression pipeline before forwarding through the selected [backend](/docs/proxy#cloud-providers).@@ -51,7 +51,7 @@ The proxy assembles a small, ordered pipeline. Every transform is independent, s2. **CacheAligner** *(off by default)* — a detector that reports dynamic-prefix drift (dates, UUIDs, session tokens). It **never mutates, moves, or rewrites** content. It is disabled by default and hard-disabled inside the proxy; it exists to surface prefix-stability metrics, not to change your messages.3. **ContentRouter** — the workhorse that does essentially all of the compression. See below.-The pipeline **never drops or reorders messages**. Earlier versions shipped a "context manager" stage (rolling-window / intelligent-context scoring) that deleted old turns to make the request fit the context window. That stage was **removed** — the `RollingWindowConfig`, `IntelligentContextConfig`, and `ScoringWeights` classes no longer exist. Headroom now does *live-zone-only* compression: it compresses content in place and leaves the message list intact. See [Context Management](/docs/context-management).+The pipeline **never drops or reorders messages**. Earlier versions shipped a "context manager" stage (rolling-window / intelligent-context scoring) that deleted old turns to make the request fit the context window. That stage was **removed** — the pipeline no longer runs any dropping/scoring logic, and the `RollingWindowConfig`, `IntelligentContextConfig`, and `ScoringWeights` classes are gone from the Python package (the TypeScript SDK's types still export the equivalent field names, but wired to nothing). Headroom now does *live-zone-only* compression: it compresses content in place and leaves the message list intact. See [Context Management](/docs/context-management).### ContentRouter@@ -64,7 +64,7 @@ ContentRouter detects the type of each content block and dispatches it to exactl| Search / grep results | SearchCompressor | 80–95% || Build / test logs | LogCompressor | 85–95% || Diffs | DiffCompressor | 40–80% |-| HTML | HTMLExtractor (trafilatura) | ~95% |+| HTML | HTMLExtractor (trafilatura) | 70–90% || Tabular (CSV/TSV/markdown tables) | TabularCompressor | 60–90% || Structured config (YAML/TOML/INI) | ConfigCompressor | 40–70% || Plain text | TextCrusher | 30–60% |diff --git a/docs/content/docs/autogen.mdx b/docs/content/docs/autogen.mdxindex 1495040b1..5f1df5708 100644--- a/docs/content/docs/autogen.mdx+++ b/docs/content/docs/autogen.mdx@@ -3,7 +3,7 @@ title: AutoGendescription: Automatic tool output compression for AutoGen agents with per-tool metrics tracking.----Headroom integrates with [AutoGen](https://github.com/microsoft/autogen) (`autogen-agentchat` >=0.7) to compress tool outputs before they enter the agent's model context. Tool-heavy agents that return large JSON arrays, database results, or verbose logs see 60-90% token reduction.+Headroom integrates with [AutoGen](https://github.com/microsoft/autogen) (`autogen-agentchat` >=0.7) to compress tool outputs before they enter the agent's model context. Tool-heavy agents that return large JSON arrays, database results, or verbose logs see the largest token reductions.## Installationdiff --git a/docs/content/docs/benchmarks.mdx b/docs/content/docs/benchmarks.mdxindex db7b0cfd6..90408427b 100644--- a/docs/content/docs/benchmarks.mdx+++ b/docs/content/docs/benchmarks.mdx@@ -9,103 +9,101 @@ For local inference, the main benefit is often faster prompt processing rather t## Compression Performance-Tested on Apple M-series (CPU), Headroom v0.5.18. Each test runs `compress()` on realistic tool outputs.+Measured on Apple M-series (CPU), Headroom 0.37.0, via `python benchmarks/bench_latency.py` (10 warm iterations per scenario; latency is p50 compression overhead, not an LLM call).-| Content Type | Original | Compressed | Saved | Ratio | Latency |+| Content Type | Original | Compressed | Saved | Ratio | Latency (p50) ||---|---|---|---|---|---|-| JSON array (100 items) | 3,163 | 297 | 2,866 | **90.6%** | 1ms |-| JSON array (500 items) | 9,526 | 1,614 | 7,912 | **83.1%** | 2ms |-| Shell output (200 lines) | 3,238 | 469 | 2,769 | **85.5%** | 1ms |-| Build log (200 lines) | 2,412 | 148 | 2,264 | **93.9%** | 1ms |-| grep results (150 hits) | 2,624 | 2,624 | 0 | 0.0% | <1ms |-| Python source (~480 lines) | 2,958 | 2,958 | 0 | 0.0% | <1ms |-| **Total** | **23,921** | **8,110** | **15,811** | **66.1%** | **5ms** |+| JSON array — search results (100 items) | 10,200 | 5,300 | 4,900 | **48%** | 0.20ms |+| JSON array — search results (500 items) | 50,200 | 25,800 | 24,400 | **49%** | 0.77ms |+| Structured logs (100 entries) | 7,600 | 3,600 | 4,000 | **53%** | 0.17ms |+| Structured logs (500 entries) | 35,700 | 16,200 | 19,400 | **54%** | 0.51ms |+| Documentation text (20K tokens) | 20,100 | 1,600 | 18,400 | **92%** | 1.4ms |+| Python source (~200 lines) | 2,600 | 2,600 | 0 | 0.0% | 1.3ms |+| **Total** | **126,400** | **55,100** | **71,300** | **56%** | **4.4ms** |<Callout type="info" title="Zero compression is intentional">-grep results and Python source show 0% compression. These are already compact structured formats. SmartCrusher only compresses JSON arrays; code passes through to preserve correctness.+Python source shows 0% compression: SmartCrusher only compresses JSON arrays, and code passes through to preserve correctness (verified: `headroom/transforms/smart_crusher.py:242`).</Callout>## Accuracy Benchmarks### HTML Extraction-**Dataset**: Scrapinghub Article Extraction Benchmark (181 HTML pages with ground truth)+**Dataset**: Scrapinghub Article Extraction Benchmark (181 HTML pages with ground truth), via `allenai/scrapinghub-article-extraction-benchmark` on Hugging Face.| Metric | Value ||---|---|| **F1 Score** | 0.919 |-| **Precision** | 0.879 |-| **Recall** | 0.982 |-| **Compression** | 94.9% |+| **Precision** | 0.875 |+| **Recall** | 0.985 |+| **Compression** | 94.8% |-For LLM applications, recall is critical -- 98.2% means nearly all article content is preserved. The slight precision drop (some extra content) does not hurt LLM accuracy.+For LLM applications, recall is critical -- 98.5% means nearly all article content is preserved. The slight precision drop (some extra content) does not hurt LLM accuracy.### JSON Compression (SmartCrusher)-**Test**: 100 production log entries with critical error at position 67. Task: find the error, error code, resolution, and affected count.+**Test**: 100-entry JSON log array with one anomalous error entry (error code, resolution, and affected count) injected at position 67, compressed via the public `compress()` API with an OpenAI-format tool-result message.-| Metric | Baseline | Headroom |-|---|---|---|-| Input tokens | 10,144 | 1,260 |-| Correct answers | 4/4 | **4/4** |-| Compression | -- | **87.6%** |+| Metric | Value |+|---|---|+| Input tokens (before) | 4,937 |+| Input tokens (after) | 3,053 |+| Compression | **38.2%** |+| Error entry preserved in output | Yes (verified by substring check) |-SmartCrusher preserves first N items (schema), last N items (recency), all anomalies (errors, warnings), and statistical distribution.+SmartCrusher preserves first N items (schema), last N items (recency), all anomalies (errors, warnings), and statistical distribution. This test confirms the anomalous entry survives compression; it does not include an LLM-graded "correct answers" comparison, which would require a paid API call to reproduce.### QA Accuracy Preservation-| Metric | Original HTML | Extracted | Delta |-|---|---|---|---|-| F1 Score | 0.85 | 0.87 | +0.02 |-| Exact Match | 60% | 62% | +2% |--<Callout type="info" title="Extraction can improve accuracy">-Removing HTML noise sometimes helps LLMs focus on relevant content, leading to slightly higher scores on extraction benchmarks.+<Callout type="warn" title="Requires a paid LLM call to reproduce">+This comparison (`tests/test_evals/test_html_oss_benchmarks.py::TestQAAccuracyPreservation`) runs SQuAD questions against both the original HTML and the extracted text using an LLM judge, and only executes when `OPENAI_API_KEY` is set. No committed result artifact for it exists in this repo, so no number is published here. Set `OPENAI_API_KEY` and run `pytest tests/test_evals/test_html_oss_benchmarks.py -k qa_accuracy -v -s` to reproduce it yourself.</Callout>## Latency Overhead### SDK Compression Latency-Measured per-scenario on Apple M-series (CPU):+Measured per-scenario on Apple M-series (CPU) via `python benchmarks/bench_latency.py --scenario json --iterations 10`. This is the local compression pipeline's own overhead — no LLM call is involved.| Scenario | Tokens In | Tokens Out | Saved | p50 (ms) | p95 (ms) ||----------|-----------|------------|-------|----------|----------|-| JSON: Search Results (100 items) | 10.2K | 1.5K | 8.7K | 189 | 231 |-| JSON: Search Results (500 items) | 50.2K | 1.5K | 48.7K | 943 | 955 |-| JSON: Search Results (1K items) | 100.5K | 1.5K | 99.0K | 2,012 | 2,198 |-| JSON: API Responses (500 items) | 38.9K | 1.1K | 37.8K | 743 | 776 |-| JSON: Database Rows (1K rows) | 43.7K | 605 | 43.1K | 961 | 1,104 |-| JSON: String Array (100 strings) | 1.1K | 231 | 820 | 15 | 15 |-| JSON: String Array (500 strings) | 4.9K | 233 | 4.6K | 72 | 80 |-| JSON: Number Array (200 numbers) | 1.2K | 192 | 1.1K | 31 | 62 |-| JSON: Mixed Array (250 items) | 2.3K | 368 | 1.9K | 38 | 40 |+| JSON: Search Results (100 items) | 10.2K | 5.3K | 4.9K | 0.20 | 0.21 |+| JSON: Search Results (500 items) | 50.2K | 25.8K | 24.4K | 0.77 | 1.1 |+| JSON: Search Results (1K items) | 100.5K | 51.7K | 48.8K | 1.4 | 1.6 |+| JSON: API Responses (500 items) | 38.9K | 21.8K | 17.0K | 0.77 | 0.80 |+| JSON: Database Rows (1K rows) | 43.7K | 16.2K | 27.5K | 0.78 | 0.81 |+| JSON: String Array (100 strings) | 1.1K | 226 | 825 | 0.15 | 0.16 |+| JSON: String Array (500 strings) | 4.9K | 228 | 4.6K | 0.11 | 0.12 |+| JSON: Number Array (200 numbers) | 1.2K | 146 | 1.1K | 0.17 | 0.18 |+| JSON: Mixed Array (250 items) | 2.3K | 1.1K | 1.2K | 0.24 | 0.25 |### Cost-Benefit Analysis-Net latency benefit = LLM time saved from fewer tokens minus compression overhead (at Claude Sonnet pricing, $3.0/MTok):+Net latency benefit = LLM time saved from fewer tokens minus compression overhead (at Claude Sonnet 4.5's 0.03ms/token prefill rate, $3.0/MTok input pricing):| Scenario | Compress (ms) | LLM Saved (ms) | Net Benefit | Savings per 1K Requests ||----------|---------------|-----------------|-------------|------------------------|-| JSON: Search Results (100 items) | 189 | 261 | **+72ms** | $26 |-| JSON: Search Results (500 items) | 943 | 1,461 | **+518ms** | $146 |-| JSON: Search Results (1K items) | 2,012 | 2,969 | **+957ms** | $297 |-| JSON: API Responses (500 items) | 743 | 1,134 | **+391ms** | $113 |-| JSON: Database Rows (1K rows) | 961 | 1,292 | **+331ms** | $129 |+| JSON: Search Results (100 items) | 0.20 | 146 | **+145.8ms** | $14.60 |+| JSON: Search Results (500 items) | 0.77 | 731 | **+730.2ms** | $73.09 |+| JSON: Search Results (1K items) | 1.4 | 1,464 | **+1,462.6ms** | $146.40 |+| JSON: API Responses (500 items) | 0.77 | 511 | **+510.2ms** | $51.10 |+| JSON: Database Rows (1K rows) | 0.78 | 824 | **+822.9ms** | $82.36 |-Compression pays for itself in latency for 11 of 12 tested scenarios against Claude Sonnet. Slower and more expensive models (Opus) benefit even more.+Compression paid for itself in latency for all 25 compressing scenarios measured (JSON, structured logs, agentic multi-turn, and long-document text) against Claude Sonnet 4.5. Slower and more expensive models (Opus) benefit even more, since the same compression overhead offsets a larger per-token prefill cost.### Pipeline Step Timing-| Step | Median | P90 | Description |-|------|--------|-----|-------------|-| `pipeline_total` | 16.9ms | 289ms | Full compression pipeline |-| `content_router` | 11.7ms | 259ms | Content detection + routing |-| `smart_crusher` | 50.1ms | 50ms | JSON array compression |-| `text_compressor` | 32.0ms | 576ms | Text compression (Kompress ONNX) |-| `initial_token_count` | 2.9ms | 16ms | Token counting (tiktoken) |+Measured via the same `bench_latency.py` run's per-transform breakdown (content detection + routing is the dominant step in every JSON scenario):-ContentRouter accounts for 91--98% of pipeline cost on average. CacheAligner is sub-millisecond.+| Scenario | `content_router` p50 | % of total pipeline time |+|---|---|---|+| JSON: String Array (500 strings) | 0.08ms | 68% |+| JSON: Search Results (100 items) | 0.16ms | 82% |+| JSON: Mixed Array (250 items) | 0.21ms | 85% |+| JSON: Database Rows (1K rows) | 0.72ms | 95% |+| JSON: Search Results (5K items) | 6.6ms | 99% |++ContentRouter accounted for 68--99% of pipeline cost across the 14 JSON scenarios measured (mean ~87%), the rest going to tokenization and the compression transform itself.## Reproducing Results@@ -114,4 +112,7 @@ git clone https://github.com/headroomlabs-ai/headroom.gitcd headroompip install -e ".[evals,html]"pytest tests/test_evals/ -v -s++# Latency and compression-ratio tables above+python benchmarks/bench_latency.py```diff --git a/docs/content/docs/ccr.mdx b/docs/content/docs/ccr.mdxindex 4d668b07c..a0db4efea 100644--- a/docs/content/docs/ccr.mdx+++ b/docs/content/docs/ccr.mdx@@ -6,7 +6,7 @@ description: Compress-Cache-Retrieve architecture that makes compression losslesHeadroom's CCR (Compress-Cache-Retrieve) architecture makes compression **reversible**. When content is compressed, the original data is cached locally. If the LLM needs the full data, it retrieves it instantly.<Callout type="info" title="Nothing is ever thrown away">- Unlike traditional lossy compression, CCR guarantees that every piece of original data remains accessible. You get 70-90% token savings with zero risk of permanent data loss.+ Unlike traditional lossy compression, CCR guarantees that every piece of original data remains accessible in the compression store, even when the compressed content the LLM sees is much smaller. Actual token savings depend heavily on how redundant the source data is -- see [How Compression Works](/docs/how-compression-works#content-type-detection) for measured ranges per content type.</Callout>## The problem with traditional compression@@ -38,7 +38,7 @@ LLM PROCESSINGWhen SmartCrusher compresses tool output:-1. The original content is stored in an LRU cache+1. The original content is stored, keyed by hash, with LRU-style eviction once the store hits capacity. In the proxy, this store defaults to a SQLite file (`ccr_store.db` in the workspace directory) rather than a pure in-process dict -- so it survives a proxy restart and is shared across worker processes. Set `HEADROOM_CCR_BACKEND=memory` to opt back into an in-process-only store. Other backend names are resolved via the `headroom.ccr_backend` setuptools entry-point group (e.g. a `redis` backend, if one is installed and registered) -- none besides `sqlite`/`memory` ship in this repo. See `headroom/cache/compression_store.py:1000-1017`.2. A hash key is generated for retrieval3. A marker is added to the compressed output:@@ -133,26 +133,33 @@ const ccrConfig: CCRConfig = {```</Tab><Tab value="Python">+The full CCR loop -- markers injected, `headroom_retrieve` tool added to the+request, and the model's retrieval call resolved automatically -- only runs+through `headroom proxy` (`headroom/proxy/handlers/*.py` wire tool injection+and the response handler; the direct SDK client does not). Point an OpenAI+client at the proxy to get it:+```python-from headroom import HeadroomClient, OpenAIProviderfrom openai import OpenAI-client = HeadroomClient(- original_client=OpenAI(),- provider=OpenAIProvider(),- default_mode="optimize",-)+# Start `headroom proxy` first (defaults to port 8787); use --no-optimize+# for a passthrough baseline or --no-ccr to disable CCR specifically.+client = OpenAI(base_url="http://127.0.0.1:8787/v1", api_key="local")-# CCR happens automatically during chat completions.-# The LLM calls headroom_retrieve when it needs more data.response = client.chat.completions.create(model="gpt-4o",messages=messages,)--# CCR is enabled by default in the current proxy path. Use --no-optimize for-# full passthrough behavior.```++`HeadroomClient` (the direct SDK integration, no proxy) still routes JSON+tool outputs through SmartCrusher and embeds `<<ccr:HASH>>` markers when a+compression ratio warrants one, and the original is stored and retrievable+via `headroom.cache.compression_store`. It does **not**, however, inject the+`headroom_retrieve` tool or intercept the model's retrieval call for you --+that wiring lives only in the proxy's request handlers. Resolve markers+yourself with `headroom.ccr.marker_resolution.resolve_markers_in_text` if+you're integrating CCR outside the proxy.</Tab></Tabs>@@ -184,7 +191,7 @@ Check the effective setting at `/v1/retrieve/stats` under| Approach | Risk | Savings ||---|---|---|| No compression | None | 0% |-| Traditional compression | Data loss | 70-90% |-| CCR compression | None (reversible) | 70-90% |+| Traditional compression | Data loss | Depends on content and target ratio |+| CCR compression | None (reversible) | Same range as traditional compression -- CCR changes the risk, not the ratio |-CCR gives you the savings of aggressive compression with zero risk. The LLM can always retrieve the original data if needed.+CCR gives you the savings of aggressive compression with zero risk: SmartCrusher, LogCompressor, SearchCompressor, and Kompress can all compress as aggressively as their configuration allows, because the original is always one retrieval away. See [How Compression Works](/docs/how-compression-works#content-type-detection) for measured savings ranges per compressor.diff --git a/docs/content/docs/ci-cd-flows.mdx b/docs/content/docs/ci-cd-flows.mdxindex 0ca77a0e3..5ca4bfcf3 100644--- a/docs/content/docs/ci-cd-flows.mdx+++ b/docs/content/docs/ci-cd-flows.mdx@@ -12,7 +12,7 @@ The short version:- Pull requests are gated by PR governance, path-filtered CI, targeted e2e workflows, and human review.- Release publishing is not triggered by every merge to `main`. `release-please` maintains a release PR; merging that release PR creates the tag and GitHub Release that trigger publishing.- Docker images are built as multi-architecture digests first, then merged into tagged manifests.-- Docs deploy only after docs changes land on `main`.+- Docs are deployed by Vercel's own Git integration, not by a GitHub Actions job -- `.github/workflows/docs.yml` ("Validate Docs") only builds the Next.js/Fumadocs app on pull requests touching `docs/**` to catch a broken build before merge; it deploys nothing.## PR Flow@@ -115,13 +115,14 @@ flowchart TDL --> M[build: sync versions, verify versions, changelog, npm packs]M --> N[build-wheels matrix]N --> O[collect-dist]- O --> P[smoke-import wheels]- P --> Q{Smoke import green?}+ N --> P[smoke-import wheels]+ O --> Q{Smoke import green?}+ P --> QQ -- no --> R[Stop before publishing broken wheels]Q -- yes --> S[publish PyPI]- Q -- yes --> T[publish npm packages]- Q -- yes --> U[publish GitHub Package Registry packages]- Q -- yes --> V[publish Docker images through docker.yml]+ M --> T[publish npm packages]+ M --> U[publish GitHub Package Registry packages]+ P --> V[publish Docker images through docker.yml]S --> W{PyPI published or PYPI_SKIP=true?}W -- no --> X[Do not update release assets]W -- yes --> Y[Create or update GitHub Release assets and notes]@@ -169,17 +170,23 @@ flowchart TDJ -- no --> L[Branch, PR, dev, or manual tags as configured]```-## Docs Deploy Flow+## Docs Validate + Deploy Flow++`.github/workflows/docs.yml` ("Validate Docs") only validates -- it has no+deploy step. Deployment of the Next.js/Fumadocs site at+`docs.headroomlabs.ai` is owned entirely by Vercel's own Git integration,+outside GitHub Actions (`.github/workflows/docs.yml:1-9`).```mermaidflowchart TD- A[Docs change in PR] --> B[PR review and normal checks]- B --> C[Merge to main]- C --> D{docs/**, mkdocs.yml, or docs workflow changed?}- D -- no --> E[No docs deploy]- D -- yes --> F[Deploy Documentation workflow]- F --> G[Build docs site]- G --> H[Deploy generated site]+ A[Docs change in PR] --> B{docs/** or docs.yml changed?}+ B -- no --> C[Validate Docs workflow does not run]+ B -- yes --> D[Validate Docs workflow: npm ci and npm run build]+ D --> E{Build green?}+ E -- no --> F[Fix before merge]+ E -- yes --> G[PR review and normal checks]+ G --> H[Merge to main]+ H --> I[Vercel Git integration builds and deploys, independent of GitHub Actions]```## Manual Validation Flow@@ -220,7 +227,7 @@ act workflow_dispatch -W .github/workflows/release.yml -e .github/act/dry-run.js| E2E | CLI, install, wrap, Docker, package paths | Docker init/wrap, native init/wrap/install, platform smoke | Relevant lifecycle checks green || Release dry-run | PRs touching release-critical paths | Version detection, wheel matrix, smoke imports | Publish path can build before merge || Release publish | GitHub Release published by release-please | Version sync, changelog, wheels, smoke import, PyPI gate, npm, GPR, Docker | Public packages and GitHub Release assets are consistent |-| Docs deploy | Push to `main` with docs paths | Docs build | Site deploy completes |+| Docs validate | PR touching `docs/**`, manual | Next.js/Fumadocs build | Build succeeds; deploy itself is done by Vercel's Git integration, not this workflow |## Workflow Ownership@@ -238,5 +245,5 @@ act workflow_dispatch -W .github/workflows/release.yml -e .github/act/dry-run.js| `.github/workflows/release-please.yml` | Release PR aggregation from conventional commits || `.github/workflows/release.yml` | Release build, wheel smoke-import gates, registry publishing, GitHub Release assets || `.github/workflows/docker.yml` | GHCR multi-architecture image builds and manifests |-| `.github/workflows/docs.yml` | Documentation deploy after docs changes merge |+| `.github/workflows/docs.yml` | Validates the Next.js/Fumadocs build on docs PRs; deploys nothing -- Vercel's own Git integration owns the actual deploy |diff --git a/docs/content/docs/claude-code-azure-foundry.mdx b/docs/content/docs/claude-code-azure-foundry.mdxindex 165bcd272..d600206c1 100644--- a/docs/content/docs/claude-code-azure-foundry.mdx+++ b/docs/content/docs/claude-code-azure-foundry.mdx@@ -11,8 +11,9 @@ just makes each call cheaper.## What you get-- **Fewer input tokens** on every Claude Code request to Azure AI Foundry (often- 30–60% on agent workloads), so you pay for less.+- **Fewer input tokens** on every Claude Code request to Azure AI Foundry —+ large file reads, logs, and tool output are compressed before forwarding —+ so you pay for less.- **Same answers** — compression is reversible and content-aware.- **No new secrets** — Headroom never holds your Azure credentials. Claude Codekeeps authenticating to Azure AI Foundry with its own `api-key` or Entra Bearer@@ -35,7 +36,7 @@ No `ANTHROPIC_API_KEY` is needed — Foundry mode uses your Azure credentials.## Run it (one command)```bash-pip install headroom-ai+pip install "headroom-ai[proxy]"headroom wrap claude```diff --git a/docs/content/docs/claude-code-vertex.mdx b/docs/content/docs/claude-code-vertex.mdxindex b41773a9f..03f86a76c 100644--- a/docs/content/docs/claude-code-vertex.mdx+++ b/docs/content/docs/claude-code-vertex.mdx@@ -11,8 +11,9 @@ just makes each call cheaper.## What you get-- **Fewer input tokens** on every Claude Code request to Vertex (often 30–60% on- agent workloads), so you pay Vertex for less.+- **Fewer input tokens** on every Claude Code request to Vertex — large file+ reads, logs, and tool output are compressed before forwarding — so you pay+ Vertex for less.- **Same answers** — compression is reversible and content-aware.- **No new secrets** — Headroom never holds your Google credentials. Claude Codekeeps authenticating to Vertex with its own ADC token; Headroom passes it through.@@ -34,7 +35,7 @@ No `ANTHROPIC_API_KEY` is needed — Vertex mode uses your Google login.## Run it (one command)```bash-pip install headroom-ai+pip install "headroom-ai[proxy]"headroom wrap claude```diff --git a/docs/content/docs/code-compression.mdx b/docs/content/docs/code-compression.mdxindex 2318c186d..70730ed15 100644--- a/docs/content/docs/code-compression.mdx+++ b/docs/content/docs/code-compression.mdx@@ -28,7 +28,6 @@ Naive truncation breaks code. Cutting a function in half leaves invalid syntax t- Class definitions- Type annotations- Decorators-- Error handlers (`try`/`except`, `try`/`catch`)**Compressed:**- Function bodies (implementations)@@ -38,9 +37,11 @@ Naive truncation breaks code. Cutting a function in half leaves invalid syntax t## Example```python-from headroom.transforms import CodeAwareCompressor+from headroom.transforms import CodeAwareCompressor, CodeCompressorConfig-compressor = CodeAwareCompressor()+# min_tokens_for_compression defaults to 100; a snippet this small needs an+# explicit override or it passes through unmodified (see "Skip small content" below).+compressor = CodeAwareCompressor(CodeCompressorConfig(min_tokens_for_compression=10))code = '''import os@@ -65,11 +66,11 @@ print(result.compressed)# def process_items(items: List[str]) -> List[str]:# """Process a list of items."""# results = []-# for item in items:-# # ... (5 lines compressed)+# # [6 lines omitted]# pass+# # [32 tokens compressed. Retrieve more: hash=<cache_key>. Expires in 5m.]-print(f"Compression: {result.compression_ratio:.0%}") # ~55%+print(f"Compression: {result.compression_ratio:.0%}") # ~57%print(f"Syntax valid: {result.syntax_valid}") # True```@@ -82,7 +83,6 @@ config = CodeCompressorConfig(preserve_imports=True, # Always keep importspreserve_signatures=True, # Always keep function signaturespreserve_type_annotations=True, # Keep type hints- preserve_error_handlers=True, # Keep try/except blockspreserve_decorators=True, # Keep decoratorsdocstring_mode=DocstringMode.FIRST_LINE, # FULL, FIRST_LINE, REMOVEtarget_compression_rate=0.2, # Keep 20% of tokens@@ -103,7 +103,6 @@ result = compressor.compress(code)| `preserve_imports` | `True` | Keep all import statements || `preserve_signatures` | `True` | Keep function/method signatures || `preserve_type_annotations` | `True` | Keep type hints |-| `preserve_error_handlers` | `True` | Keep try/except blocks || `preserve_decorators` | `True` | Keep decorators || `docstring_mode` | `FIRST_LINE` | How to handle docstrings: `FULL`, `FIRST_LINE`, `REMOVE` || `target_compression_rate` | `0.2` | Fraction of tokens to keep (0.2 = keep 20%) |@@ -169,6 +168,6 @@ unload_tree_sitter()| Memory | ~50MB (tree-sitter parsers) || Syntax validity | Guaranteed |-<Callout type="info" title="Automatic routing">- When you use the Headroom proxy or call `compress()`, source code is automatically detected and routed to CodeAwareCompressor. Direct usage gives you control over compression settings per language.+<Callout type="info" title="Routing differs between the proxy and the library API">+ ContentRouter always *detects* source code automatically, but whether it routes that code to CodeAwareCompressor depends on the entry point. `headroom proxy` enables code-aware routing by default (`HEADROOM_CODE_AWARE_ENABLED` defaults to on; disable with `--no-code-aware` or `HEADROOM_CODE_AWARE_ENABLED=0`). The one-function `compress()` API and `HeadroomClient`, however, build `ContentRouterConfig` with its own default, `enable_code_aware=False` -- there, detected code falls back to Kompress unless you construct your own pipeline with `ContentRouterConfig(enable_code_aware=True)`. Direct usage of `CodeAwareCompressor`, as shown on this page, is unaffected either way. See [How Compression Works](/docs/how-compression-works#content-type-detection).</Callout>diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdxindex fbcc6b297..99bb5670c 100644--- a/docs/content/docs/configuration.mdx+++ b/docs/content/docs/configuration.mdx@@ -31,7 +31,7 @@ These modes apply to SDK usage via `HeadroomClient(default_mode=...)` or per-req| `optimize` | Applies safe, deterministic transforms | Production optimization || `simulate` | Returns plan without API call | Testing, cost estimation |-> **Proxy `--mode` is a separate axis**: `headroom proxy --mode token` (maximize compression) or `--mode cache` (freeze prior turns for prefix-cache stability). The proxy does not accept `audit`, `optimize`, or `simulate`.+> **Proxy `--mode` is a separate axis**: `--mode cache` (the default) freezes prior turns so the provider's prefix cache is never busted, which is where the savings come from on a real agent workload. `--mode token` maximizes visible per-request compression at the cost of cache stability; prefer `cache` unless you are specifically diagnosing compression numbers. The proxy does not accept `audit`, `optimize`, or `simulate`.## SDK Configuration@@ -203,14 +203,16 @@ config = SmartCrusherConfig(Control prefix stabilization for provider cache hit rates:```python-from headroom.transforms import CacheAlignerConfig+from headroom import CacheAlignerConfigconfig = CacheAlignerConfig(# Enable/disable cache alignmentenabled=True,- # Patterns to extract from system prompt- dynamic_patterns=[+ # Use custom regex patterns instead of the built-in dynamic-content+ # detector (use_dynamic_detector=False activates date_patterns)+ use_dynamic_detector=False,+ date_patterns=[r"Today is \w+ \d+, \d{4}",r"Current time: .*",],@@ -293,7 +295,7 @@ If the upstream base URL itself must vary per request, use the `x-headroom-base-headroom proxy \--port 8787 \ # Port to listen on--host 0.0.0.0 \ # Host to bind to- --mode token \ # token compression mode; use cache for prefix-cache stability+ --mode cache \ # default; freezes prior turns for prefix-cache stability--budget 10.00 \ # Daily budget limit in USD--log-file headroom.jsonl # Log file path```@@ -345,6 +347,7 @@ headroom proxy --learn --min-evidence 3| `HEADROOM_STRIP_INTERNAL_HEADERS` | Python proxy: whether to strip internal `x-headroom-*` request headers (e.g. `x-headroom-bypass`, `x-headroom-mode`, `x-headroom-user-id`, `x-headroom-stack`, `x-headroom-base-url`) before every upstream forwarder call (PR-A5, fixes P5-49). `enabled` (default) stops fingerprinting / leakage. `disabled` is an explicit operator opt-in for diagnostic shadow tracing — NOT a fallback. Inbound reads of these headers (bypass gating, memory user-id resolution) are unaffected because they read `request.headers` directly. | `enabled` || `HEADROOM_PROXY_STRIP_INTERNAL_HEADERS` | Rust proxy: same policy as `HEADROOM_STRIP_INTERNAL_HEADERS` but for the Rust transparent proxy. Stripping happens inside `build_forward_request_headers` so both HTTP and WebSocket upstream calls are gated by one flag. `enabled` default; `disabled` operator opt-in for diagnostic shadow tracing. Response-side `X-Headroom-*` injection (e.g. `x-headroom-tokens-saved`) is unrelated and stays. | `enabled` || `HEADROOM_EMBEDDER_RUNTIME` | Set to `pytorch_mps` to run the memory embedder via the torch sentence-transformers backend on the Apple GPU (MPS). Only engages when Apple MPS is actually available; otherwise it logs a warning and uses the existing default embedder selection path. `pytorch_mps` is the only accepted value. Requires the `[pytorch-mps]` extra. See [Memory](/docs/memory#embedding-runtime--gpu-offload-apple-silicon). | default embedder selection |+| `HEADROOM_KOMPRESS_BACKEND` | Selects the Kompress (ModernBERT) inference backend, separate from `HEADROOM_EMBEDDER_RUNTIME` above. `auto` tries ONNX CPU then falls back to PyTorch; `onnx`/`onnx_cpu` and `onnx_coreml` force ONNX Runtime (CPU or CoreML); `pytorch` and `pytorch_mps` force PyTorch (`pytorch_mps` targets Apple's GPU, with `mps`/`torch_mps` accepted as aliases). | `auto` || `ORT_DYLIB_PATH` | Path to the ONNX Runtime shared library loaded by the Rust core (magika detection, fastembed embeddings), which loads ORT dynamically on every platform. Auto-pinned at `import headroom` to the library inside the `onnxruntime` pip package (`onnxruntime.dll` / `libonnxruntime.so*` / `libonnxruntime*.dylib`); set it yourself to override. Without a pin, ML detection degrades to the non-ONNX tiers — and on Windows the bare DLL search can resolve to the Windows ML System32 build (1.17.x on Win11 24H2+), which deadlocks ONNX session init — see [Troubleshooting](/docs/troubleshooting#windows-ml-content-detection-hangs-or-silently-falls-back). | auto-pinned || `HEADROOM_MAGIKA_INIT_TIMEOUT_SECS` | Upper bound (integer seconds, > 0) on magika's one-time ONNX session init in the Rust detection chain. On timeout the init error is cached and detection uses the non-ML fallback tiers for the rest of the process; a warning is logged. Safety net for environments where the dylib pin above does not apply. | `5` || `HEADROOM_REQUEST_TIMEOUT` | Request timeout in seconds | `300` |@@ -518,22 +521,31 @@ Unknown models are automatically inferred from naming patterns:## Provider-Specific Settings+Provider classes configure token counting and context/pricing overrides, not+cache toggles -- provider-specific cache optimization (Anthropic+`cache_control` breakpoints, OpenAI prefix stabilization, Google+`CachedContent`) is controlled by `enable_cache_optimizer` on `HeadroomClient`+(see [SDK Configuration](#sdk-configuration) above), which auto-detects the+right strategy from the provider you pass in.+<Tabs groupId="lang" items={['OpenAI', 'Anthropic', 'Google']}><Tab value="OpenAI">```pythonfrom headroom import OpenAIProviderprovider = OpenAIProvider(- enable_prefix_caching=True,+ context_limits={"gpt-4o": 128000},)```</Tab><Tab value="Anthropic">```pythonfrom headroom import AnthropicProvider+from anthropic import Anthropicprovider = AnthropicProvider(- enable_cache_control=True,+ # Optional: enables accurate token counting via Anthropic's Token Count API+ client=Anthropic(),)```</Tab>@@ -541,9 +553,9 @@ provider = AnthropicProvider(```pythonfrom headroom.providers import GoogleProvider-provider = GoogleProvider(- enable_context_caching=True,-)+# Optional: pass a configured google.generativeai module for API-based+# token counting via countTokens; omit for estimation-based counting.+provider = GoogleProvider()```</Tab></Tabs>@@ -581,6 +593,7 @@ result = client.validate_setup()if not result["valid"]:print("Configuration issues:")- for issue in result["issues"]:- print(f" - {issue}")+ for check in ("provider", "storage", "config", "cache_optimizer"):+ if result[check]["error"]:+ print(f" - {check}: {result[check]['error']}")```diff --git a/docs/content/docs/context-management.mdx b/docs/content/docs/context-management.mdxindex 39ad4f84e..2e50dcfe2 100644--- a/docs/content/docs/context-management.mdx+++ b/docs/content/docs/context-management.mdx@@ -39,7 +39,7 @@ System messages are never dropped. They contain critical instructions, persona d### Turn protection-The last N user/assistant turns are always preserved, ensuring the model has immediate conversational context. By default, the last 2 turns are protected.+The last N messages are always preserved, ensuring the model has immediate conversational context. The one-function `compress()` API exposes this as `CompressConfig.protect_recent`, which defaults to `4` messages (roughly the last 2 user/assistant turns) -- see `headroom/compress.py:110-112`.## Configuration@@ -74,9 +74,17 @@ response = client.chat.completions.create(model="gpt-4o",messages=messages,headroom_output_buffer_tokens=8000, # More room for long responses- headroom_keep_turns=5, # Protect last 5 turns)```++`HeadroomClient.chat.completions.create()` also accepts a `headroom_keep_turns`+parameter, but as of this package version it is accepted and threaded through+the wrapper methods without being forwarded into the transform pipeline (see+`headroom/client.py` -- `TransformPipeline.apply()`'s accepted kwargs, listed+in its docstring, don't include a turns/keep-turns option). Passing it does+not raise an error, but it currently has no effect; use `compress()`'s+`protect_recent` (see [Turn protection](#turn-protection) above) if you need+this control today.</Tab></Tabs>diff --git a/docs/content/docs/crewai.mdx b/docs/content/docs/crewai.mdxindex ec4876b6e..fd36091f2 100644--- a/docs/content/docs/crewai.mdx+++ b/docs/content/docs/crewai.mdx@@ -3,7 +3,7 @@ title: CrewAIdescription: Automatic tool output compression for CrewAI agents with per-tool metrics tracking.----Headroom integrates with [CrewAI](https://github.com/crewAIInc/crewAI) to compress tool outputs before they enter the agent's LLM context. Tool-heavy agents that return large JSON arrays, database results, or verbose logs see 60-90% token reduction.+Headroom integrates with [CrewAI](https://github.com/crewAIInc/crewAI) to compress tool outputs before they enter the agent's LLM context. Tool-heavy agents that return large JSON arrays, database results, or verbose logs see the largest token reductions.## Installationdiff --git a/docs/content/docs/docker-install.mdx b/docs/content/docs/docker-install.mdxindex 06e90fe38..4fde7708a 100644--- a/docs/content/docs/docker-install.mdx+++ b/docs/content/docs/docker-install.mdx@@ -44,7 +44,7 @@ The wrapper keeps Headroom inside Docker and mounts host state back into the conPort `8787` stays the default, so `http://localhost:8787` works the same way as a native install.-Published releases also push versioned GHCR tags such as `ghcr.io/headroomlabs-ai/headroom:0.5.26`, and those images are built with the same synced package version used for the matching PyPI and npm release.+Published releases also push versioned GHCR tags such as `ghcr.io/headroomlabs-ai/headroom:0.37.0`, and those images are built with the same synced package version used for the matching PyPI and npm release.## How the wrapper behavesdiff --git a/docs/content/docs/errors.mdx b/docs/content/docs/errors.mdxindex d4fd65c60..707e029f6 100644--- a/docs/content/docs/errors.mdx+++ b/docs/content/docs/errors.mdx@@ -45,7 +45,10 @@ HeadroomError (base class)+-- ProviderError # Provider issues (unknown model, etc.)+-- StorageError # Database/storage failures+-- CompressionError # Compression failures (rare)+ +-- TokenizationError # Token counting failed+ +-- CacheError # Cache operations failed+-- ValidationError # Setup validation failures+ +-- TransformError # Transform execution failed``````python@@ -55,7 +58,10 @@ from headroom import (ProviderError,StorageError,CompressionError,+ TokenizationError,+ CacheError,ValidationError,+ TransformError,)```@@ -119,7 +125,11 @@ except HeadroomError as e:### ConfigurationError-Raised when configuration is invalid.+Raised when configuration is invalid. In the Python SDK (0.37.0),+`ConfigurationError` is importable and exported from `headroom`, but+`HeadroomClient` itself does not currently raise it: an invalid+`default_mode` string is validated by the `HeadroomMode` enum and raises a+plain **`ValueError`**, not `ConfigurationError`.<Tabs groupId="lang" items={['TypeScript', 'Python']}><Tab value="TypeScript">@@ -136,44 +146,62 @@ try:client = HeadroomClient(original_client=OpenAI(),provider=OpenAIProvider(),- default_mode="invalid_mode", # Will raise ConfigurationError+ default_mode="invalid_mode",)-except ConfigurationError as e:- print(f"Config error: {e}")- print(f"Field: {e.details.get('field')}")+except ValueError as e:+ print(f"Invalid mode: {e}")+ # 'invalid_mode' is not a valid HeadroomMode```</Tab></Tabs>### ProviderError-Raised for provider-specific issues (unknown model, API error, token counting failure).+Reserved for provider-specific issues, but not currently raised anywhere in+the SDK. In particular, an unknown model name does **not** raise+`ProviderError`: `Provider.get_context_limit()` is documented to "never+raise an exception -- uses sensible defaults for unknown models," and only+logs a one-time `WARNING` naming the fallback it used.```python-try:- response = client.chat.completions.create(- model="unknown-model-xyz",- messages=[...],- )-except ProviderError as e:- print(f"Provider error: {e}")- print(f"Provider: {e.details.get('provider')}")+import logging+logging.basicConfig(level=logging.WARNING)++# Does NOT raise ProviderError -- falls back to a default context limit+# and logs: WARNING:headroom.providers.openai:Unknown OpenAI model+# 'unknown-model-xyz': using default limit (...). To configure explicitly,+# set HEADROOM_MODEL_LIMITS env var or add to ~/.headroom/models.json+response = client.chat.completions.create(+ model="unknown-model-xyz",+ messages=[...],+)```### StorageError-Raised when database operations fail. Storage errors do not affect core functionality -- the application can continue without historical metrics.+Reserved for database/storage failures. `HeadroomClient.get_metrics()` and+`get_summary()` currently delegate straight to the storage backend+(`headroom/client.py`) without wrapping failures in `StorageError`, so a+broken database today surfaces as the underlying driver's own exception+(for example `sqlite3.OperationalError`) rather than `StorageError`. Catch+the base `HeadroomError` -- or `Exception` around storage calls specifically+-- until that wrapping lands.```pythontry:metrics = client.get_metrics()-except StorageError as e:+except Exception as e:metrics = [] # Continue without historical metrics```### CompressionError-Raised when compression fails (rare). In practice, compression errors are caught internally and the original content passes through unchanged. This exception is only raised in strict mode.+Reserved for compression failures. As of 0.37.0 this class is exported but+not raised anywhere in the codebase -- there is no "strict mode" that+triggers it. Compression failures are instead caught internally by broad+`except Exception` handlers throughout `headroom/transforms/`, which fail+open and return the original, uncompressed content. This is what backs the+safety guarantee below.### HeadroomConnectionError (TypeScript)@@ -202,6 +230,7 @@ The TypeScript SDK automatically maps proxy error responses to the correct error| 4xx/5xx | `provider_error` | `ProviderError` || 4xx/5xx | `storage_error` | `StorageError` || 4xx/5xx | `tokenization_error` | `TokenizationError` |+| 4xx/5xx | `cache_error` | `CacheError` || 4xx/5xx | `validation_error` | `ValidationError` || 4xx/5xx | `transform_error` | `TransformError` || 4xx/5xx | (other) | `HeadroomCompressError` |@@ -265,12 +294,15 @@ response = client.chat.completions.create(## Best Practices1. **Catch specific exceptions** rather than broad `Exception` to avoid hiding real bugs-2. **Let StorageError pass** -- storage errors do not affect core compression functionality+2. **Don't rely on storage failures raising** -- as of 0.37.0 they surface as the+ underlying driver's own exception, not `StorageError` (see above)3. **Validate on startup** with `client.validate_setup()` to catch configuration issues early-4. **Enable logging** at WARNING level to see when compression is skipped+4. **Enable logging** at WARNING level to see when compression falls back safely```pythonimport logginglogging.basicConfig(level=logging.WARNING)-# WARNING:headroom.transforms.smart_crusher:Skipping compression: invalid JSON+# WARNING:headroom.transforms.smart_crusher:SmartCrusher audit_safe: 1 protected+# row(s) could not be preserved through compression (...). Failing closed:+# returning original uncompressed.```diff --git a/docs/content/docs/failure-learning.mdx b/docs/content/docs/failure-learning.mdxindex 15a4f58e1..625a6d87c 100644--- a/docs/content/docs/failure-learning.mdx+++ b/docs/content/docs/failure-learning.mdx@@ -146,12 +146,12 @@ Options:## Real-World Results-Tested on 67,583 tool calls across 23 projects:--| Metric | Value |-|--------|-------|-| Failure rate | 7.5% (5,066 failures) |-| Corrections extracted | 164 per project (avg) |-| Path corrections | 22 (axion project) |-| Search scope corrections | 24 (axion project) |-| Command patterns learned | 5 (axion project) |+<Callout type="warning" title="Figures removed">+ A prior version of this page cited specific counts (tool calls analyzed,+ failure rate, corrections extracted) for a real run. We could not trace+ those numbers to a committed benchmark, test, or dataset in this repo, and+ they appear to have been copied from `wiki/learn.md` rather than measured+ independently -- so we removed them rather than publish an unverifiable+ figure. Run `headroom learn` (dry-run by default) on your own session+ history to see real counts for your project.+</Callout>diff --git a/docs/content/docs/how-compression-works.mdx b/docs/content/docs/how-compression-works.mdxindex 5ea69b257..9b2fcf820 100644--- a/docs/content/docs/how-compression-works.mdx+++ b/docs/content/docs/how-compression-works.mdx@@ -28,16 +28,16 @@ The router auto-detects content type by analyzing structure and patterns. No man| Content Type | Detection Signal | Compressor | Typical Savings ||---|---|---|---|-| JSON arrays | Valid JSON with array elements | SmartCrusher | 70-90% |-| Source code | Syntax patterns, indentation, keywords | CodeAwareCompressor | 40-70% (opt-in; disabled by default) |-| Search results | `file:line:content` format | SearchCompressor | 80-95% |-| Build/test logs | Timestamps, log levels, pytest/npm markers | LogCompressor | 85-95% |-| Diffs | Unified diff format | DiffCompressor | 60-80% |-| HTML | Tag structure | HTMLExtractor | 50-70% |-| Tabular (CSV/TSV/markdown tables) | Delimited rows / table syntax | TabularCompressor | 60-90% |-| Structured config (YAML/TOML/INI) | Config syntax | ConfigCompressor | 40-70% |-| Plain text | Text with no stronger signal | TextCrusher | 30-60% |-| Anything else | ML fallback | Kompress | varies |+| JSON arrays | Valid JSON with array elements | SmartCrusher | Varies with redundancy -- measured 26-54% on realistic (non-duplicate) tool-output arrays of 100-10,000 items; highly repetitive arrays compress far more. See `benchmarks/compression_benchmark.py`. |+| Source code | Syntax patterns, indentation, keywords | Kompress via the library `compress()`/`HeadroomClient` path (`enable_code_aware` defaults to `False` there); CodeAwareCompressor via `headroom proxy` (`HEADROOM_CODE_AWARE_ENABLED` defaults to on) | workload-dependent |+| Search results | `file:line:content` format | SearchCompressor | 80-95% (measured ~91% on a synthetic 40-file ripgrep-style corpus) |+| Build/test logs | Timestamps, log levels, pytest/npm markers | LogCompressor | 85-95% (measured ~93% on a synthetic 1,000-line log with clustered errors) |+| Diffs | Unified diff format | DiffCompressor | 60-80% (measured ~70% on a multi-file diff with default `max_context_lines`/`max_hunks_per_file` limits) |+| HTML | Tag structure | HTMLExtractor | 70-90% (module docstring; measured ~81% on a synthetic nav/ads/script-heavy page) |+| Tabular (CSV/TSV/markdown tables) | Delimited rows / table syntax | TabularCompressor | Varies with redundancy -- TabularCompressor bridges to SmartCrusher, so it inherits the same range (measured 26-28% on non-duplicate rows) |+| Structured config (YAML/TOML/INI) | Config syntax | ConfigCompressor | 40-70% (measured ~50% on a commented/blank-line-heavy YAML file) |+| Plain text | Text with no stronger signal | Kompress | workload-dependent |+| Anything else | Fallback chain, then passthrough if no safe saving is found | Kompress / passthrough | varies |## Quick Start@@ -61,9 +61,13 @@ console.log(`Compression ratio: ${result.compressionRatio}`);```pythonfrom headroom import compress-result = compress(content)-print(result.compressed)-print(f"Saved {result.savings_percentage:.0f}% tokens")+messages = [+ {"role": "user", "content": "Summarize the tool output."},+ {"role": "tool", "tool_call_id": "call_1", "content": large_output},+]+result = compress(messages, model="gpt-4o")+print(result.messages)+print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")```</Tab></Tabs>@@ -87,22 +91,18 @@ console.log(`Transforms: ${result.transformsApplied.join(", ")}`);</Tab><Tab value="Python">```python-# Advanced / Internal API -- prefer `from headroom import compress` for typical use-from headroom.compression import UniversalCompressor, UniversalCompressorConfig--config = UniversalCompressorConfig(- compression_ratio_target=0.5, # Keep 50% of content- use_entropy_preservation=True, # Preserve UUIDs, hashes- use_magika=True, # ML-based content detection- ccr_enabled=True, # Store originals for retrieval-)+from headroom import CompressConfig, compress-compressor = UniversalCompressor(config=config)-result = compressor.compress(content)+config = CompressConfig(+ compress_user_messages=True,+ protect_recent=0,+ target_ratio=0.5, # Kompress keep ratio; structural compressors use their own rules+ min_tokens_to_compress=250,+)-print(f"Type: {result.content_type}")-print(f"Handler: {result.handler_used}")-print(f"Saved: {result.savings_percentage:.0f}%")+result = compress(messages, model="gpt-4o", config=config)+print(f"Saved: {result.tokens_saved} tokens")+print(result.transforms_applied)```</Tab></Tabs>@@ -120,44 +120,50 @@ Headroom doesn't blindly truncate. It identifies what matters in each content ty## Real Compression Ratios-| Content Type | Compression | Speed | What's Preserved |-|---|---|---|---|-| JSON (large arrays) | 70-90% | ~1ms | All keys, structure |-| Source code (Python) | 50-70% | ~10ms | Signatures, imports |-| Search results | 80-95% | ~2ms | Relevant matches |-| Build logs | 85-95% | ~3ms | Errors, stack traces |-| Plain text | 60-80% | ~5ms | High-entropy tokens |--## Batch Compression--For multiple contents, batch compression is more efficient:+Compression ratio and latency both depend heavily on the shape of the input+(how redundant the data is, how large the payload is, and -- for Kompress --+what `target_ratio` is configured). There's no single number that holds+across workloads, so treat the ranges in the table above as directional and+reproduce them on your own traffic with the harnesses in+[`benchmarks/`](https://github.com/headroomlabs-ai/headroom/tree/main/benchmarks)+(for example `compression_benchmark.py`, `bench_transforms.py`,+`text_crusher_quality_eval.py`). What stays constant across content types is+*what's preserved*:++| Content Type | What's Preserved |+|---|---|+| JSON (large arrays) | All keys, structure |+| Source code (Python) | Signatures, imports |+| Search results | Relevant matches |+| Build logs | Errors, stack traces |+| Plain text | High-entropy tokens |++## Compressing multiple documents++The public `compress()` API accepts an LLM message list. Put documents in+separate messages or call it once per independent request; this preserves the+same message shape you will send to the provider:```python-# Advanced / Internal API -- prefer `from headroom import compress` for typical use-from headroom.compression import UniversalCompressor--compressor = UniversalCompressor()+from headroom import compress-contents = [- '{"users": [...]}',- 'def hello(): pass',- 'Plain text content',+messages = [+ {"role": "user", "content": "Compare these documents."},+ {"role": "tool", "tool_call_id": "doc_1", "content": first_document},+ {"role": "tool", "tool_call_id": "doc_2", "content": second_document},]--results = compressor.compress_batch(contents)--for result in results:- print(f"{result.content_type}: {result.savings_percentage:.0f}% saved")+result = compress(messages, model="gpt-4o")```## What Happens Under the HoodWhen you call `compress()`, here is the full sequence:-1. **Content detection** -- Magika (ML-based) or pattern matching identifies the content type-2. **Structure extraction** -- A handler extracts a structure mask marking what to preserve-3. **Compression** -- Non-structural content is compressed (SmartCrusher, Kompress ML, or text utilities like TextCrusher)-4. **CCR storage** -- If enabled, the original is stored for retrieval when the LLM needs full context+1. **Safety gates** -- protected tools, recent turns, frozen cache prefixes, and minimum-size rules decide what may change.+2. **Content detection** -- Magika when available plus deterministic pattern matching identifies the content type.+3. **Structural compression** -- format-specific handlers compact JSON, logs, search results, tables, configuration, HTML, and other recognized structures.+4. **Fallback compression** -- Kompress handles eligible text when its runtime is available; a no-saving or failed transform passes the original through.+5. **CCR storage in proxy flows** -- when CCR is enabled, originals for marker-bearing compression are retained for later retrieval. `--lossless` and `--no-ccr` intentionally use different contracts; see [Reversible Compression](/docs/ccr).<Callout type="info" title="Zero-config by default">The pipeline works out of the box with no configuration. All detection, routing, and compression happens automatically. Configuration is available when you need fine-grained control.diff --git a/docs/content/docs/image-compression.mdx b/docs/content/docs/image-compression.mdxindex 52a9f9cba..60ece1ef0 100644--- a/docs/content/docs/image-compression.mdx+++ b/docs/content/docs/image-compression.mdx@@ -52,9 +52,14 @@ ANTHROPIC_BASE_URL=http://localhost:8787 claude### With HeadroomClient```python-from headroom import HeadroomClient+from headroom import HeadroomClient, OpenAIProvider+from openai import OpenAI-client = HeadroomClient(provider="openai")+client = HeadroomClient(+ original_client=OpenAI(),+ provider=OpenAIProvider(),+ default_mode="optimize",+)response = client.chat.completions.create(model="gpt-4o",@@ -115,6 +120,12 @@ The compressor adapts its strategy per provider:|---|---|---|| 1,032 tokens (4 tiles) | 258 tokens (1 tile) | 75% |+Unlike the OpenAI and Anthropic figures above (computed from the formulas in+`headroom/image/tile_optimizer.py` and verified to match this page's numbers+exactly), Headroom has no Gemini token-counting formula in the codebase --+these figures describe Google's publicly documented tile pricing, not+something this repo computes or tests.+## Configuration```python@@ -140,11 +151,10 @@ headroom proxy| Metric | Value ||---|---|-| Router inference | ~10ms (CPU), ~2ms (GPU) |-| Image resize | ~5-20ms |-| First request | +2-3s (model download, cached after) |-| Router accuracy | 93.7% |-| Model size | ~128MB |+| Image resize | ~5-20ms (measured ~9ms median for a 1024px -> 512px PIL/LANCZOS resize) |+| First request | Model download, cached after (duration depends on network) |+| Router accuracy | 93.7% (fine-tuned MiniLM classifier, 1,157 training examples -- see `headroom/image/trained_router.py`) |+| Model size | ~100MB (PyTorch MiniLM router) or ~32MB (ONNX INT8 router, preferred in production) || GPU memory (SigLIP) | ~400MB |<Callout type="info" title="Automatic with the proxy">diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdxindex 3f2471687..5533b48a9 100644--- a/docs/content/docs/index.mdx+++ b/docs/content/docs/index.mdx@@ -24,9 +24,14 @@ console.log(`Saved ${result.tokensSaved} tokens (${((1 - result.compressionRatio<Tab value="Python">```pythonfrom headroom import compress+from openai import OpenAI++messages = [{"role": "user", "content": "Analyze these results"}]result = compress(messages, model="gpt-4o")-response = client.messages.create(++client = OpenAI()+response = client.chat.completions.create(model="gpt-4o",messages=result.messages,)@@ -39,13 +44,17 @@ print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")| Content type | What happens | Typical savings ||---|---|---|-| JSON arrays (tool outputs) | Statistical analysis keeps errors, anomalies, boundaries | 70--90% |-| Source code | AST-aware compression preserves signatures, collapses bodies | 40--70% (opt-in; disabled by default) |-| Build/test logs | Keeps failures and errors, drops passing noise | 80--95% |-| Search results | Ranks by relevance, keeps top matches | 60--80% |-| Plain text | ModernBERT token classification removes redundancy | 30--50% |-| Git diffs | Preserves change hunks, drops unchanged context | 40--60% |-| Images | ML router selects optimal resize/quality tradeoff | 40--90% |+| JSON arrays (tool outputs) | Statistical analysis keeps errors, anomalies, boundaries | varies with array size and redundancy |+| Source code | AST-aware compression preserves signatures, collapses bodies | opt-in; disabled by default |+| Build/test logs | Keeps failures and errors, drops passing noise | varies with log verbosity |+| Search results | Ranks by relevance, keeps top matches | varies with result set size |+| Plain text | ModernBERT token classification removes redundancy | varies with redundancy |+| Git diffs | Preserves change hunks, drops unchanged context | varies with diff size |+| Images | ML router selects optimal resize/quality tradeoff | varies with image content |++Savings depend heavily on how repetitive the content is -- see+[Benchmarks](/docs/benchmarks) and the reproducible scenario table below for+measured numbers on real workloads.## Where Headroom fits@@ -64,21 +73,35 @@ Headroom works as a **transparent proxy** (zero code changes), a **Python functi## Real-world results-**100 production log entries. One critical error buried at position 67.**--| Metric | Baseline | Headroom |-|---|---|---|-| Input tokens | 10,144 | 1,260 |-| Correct answers | **4/4** | **4/4** |+Headroom is built for the scenario that matters most in agent workflows: a+single critical error or fact buried inside a large, mostly-routine tool+output. SmartCrusher preserves error items, anomalies (values outside normal+statistical range), and first/last boundaries by construction -- not by+keyword matching, but by statistical analysis of field variance -- so the+signal survives even when the surrounding noise is compressed away+aggressively.-87.6% fewer tokens. Same answer. The FATAL error was automatically preserved -- not by keyword matching, but by statistical analysis of field variance.+Measured on local, seeded test data built from real MCP server output+formats. These are not production telemetry, and they are reproducible:| Scenario | Before | After | Savings ||---|---|---|---|-| Code search (100 results) | 17,765 | 1,408 | **92%** |-| SRE incident debugging | 65,694 | 5,118 | **92%** |-| Codebase exploration | 78,502 | 41,254 | **47%** |-| GitHub issue triage | 54,174 | 14,761 | **73%** |+| Code search (100 results) | 17,199 | 13,597 | **21%** |+| SRE incident debugging | 55,957 | 24,340 | **57%** |+| Codebase exploration | 58,801 | 33,895 | **42%** |+| GitHub issue triage | 46,067 | 32,429 | **30%** |++```bash+uv run python benchmarks/index_proof_table.py --seed 20260902+```++Token counts are from the `gpt-5.6` tokenizer. The corpus is generated, so the+exact before/after counts move slightly with the seed; the savings hold across+seeds (Code search 21%, SRE 56--57%, triage 29--30%, exploration 41--50% over+five seeds). Savings depend on how repetitive your tool output is, so treat+these as a shape, not a promise.++See [Benchmarks](/docs/benchmarks) for the wider suite.## Key Featuresdiff --git a/docs/content/docs/installation.mdx b/docs/content/docs/installation.mdxindex 08c666a33..5a7cd55f3 100644--- a/docs/content/docs/installation.mdx+++ b/docs/content/docs/installation.mdx@@ -7,20 +7,22 @@ description: Install Headroom via pip, npm, or Docker. Includes all Python extra## Install options-**uv tool** - you want the `headroom` CLI (`proxy`, `wrap`, `mcp`, `learn`, `perf`) installed once on your machine in an isolated app environment.+**uv tool** - you want the `headroom` CLI (`deploy`, `proxy`, `wrap`, `doctor`, `mcp`, `learn`, and the other CLI commands) installed once on your machine in an isolated app environment.-**pip** - you're writing Python, or you need the CLI (`headroom proxy`, `wrap`, `mcp`, `learn`, `perf`), regardless of what language your app is in.+**pip** - you're writing Python, or you need the CLI, regardless of what language your app is in.**npm** - you're writing TypeScript/Node and want inline `compress()`, SDK wrapping (`withHeadroom`), or Vercel AI SDK middleware.## PythonHeadroom requires **Python 3.10+** and is published as `headroom-ai` on PyPI.-Current release wheels are built for Python **3.10 through 3.13** on Linux-(manylinux_2_28 x86_64 / aarch64) and macOS (Apple Silicon). Other targets —-**Windows** and **Intel macOS** — fall back to building the Rust extension-from the sdist and need a working native toolchain. If your installer is-using a newer Python, force a supported interpreter.+Release wheels are built for CPython **3.10 through 3.13** on Linux+(manylinux_2_28 x86_64 / aarch64), macOS (Apple Silicon and Intel), and+Windows x86_64. The Rust extension uses the CPython stable ABI, so those wheels+are forward-compatible with newer supported CPython versions; optional+dependencies may impose their own Python/platform limits. Platforms outside+that matrix fall back to the source distribution and need a Rust/native+toolchain.### CLI install with uv@@ -60,11 +62,6 @@ command = "/Users/you/.local/bin/headroom"args = ["mcp", "serve"]```-Native Intel macOS installs are currently tracked in-[headroomlabs-ai/headroom#525](https://github.com/headroomlabs-ai/headroom/issues/525).-Use [Docker-Native Install](/docs/docker-install) on Intel Macs until native-wheel support lands.-### Core package```bash@@ -85,22 +82,36 @@ pip install "headroom-ai[all]"| Extra | What it adds | Install command ||---|---|---|-| `proxy` | Proxy server, MCP tools, HTTP API | `pip install "headroom-ai[proxy]"` |-| `ml` | Kompress (ModernBERT text compression, requires PyTorch) | `pip install "headroom-ai[ml]"` |+| `proxy` | Proxy server, HTTP API, MCP runtime, local ONNX Kompress path | `pip install "headroom-ai[proxy]"` |+| `proxy-prod` | `proxy` plus gunicorn on Unix production hosts | `pip install "headroom-ai[proxy,proxy-prod]"` |+| `ml` | PyTorch/Hugging Face Kompress backend and model tooling | `pip install "headroom-ai[ml]"` || `code` | CodeCompressor (tree-sitter AST parsing) | `pip install "headroom-ai[code]"` || `memory` | Persistent memory (sqlite-vec, sentence-transformers) — pure-Python default backend, no compiler | `pip install "headroom-ai[memory]"` || `vector` | Optional HNSW vector backend (hnswlib) — needs a C++ toolchain; **not in `[all]`** | `pip install "headroom-ai[vector]"` |+| `memory-stack` | Optional Qdrant + Neo4j memory backend helpers; **not in `[all]`** | `pip install "headroom-ai[memory-stack]"` || `relevance` | fastembed-based relevance scoring (BAAI/bge-small-en-v1.5, ONNX) | `pip install "headroom-ai[relevance]"` || `image` | Image compression (Pillow, ONNX runtime, OCR) | `pip install "headroom-ai[image]"` || `reports` | HTML/Markdown report generation (Jinja2) | `pip install "headroom-ai[reports]"` || `otel` | OpenTelemetry exporter (OTLP) | `pip install "headroom-ai[otel]"` || `voice` | Voice/audio support | `pip install "headroom-ai[voice]"` |+| `voice-train` | Voice training dependencies; **not in `[all]`** | `pip install "headroom-ai[voice-train]"` || `mcp` | MCP server tools (`headroom_compress`, `headroom_retrieve`, `headroom_stats`) | `pip install "headroom-ai[mcp]"` |-| `langchain` | LangChain `HeadroomChatModel` wrapper | `pip install "headroom-ai[langchain]"` |-| `agno` | Agno `HeadroomAgnoModel` wrapper | `pip install "headroom-ai[agno]"` |+| `langchain` | LangChain `HeadroomChatModel` wrapper; **not in `[all]`** | `pip install "headroom-ai[langchain]"` |+| `agno` | Agno `HeadroomAgnoModel` wrapper; **not in `[all]`** | `pip install "headroom-ai[agno]"` |+| `strands` | AWS Strands Agents integration; **not in `[all]`** | `pip install "headroom-ai[strands]"` |+| `crewai` | CrewAI integration; **not in `[all]`** | `pip install "headroom-ai[crewai]"` |+| `autogen` | AutoGen AgentChat integration; **not in `[all]`** | `pip install "headroom-ai[autogen]"` |+| `anyllm` | any-llm multi-provider backend (Python 3.11+); **not in `[all]`** | `pip install "headroom-ai[anyllm]"` |+| `bedrock` | Native AWS Bedrock credentials/backend support; **not in `[all]`** | `pip install "headroom-ai[bedrock]"` || `evals` | Evaluation framework (GSM8K, SQuAD, BFCL benchmarks) | `pip install "headroom-ai[evals]"` || `pytorch-mps` | Apple-GPU (MPS) memory-embedder offload — **macOS only**, not in `[all]` (torch + sentence-transformers); opt in with `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps` | `pip install "headroom-ai[pytorch-mps]"` |-| `all` | Everything above | `pip install "headroom-ai[all]"` |+| `html` | HTML main-content extraction with trafilatura | `pip install "headroom-ai[html]"` |+| `spreadsheet` | `.xlsx` / `.xls` ingestion with openpyxl and xlrd | `pip install "headroom-ai[spreadsheet]"` |+| `sandbox` | Torch-free proxy bundle for constrained environments | `pip install "headroom-ai[sandbox]"` |+| `all` | Runtime bundle: `proxy,code,ml,memory,relevance,image,reports,otel,evals,voice,html,mcp,spreadsheet` | `pip install "headroom-ai[all]"` |++`[all]` is the full built-in runtime bundle, not every integration or optional+backend. The rows marked “not in `[all]`” must be requested explicitly.You can combine extras:@@ -108,12 +119,13 @@ You can combine extras:pip install "headroom-ai[proxy,langchain,ml]"```-### Windows+### Source builds and unsupported targets-There are no prebuilt Windows wheels yet, so `pip install headroom-ai`-(and `uv tool install`, `pipx install`, …) will fall back to building the-Rust extension from the sdist. The build needs the MSVC toolchain on-`PATH`. Without it you'll see:+Windows x86_64, Intel/Apple Silicon macOS, and Linux x86_64/aarch64 have+release wheels. If pip selects the source distribution on another target (or+because a matching wheel is unavailable), the build needs Rust plus the+platform C/C++ toolchain. On Windows without MSVC on `PATH`, for example,+you'll see:```texterror: linker `link.exe` not found@@ -138,9 +150,8 @@ To install the prerequisites:pip install "headroom-ai[all]"```-If you'd rather avoid the native toolchain entirely, run Headroom-through Docker — see the [Docker](#docker) section below. Native-Windows wheels are tracked in [#636](https://github.com/headroomlabs-ai/headroom/issues/636).+If you'd rather avoid a source build, use a supported interpreter/platform or+run Headroom through Docker — see the [Docker](#docker) section below.### pipx@@ -155,10 +166,10 @@ Use Python 3.13 explicitly. If you already use uv, prefer thepipx install --python python3.13 "headroom-ai[all]"```-For a pinned release:+For a pinned release, replace `<version>` with the version you require:```bash-pipx install --python python3.13 "headroom-ai[all]==0.21.4"+pipx install --python python3.13 "headroom-ai[all]==<version>"```Check which Python an existing `pipx` environment uses:@@ -230,15 +241,15 @@ If you want a host `headroom` CLI that keeps Headroom itself inside a container| Tag | Extras | Base image | Description ||---|---|---|---|-| `latest` | `proxy` | Debian slim | Default image, runs the proxy |-| `<version>` | `proxy` | Debian slim | Pinned version |-| `nonroot` | `proxy` | Debian slim | Runs as non-root user |-| `code` | `proxy,code` | Debian slim | Includes tree-sitter for code compression |-| `code-nonroot` | `proxy,code` | Debian slim | Code compression, non-root |-| `slim` | `proxy` | Distroless | Minimal image, no shell |-| `slim-nonroot` | `proxy` | Distroless | Minimal, non-root |-| `code-slim` | `proxy,code` | Distroless | Code compression, minimal |-| `code-slim-nonroot` | `proxy,code` | Distroless | Code compression, minimal, non-root |+| `latest` | `proxy,bedrock` | Debian slim | Default image, runs as non-root |+| `<version>` | `proxy,bedrock` | Debian slim | Pinned release, same default variant |+| `nonroot` | `proxy,bedrock` | Debian slim | Explicit non-root variant |+| `code` | `proxy,code,bedrock` | Debian slim | Includes tree-sitter for code compression |+| `code-nonroot` | `proxy,code,bedrock` | Debian slim | Code compression, non-root |+| `slim` | `proxy,bedrock` | Distroless | Minimal image, no shell |+| `slim-nonroot` | `proxy,bedrock` | Distroless | Minimal, non-root |+| `code-slim` | `proxy,code,bedrock` | Distroless | Code compression, minimal |+| `code-slim-nonroot` | `proxy,code,bedrock` | Distroless | Code compression, minimal, non-root |### Build from sourcediff --git a/docs/content/docs/langchain.mdx b/docs/content/docs/langchain.mdxindex a94fa9231..9104bcf54 100644--- a/docs/content/docs/langchain.mdx+++ b/docs/content/docs/langchain.mdx@@ -25,8 +25,9 @@ llm = HeadroomChatModel(ChatOpenAI(model="gpt-4o"))response = llm.invoke("Hello!")# Check savings-print(llm.get_metrics())-# {'tokens_saved': 12500, 'savings_percent': 45.2, 'requests': 50}+print(llm.get_savings_summary())+# {'total_requests': 50, 'total_tokens_saved': 12500, 'average_savings_percent': 45.2,+# 'total_tokens_before': 27700, 'total_tokens_after': 15200}```Works with any provider:@@ -60,7 +61,8 @@ After usage:```pythonprint(compressed_history.get_compression_stats())-# {'compression_count': 12, 'total_tokens_saved': 28000}+# {'compression_count': 12, 'total_tokens_saved': 28000,+# 'threshold_tokens': 4000, 'keep_recent_turns': 5}```## Retriever integration@@ -118,7 +120,15 @@ from headroom.integrations import get_tool_metricsmetrics = get_tool_metrics()print(metrics.get_summary())-# {'total_invocations': 25, 'total_compressions': 18, 'total_chars_saved': 450000}+# {+# 'total_invocations': 25,+# 'total_compressions': 18,+# 'total_chars_saved': 450000,+# 'average_compression_ratio': 0.35,+# 'by_tool': {+# 'search_database': {'invocations': 15, 'compressions': 12, 'chars_saved': 320000},+# }+# }```## LangGraph ReAct agent@@ -178,11 +188,10 @@ from headroom import HeadroomConfig, HeadroomModeconfig = HeadroomConfig(default_mode=HeadroomMode.OPTIMIZE,- smart_crusher_target_ratio=0.3,)llm = HeadroomChatModel(ChatOpenAI(model="gpt-4o"),- headroom_config=config,+ config=config,)```diff --git a/docs/content/docs/limitations.mdx b/docs/content/docs/limitations.mdxindex 96a3f75c5..2553a9d90 100644--- a/docs/content/docs/limitations.mdx+++ b/docs/content/docs/limitations.mdx@@ -7,34 +7,47 @@ Headroom is designed to compress LLM context without losing accuracy. This page## When Headroom Helps vs. Does Not-| Content Type | Compression | Latency Impact | Best For |+<Callout type="info" title="Methodology">+ The compression figures below are not from a published, repeatable+ benchmark suite -- we could not trace a prior version of this table to one.+ Instead of an unsourced number, each row is a directional single-sample+ measurement taken with `compress()` against a synthetic payload of that+ shape. For a seeded, committed harness that reproduces figures of this kind+ exactly, run `uv run python benchmarks/index_proof_table.py --seed 20260902`.+ Your own traffic will+ vary; measure it with `client.chat.completions.simulate()` (see+ [Troubleshooting](/docs/troubleshooting#use-simulation-to-inspect-transforms))+ rather than treating these as guarantees.+</Callout>++| Content Type | Compression (single-sample) | Latency Impact | Best For ||---|---|---|---|-| **JSON: Arrays of dicts** (search results, API responses, DB rows) | 86--100% | Net latency win on Sonnet/Opus | Primary use case |-| **JSON: Arrays of strings** (file paths, log lines, tags) | 60--90% | Net latency win | String dedup + sampling |-| **JSON: Arrays of numbers** (metrics, time series) | 70--85% | Net latency win | Statistical summary |-| **JSON: Mixed-type arrays** | 50--70% | Net latency win | Group-by-type compression |-| **Structured logs** (as JSON) | 82--95% | Net latency win | Log entries in tool outputs |-| **Agentic conversations** (25--50 turns) | 56--81% | Break-even to net win | Multi-tool agent sessions |-| **Plain text** (documentation, articles) | 43--46% | Adds latency (cost savings only) | Cost optimization |+| **JSON: Arrays of dicts** (search results, API responses, DB rows) | ~52% (200-item sample) | Net latency win on Sonnet/Opus | Primary use case |+| **JSON: Arrays of strings** (file paths, log lines, tags) | ~95% (300-item sample) | Net latency win | String dedup + sampling |+| **JSON: Arrays of numbers** (metrics, time series) | ~97% (500-item sample) | Net latency win | Statistical summary |+| **JSON: Mixed-type arrays** | ~45% (200-item sample) | Net latency win | Group-by-type compression |+| **Structured logs** (as JSON) | Varies widely with duplication -- see methodology note | Net latency win | Log entries in tool outputs |+| **Agentic conversations** (multi-turn) | Not independently measured for this page | Break-even to net win | Multi-tool agent sessions |+| **Plain text** (documentation, articles) | Requires the optional `kompress`/ML text path; not exercised in this measurement pass | Adds latency (cost savings only) | Cost optimization || **Code** | Passthrough | Minimal overhead | See below || **RAG document contexts** | Passthrough | Minimal overhead | Not compressed |### Where Headroom Adds the Most Value-- Long agent sessions with accumulated tool outputs (40--80% compression)-- JSON-heavy workflows -- API responses, database queries (83--94% compression)-- Build and test output (85--94% compression)-- Multi-tool agents (60--76% compression across tool results)+- Long agent sessions with accumulated tool outputs+- JSON-heavy workflows -- API responses, database queries+- Build and test output+- Multi-tool agents (repeated tool results compound the per-call savings above)### Where Headroom Adds Little Value-- Short conversational exchanges (median 4.8% compression)+- Short conversational exchanges -- overhead can exceed savings on small payloads- Code-only sessions (reading/writing files) -- code passes through- Single-turn requests with no accumulated context## What Headroom Does NOT Compress-- **Short messages** (< 300 tokens) -- overhead exceeds savings+- **Short messages** (below `min_tokens_to_compress`, 50 tokens by default -- `headroom/transforms/content_router.py:4806`) -- overhead exceeds savings- **Source code** -- passes through unchanged to preserve correctness- **grep/search results** -- compact structured format, already minimal- **Images** -- counted at fixed token cost (~1,600 tokens), not compressed@@ -42,11 +55,11 @@ Headroom is designed to compress LLM context without losing accuracy. This page## Code Compression-Headroom includes an AST-aware CodeCompressor (tree-sitter, 8 languages) but it is gated behind safety protections that prevent it from firing in most real-world scenarios. This is intentional.+Headroom includes an AST-aware CodeCompressor (tree-sitter, 11 languages: Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Perl, C#, PHP) but it is gated behind safety protections that prevent it from firing in most real-world scenarios. This is intentional.**Why code mostly passes through:**-1. **Word count gate**: Content under 50 words is silently skipped+1. **Size gates, not a word count**: a message under `min_tokens` (50 tokens by default; savings profiles set this anywhere from 10-250) is skipped, and a block under `min_chars_for_block_compression` (500 characters) is skipped -- both measured in tokens/characters, never words (`headroom/transforms/content_router.py:4806,1596`)2. **Recent code protection** (`protect_recent_code=4`): Code in the last 4 messages is never compressed3. **Analysis intent protection** (`protect_analysis_context=True`): If the most recent user message contains keywords like "analyze", "review", "explain", "fix", "debug" -- ALL code in the conversation is protected@@ -85,13 +98,16 @@ Headroom includes an AST-aware CodeCompressor (tree-sitter, 8 languages) but itAll compressors follow the same principle: **fail gracefully, return original content unchanged**.- Invalid JSON passes through (no error raised)-- AST parse failure falls back to original or LLMLingua+- AST parse failure falls back to the original content, unchanged- Compression that makes output larger returns the original-- Missing optional dependencies (tree-sitter, LLMLingua) cause a passthrough with warning log+- A missing optional dependency (tree-sitter) causes a passthrough with a warning log- Errors are logged at WARNING level and never propagated to callers-<Callout type="info" title="One exception">-LLMLingua out-of-memory during model loading raises a `RuntimeError`. All other failures are silently handled.+<Callout type="warning" title="LLMLingua was removed">+LLMLingua is not part of Headroom 0.37.0. The `[llmlingua]` extra was removed+in 0.9.x with no live code path using it (`pyproject.toml:115`); text+compression today goes through the Kompress (ModernBERT ONNX) path instead,+which fails open the same as every other compressor.</Callout>## Adaptive K: How Item Retention Works@@ -141,3 +157,27 @@ The Tool Output Intelligence Network (TOIN) learns compression patterns from usa- Confidence below `toin_confidence_threshold` (default 0.3) -- TOIN hints ignored- Patterns build up over time as tools are used repeatedly- Cross-session learning requires persistence (`TelemetryConfig.storage_path`)++## Telemetry and the Upload Beacon++Headroom ships two independent, separately-defaulted switches+(`headroom/telemetry/beacon.py:1-92`) -- worth knowing about before you treat+this page's "nothing leaves the machine" framing as universal:++- **`HEADROOM_TELEMETRY`** -- off by default, opt-in. Aggregates compression+ stats locally for the in-process collector and the `/stats` endpoint.+ Never leaves the machine.+- **`HEADROOM_BEACON`** -- **on by default, opt-out.** Uploads an anonymous+ summary of how compression behaved, so we can see when a release regresses a+ ratio or starts skipping a content type across real workloads instead of only+ our own test corpus. It carries counters and identifiers only: token totals,+ compression ratios, skip reasons, provider and model ids, failure counts, plus+ OS and architecture. Never prompts, completions, code, or file paths -- the+ collector allowlists fields server-side and drops the rest. Disable it with+ `HEADROOM_BEACON=off`, the cross-tool `DO_NOT_TRACK=1` convention, or by+ running offline. `is_beacon_enabled()` is fail-open: an unrecognized value+ uploads rather than staying silent. See [Proxy](/docs/proxy) for the full+ field list.++These are deliberately separate so that enabling local `/stats` does not+silently start an upload on the next release.diff --git a/docs/content/docs/litellm.mdx b/docs/content/docs/litellm.mdxindex b7c174604..d0975f1c7 100644--- a/docs/content/docs/litellm.mdx+++ b/docs/content/docs/litellm.mdx@@ -32,12 +32,12 @@ response = litellm.completion(model="bedrock/claude-sonnet", messages=[...])response = litellm.completion(model="azure/gpt-4o", messages=[...])```-The callback compresses messages in LiteLLM's `pre_call_hook` before they reach the provider.+The callback compresses messages in LiteLLM's `async_pre_call_hook` before they reach the provider.## How it works1. You call `litellm.completion()` with your messages-2. `HeadroomCallback.pre_call_hook` compresses the messages+2. `HeadroomCallback.async_pre_call_hook` compresses the messages3. LiteLLM sends the compressed messages to the provider4. The response comes back unchanged@@ -99,9 +99,11 @@ Response headers include `x-headroom-compressed: true` and `x-headroom-tokens-saThe options above run Headroom **in** the LiteLLM process. If instead LiteLLM runs as its own proxy and you want it to call Headroom over the network — the guardrail deployment — point it at [`POST /v1/compress`](/docs/proxy#post-v1compress). LiteLLM swaps `messages` for the compressed result and forwards to the provider.-Two things this deployment needs:+Two things this deployment needs — the proxy extras, and the proxy itself running with remote access opted in:```bash+pip install "headroom-ai[proxy]"+# Headroom is loopback-only by default and answers remote callers with 404.HEADROOM_COMPRESS_ALLOW_REMOTE=1 headroom proxy```diff --git a/docs/content/docs/mcp.mdx b/docs/content/docs/mcp.mdxindex 7fe121ff8..b2ee0eeec 100644--- a/docs/content/docs/mcp.mdx+++ b/docs/content/docs/mcp.mdx@@ -205,7 +205,7 @@ The proxy compresses all traffic at the HTTP level (before the LLM sees content)**"Proxy not running"** -- Start the proxy with `headroom proxy` in another terminal. Only needed for proxy-backed retrieval.-**"Entry not found or expired"** -- Local content expires after 1 hour, proxy content after 5 minutes.+**"Entry not found or expired"** -- Local content expires after 1 hour, proxy content after 30 minutes (configurable via `HEADROOM_CCR_TTL_SECONDS`).**Claude doesn't see headroom tools** -- Run `headroom mcp status`, restart Claude Code, and verify with `/mcp` inside Claude Code.diff --git a/docs/content/docs/memory.mdx b/docs/content/docs/memory.mdxindex cc56829c7..523153285 100644--- a/docs/content/docs/memory.mdx+++ b/docs/content/docs/memory.mdx@@ -86,7 +86,11 @@ response = client2.chat.completions.create(## Memory Categories-Each memory carries a free-form `category` string -- pass any label you like. These are the conventional categories Headroom uses for organization and retrieval:+There is no dedicated `category` field on `Memory` or parameter on `add()`+(`headroom/memory/models.py`, `headroom/memory/core.py`) -- store a+free-form category string in the `metadata` dict instead, e.g.+`metadata={"category": "fact"}`. These are the conventional category values+used in Headroom's own examples for organization and retrieval:| Category | Description | Examples ||----------|-------------|----------|@@ -122,9 +126,10 @@ all_memories = client.memory.get_all()client.memory.clear()# Get stats+# `stats()` currently returns only {"total": N} -- there is no+# per-category breakdown (`headroom/memory/wrapper.py:342-348`).stats = client.memory.stats()print(f"Total memories: {stats['total']}")-print(f"By category: {stats['categories']}")```## Temporal Versioning@@ -137,10 +142,12 @@ from headroom.memory import HierarchicalMemory, MemoryFiltermemory = await HierarchicalMemory.create()# Original fact+# `category` is a convention, not a keyword argument -- `add()` has no+# `category` param (`headroom/memory/core.py`); store it in `metadata`.orig = await memory.add(content="User works at Google",user_id="alice",- category="fact",+ metadata={"category": "fact"},)# User changes jobs -- supersede the old memorydiff --git a/docs/content/docs/metrics.mdx b/docs/content/docs/metrics.mdxindex c07953d6a..d7dacba53 100644--- a/docs/content/docs/metrics.mdx+++ b/docs/content/docs/metrics.mdx@@ -67,7 +67,7 @@ curl http://localhost:8787/metrics```# HELP headroom_requests_total Total requests processed-headroom_requests_total{mode="optimize"} 1234+headroom_requests_total 1234# HELP headroom_tokens_saved_total Total tokens savedheadroom_tokens_saved_total 5678900@@ -75,19 +75,19 @@ headroom_tokens_saved_total 5678900# HELP headroom_persistent_savings_tokens_saved_total Durable lifetime input tokens saved by proxy compressionheadroom_persistent_savings_tokens_saved_total 5678900-# HELP headroom_compression_ratio Compression ratio histogram-headroom_compression_ratio_bucket{le="0.5"} 890-headroom_compression_ratio_bucket{le="0.7"} 1100-headroom_compression_ratio_bucket{le="0.9"} 1200+# HELP headroom_latency_ms_sum Sum of request latency in milliseconds+headroom_latency_ms_sum 152300+# HELP headroom_latency_ms_count Count of latency samples+headroom_latency_ms_count 1234-# HELP headroom_latency_seconds Request latency histogram-headroom_latency_seconds_bucket{le="0.01"} 800-headroom_latency_seconds_bucket{le="0.1"} 1150--# HELP headroom_cache_hits_total Cache hit counter-headroom_cache_hits_total 456+# HELP headroom_provider_cache_hit_requests_total Requests that read from the provider's prompt cache+headroom_provider_cache_hit_requests_total{provider="anthropic"} 456```+<Callout type="warn" title="No percentile buckets on /metrics">+There are no Prometheus histogram buckets for compression ratio or latency — build percentiles or averages from `_sum` / `_count` pairs (`headroom_latency_ms_sum`, `headroom_latency_ms_count`, and so on), or use the `headroom perf` CLI for real p95/p99.+</Callout>+### OpenTelemetry (OTLP) ExportThe proxy can also push its counters to any OTLP/HTTP endpoint. Install the extra and set four variables:@@ -154,7 +154,7 @@ curl http://localhost:8787/health```json{"status": "healthy",- "version": "0.1.0",+ "version": "0.37.0","uptime_seconds": 3600}```@@ -176,7 +176,7 @@ const client = new HeadroomClient();// Get proxy statsconst stats = await client.proxyStats();console.log(`Tokens saved: ${stats.tokens.saved}`);-console.log(`Savings: ${stats.tokens.savings_percent}%`);+console.log(`Savings: ${stats.tokens.savingsPercent}%`);```### Compression Result Metrics@@ -203,7 +203,7 @@ Quick stats for the current session (no database query):stats = client.get_stats()print(f"Mode: {stats['config']['mode']}")print(f"Tokens saved: {stats['session']['tokens_saved_total']}")-print(f"Avg compression: {stats['session']['compression_ratio_avg']:.1%}")+print(f"Requests optimized: {stats['session']['requests_optimized']}")```Returns:@@ -212,23 +212,20 @@ Returns:{"session": {"requests_total": 10,- "tokens_input_before": 50000,- "tokens_input_after": 35000,+ "requests_optimized": 8,+ "requests_audit": 2,"tokens_saved_total": 15000,- "tokens_output_total": 8000,"cache_hits": 3,- "compression_ratio_avg": 0.70,},"config": {"mode": "optimize","provider": "openai",- "cache_optimizer_enabled": True,- "semantic_cache_enabled": False,+ "cache_optimizer": "openai-prefix-stabilizer",+ "semantic_cache": False,},"transforms": {"smart_crusher_enabled": True,"cache_aligner_enabled": True,- "rolling_window_enabled": True,},}```@@ -257,8 +254,7 @@ Aggregate statistics across all stored metrics:summary = client.get_summary()print(f"Total requests: {summary['total_requests']}")print(f"Total tokens saved: {summary['total_tokens_saved']}")-print(f"Average compression: {summary['avg_compression_ratio']:.1%}")-print(f"Total cost savings: ${summary['total_cost_saved_usd']:.2f}")+print(f"Avg tokens saved per request: {summary['avg_tokens_saved']:.0f}")```</Tab>@@ -291,8 +287,8 @@ DEBUG:headroom.transforms.smart_crusher:Kept items: [0,1,2,42,77,97,98,99] (erro# Log to fileheadroom proxy --log-file headroom.jsonl-# Increase verbosity-headroom proxy --log-level debug+# Increase verbosity (no --log-level flag; use the env var)+HEADROOM_LOG_LEVEL=debug headroom proxy```</Tab></Tabs>@@ -353,19 +349,19 @@ Env: `HEADROOM_BUDGET_ESTIMATED_BASIS`. `headroom doctor` reports the estimated|--------|-------------------|--------|| `headroom_tokens_saved_total` | Runtime tokens saved since this proxy process started | Higher is better || `headroom_persistent_savings_tokens_saved_total` | Durable lifetime tokens saved from `/stats.persistent_savings` | Higher is better |-| `compression_ratio_avg` | Efficiency | 0.7--0.9 typical |-| `cache_hit_rate` | Cache effectiveness | >20% is good |-| `latency_p99` | Performance impact | <10ms |-| `failed_requests` | Reliability | 0 |+| `headroom_overhead_ms_sum` / `headroom_overhead_ms_count` | Mean latency Headroom itself adds (there are no percentile buckets — see the callout above) | Low is better |+| `headroom_provider_cache_hit_requests_total` / `headroom_provider_cache_requests_total` | Cache effectiveness, by provider | >20% is good |+| `headroom_requests_failed_total` | Reliability (upstream 5xx errors) | 0 |## Grafana Dashboard-A ready-to-import dashboard ships in+A dashboard template ships in[`examples/grafana/headroom-dashboard.json`](https://github.com/headroomlabs-ai/headroom/blob/main/examples/grafana/headroom-dashboard.json).-Import it in Grafana (**Dashboards → New → Import → Upload**) and pick your Prometheus-datasource — it renders tokens saved, request throughput, and processing overhead-(`headroom_overhead_ms_sum` / `headroom_overhead_ms_count`) straight from the metrics-the `/metrics` endpoint exposes.+Its metric names match `/metrics`, but every panel query filters on a `pool` label+(e.g. `headroom_tokens_saved_total{pool=~"..."}`) that no metric in+`headroom/proxy/prometheus_metrics.py` actually emits, so the panel dropdowns come up+empty on import. Edit the queries to drop the `pool=~"..."` filter, or use the ad-hoc+queries below instead.Example ad-hoc queries against the same metric family:@@ -373,6 +369,5 @@ Example ad-hoc queries against the same metric family:|-------|--------|| Runtime Tokens Saved | `headroom_tokens_saved_total` || Lifetime Tokens Saved | `headroom_persistent_savings_tokens_saved_total` |-| Compression Ratio (median) | `histogram_quantile(0.5, headroom_compression_ratio_bucket)` |-| Request Latency (p99) | `histogram_quantile(0.99, headroom_latency_seconds_bucket)` |-| Cache Hit Rate | `headroom_cache_hits_total / (headroom_cache_hits_total + headroom_cache_misses_total)` |+| Mean Headroom Overhead | `rate(headroom_overhead_ms_sum[5m]) / rate(headroom_overhead_ms_count[5m])` |+| Cache Hit Rate (by provider) | `sum by (provider) (rate(headroom_provider_cache_hit_requests_total[5m])) / sum by (provider) (rate(headroom_provider_cache_requests_total[5m]))` |diff --git a/docs/content/docs/opencode-deepseek.mdx b/docs/content/docs/opencode-deepseek.mdxindex a9a3594af..9d2bf94df 100644--- a/docs/content/docs/opencode-deepseek.mdx+++ b/docs/content/docs/opencode-deepseek.mdx@@ -3,7 +3,9 @@ title: OpenCode + DeepSeekdescription: Configure OpenCode to route DeepSeek traffic through the Headroom proxy for compression, output shaping, and savings visibility.----Save 20-60% on DeepSeek API costs with Headroom's context compression proxy.+Cut DeepSeek API costs with Headroom's context compression proxy: tool outputs,+logs, and search results are compressed before they reach the model, and+responses can be shaped to be more concise.## How it works@@ -22,9 +24,9 @@ concise. DeepSeek's API is OpenAI-compatible — one flag and you're running.## 1. Install Headroom```bash-pip install headroom-ai+pip install "headroom-ai[proxy]"# or via uv:-uv tool install headroom-ai+uv tool install "headroom-ai[proxy]"```You get SmartCrusher (structural compression), the proxy, output shaping, and@@ -71,7 +73,7 @@ curl -s http://127.0.0.1:8787/v1/models \Output shaping makes the model's responses shorter — fewer tokens, lower cost:```bash-HEADROOM_ROLLOUT_CHANNEL=beta HEADROOM_OUTPUT_SHAPER=1 HEADROOM_VERBOSITY_LEVEL=2 \+HEADROOM_OUTPUT_SHAPER=1 HEADROOM_VERBOSITY_LEVEL=2 \headroom proxy --port 8787 --openai-api-url https://api.deepseek.com/v1```@@ -225,8 +227,8 @@ shaper is active immediately — the numbers just need calibration.- **Claude or GPT models** — this setup uses DeepSeek exclusively- **`headroom wrap`** — do not use it; it overrides the config- **Deprecated model names** — `deepseek-chat` and `deepseek-reasoner` are- compatibility aliases that will be deprecated on 2026-07-24; use- `deepseek-v4-pro` and `deepseek-v4-flash` instead+ compatibility aliases slated for removal; use `deepseek-v4-pro` and+ `deepseek-v4-flash` instead- **Kompress (ML compression)** — requires extra dependencies; SmartCrusherhandles the majority of use cases- **Any code changes** — headroom ships full DeepSeek support nativelydiff --git a/docs/content/docs/pipeline-extensions.mdx b/docs/content/docs/pipeline-extensions.mdxindex 640099c06..23dc9da41 100644--- a/docs/content/docs/pipeline-extensions.mdx+++ b/docs/content/docs/pipeline-extensions.mdx@@ -18,6 +18,7 @@ Extensions receive a `PipelineEvent` for each stage in `headroom.pipeline.Pipeli| `INPUT_CACHED`, `INPUT_ROUTED`, `INPUT_COMPRESSED`, `INPUT_REMEMBERED` | Cache, routing, compression, memory stages || `PRE_SEND` | Last hook before the request is forwarded upstream || `POST_SEND`, `RESPONSE_RECEIVED` | After forwarding / on response |+| `OUTCOME_OBSERVED` | Emits a read-only `OutcomeSnapshot` (tokens, stop reason, transforms applied) once the response is fully processed |`PRE_SEND` is the right stage for normalizing requests to fit a quirky upstream: compression and caching are done, and whatever you write into `event.messages` is exactly what the provider receives.diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdxindex 3390a086d..0c5db144e 100644--- a/docs/content/docs/proxy.mdx+++ b/docs/content/docs/proxy.mdx@@ -22,7 +22,19 @@ headroom proxy \--budget 100.0```-Telemetry is **local-only and off by default**. `HEADROOM_TELEMETRY=on` (or `--telemetry`) turns on in-process usage stats that power your own `/stats`, `/metrics`, and dashboard — **nothing is sent to Headroom Labs**. (The anonymous aggregate beacon that older versions shipped has been removed from the code.)+Two independent telemetry switches exist. `HEADROOM_TELEMETRY=on` (or `--telemetry`) turns on **local-only** in-process usage stats that power your own `/stats`, `/metrics`, and dashboard — off by default, and nothing under this switch leaves the machine.++Separately, an **anonymous usage beacon is on by default** (opt-out). Once a session goes idle it POSTs a small summary of how compression behaved to a Headroom Labs collector.++**Why it exists.** Compression quality is the product. The beacon tells us when a release changes it — a ratio that regresses, a content type that starts getting skipped, a provider path that begins failing — across real workloads rather than only our own test corpus. That is the whole purpose; there is no other use.++**What it sends.** Counters and identifiers, never free text. The collector applies an allowlist server-side and drops everything else before storage ([`deploy/beacon/worker.js`](https://github.com/headroomlabs-ai/headroom/blob/main/deploy/beacon/worker.js)): token totals, compression ratios and rates, skip reasons, source and provider names, model ids, failure counts and status codes, and a routing summary. Alongside those, seven resource attributes: service name and version, install id, install mode, stack, OS type and CPU architecture. A typical event is about 2KB.++**What it never sends.** Your prompts, your completions, your code, file paths, file contents, environment variables, or anything else derived from request or response bodies. None of these are on the allowlist, so even if a future client sent one the collector would discard it.++The install id is a random UUID generated on first run and stored in your config directory. It is deliberately not derived from hostname, MAC address, or any hardware property — delete the file and you get a new one.++Disable it with `HEADROOM_BEACON=off`, the `DO_NOT_TRACK=1` convention, or `--offline` (which also disables update checks and license reporting).## CLI options@@ -96,11 +108,11 @@ headroom proxy --mode cache| Profile | Target savings | Mode | Notes ||---------|----------------|------|-------|| `coding` | emergent (~50%) | `cache` | **Default.** Delta-only compression at ~0 prefix-cache busts; never lossy-compresses file reads. |-| `balanced` | ~70% | `token` | Moderate compression with structural compaction. Also the fallback for an unknown profile name. |+| `balanced` | ~70% | `token` | Moderate compression with structural compaction. || `agent-90` | ~90% | `token` | Aggressive; pins a `0.10` keep-ratio and forces Kompress. || `general` | emergent (~60%) | `token` | Non-coding workloads. |-An unrecognized `HEADROOM_SAVINGS_PROFILE` value logs a warning and falls back to `balanced` — the proxy never fails to start over a bad profile name. See `headroom/agent_savings.py` for each profile's full set of knobs.+An unrecognized `HEADROOM_SAVINGS_PROFILE` value logs a warning and falls back to `coding` (the same default an unset variable resolves to) — the proxy never fails to start over a bad profile name. `balanced` is used only as a last-resort fallback when the runtime has no `coding` entry at all (old-runtime/new-client version skew). See `headroom/agent_savings.py` for each profile's full set of knobs.Because the default `coding` profile uses **cache** mode (and the proxy's own default mode is also `cache`), Headroom runs in cache mode out of the box. Mode precedence: an explicit `--mode` wins, otherwise `HEADROOM_MODE` (which a profile seeds), otherwise the `cache` default. To run token mode, pass `--mode token` or choose a token-mode profile:@@ -122,13 +134,13 @@ HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy --port 8787| `--no-learn` | `false` | Explicitly disable traffic learning || `--min-evidence` | `5` | Minimum observations before a learned pattern is persisted || `--codex-wire-debug` | `false` | Write local Codex wire snapshots and matching proxy log traces |-| `--compress-passthrough` | `false` | Also compress custom proxy paths that fall through to the catch-all handler (OpenAI Responses-shaped bodies, path ends in `/responses`). Also `HEADROOM_COMPRESS_PASSTHROUGH=1` |+| `HEADROOM_COMPRESS_PASSTHROUGH` | `0` | Also compress custom proxy paths that fall through to the catch-all handler (OpenAI Responses-shaped bodies, path ends in `/responses`). No `--compress-passthrough` flag on `headroom proxy`; the direct module entry point (`python -m headroom.proxy.server`) does accept one |```bashheadroom proxy --memoryheadroom proxy --learn --min-evidence 3headroom proxy --codex-wire-debug-headroom proxy --compress-passthrough+HEADROOM_COMPRESS_PASSTHROUGH=1 headroom proxy```<Callout type="info" title="LLMLingua removed from the proxy CLI">@@ -153,7 +165,7 @@ HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy| `balanced` | 70% | `token` | No | General-purpose moderate compression || `general` | ~60% (emergent) | `token` | No | Non-coding chat, little code in context |-**`coding` (default)** — Optimizes for coding-agent workloads with Anthropic. Uses **cache mode** (`proxy_mode="cache"`): compresses only the newest delta in each turn so the provider's prefix-cache is never busted. User messages are compressed, system prompts preserved (hottest cache). Protects the 2 most recent turns verbatim. Lossless-first with lossy fallback; tool search and cross-turn dedup enabled. This is the profile that `headroom wrap` uses.+**`coding` (default)** — Optimizes for coding-agent workloads with Anthropic. Uses **cache mode** (`proxy_mode="cache"`): compresses only the newest delta in each turn so the provider's prefix-cache is never busted. User messages are compressed, system prompts preserved (hottest cache). `protect_recent` is `0` — in cache mode the delta already *is* the newest turn, so a turn-count guard would suppress the only thing cache mode compresses; byte-exact fidelity instead comes from `protect_reads=True` (file reads are never lossy-compressed). Lossless-first with lossy fallback; tool search and cross-turn dedup enabled. This is the profile that `headroom wrap` uses.**`agent-90`** — Forces ML-based (Kompress) compression with a 10% keep-ratio, ignoring the lossless path. Compresses both user and system messages. Designed for non-coding or cost-sensitive workloads where maximum compression is the goal.@@ -212,7 +224,7 @@ Fine-grained control over what gets compressed and how hard. Most users pick a [| `--mode` / `HEADROOM_MODE` | `cache` | `cache` compresses only the newest delta (prefix-cache safe); `token` maximizes removal. || `--target-ratio` / `HEADROOM_TARGET_RATIO` | unset | Keep-ratio for ML text compression; lower = more aggressive (e.g. `0.10`). || `HEADROOM_MIN_TOKENS` | `500` | Minimum block size before a tool output is compressed. |-| `--compress-user-messages` / `HEADROOM_COMPRESS_USER_MESSAGES` | `false` | Compress content inside user-role messages (tool results live there). The `coding` profile turns this on. |+| `HEADROOM_COMPRESS_USER_MESSAGES` | `false` | Compress content inside user-role messages (tool results live there). The `coding` profile turns this on. No `--compress-user-messages` flag on `headroom proxy`; the direct module entry point (`python -m headroom.proxy.server`) does accept one. || `HEADROOM_COMPRESS_SYSTEM_MESSAGES` | unset | Compress system prompts. Off by default to keep the hottest cache prefix stable. || `HEADROOM_PROTECT_RECENT` | profile | Never compress the N most recent turns. || `--protect-tool-results` / `HEADROOM_PROTECT_TOOL_RESULTS` | empty | Comma-separated tool names whose output is never lossy-compressed. |@@ -227,7 +239,7 @@ Kompress is the ModernBERT/ONNX compressor that ContentRouter falls back to for|---|---|---|| `--disable-kompress` / `HEADROOM_DISABLE_KOMPRESS` | `false` | Turn off ML compression; keep the structural compressors. || `--disable-kompress-anthropic` / `--disable-kompress-openai` | inherit | Per-provider override. |-| `--force-kompress-all` / `HEADROOM_FORCE_KOMPRESS_ALL` | `false` | Route *all* content through Kompress, bypassing per-type selection. |+| `HEADROOM_FORCE_KOMPRESS_ALL` | `false` | Route *all* content through Kompress, bypassing per-type selection. No `--force-kompress-all` flag on `headroom proxy`; the direct module entry point (`python -m headroom.proxy.server`) does accept one. || `HEADROOM_KOMPRESS_ENDPOINT` | none | Offload ML compression to a remote `/compress` endpoint (e.g. a Modal deployment) instead of running the model locally. || `HEADROOM_KOMPRESS_ENDPOINT_TOKEN` | none | Bearer token for the remote endpoint. || `HEADROOM_KOMPRESS_BACKEND` | `auto` | Compute backend: `auto`, `onnx_cpu`, `onnx_coreml`, `pytorch`, `pytorch_mps`. |@@ -740,12 +752,14 @@ headroom proxy```bashpip install gunicorn-gunicorn headroom.proxy.server:app \+gunicorn "headroom.proxy.server:create_app()" \--workers 4 \--bind 0.0.0.0:8787 \--worker-class uvicorn.workers.UvicornWorker```+`headroom.proxy.server` has no module-level `app` object — it exposes a `create_app(config: ProxyConfig | None = None) -> FastAPI` factory, so gunicorn's import string must call it.+### Docker```dockerfilediff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdxindex 36615f526..afa76b2b0 100644--- a/docs/content/docs/quickstart.mdx+++ b/docs/content/docs/quickstart.mdx@@ -156,7 +156,8 @@ const result = {tokensBefore: 45000,tokensAfter: 4500,tokensSaved: 40500,- compressionRatio: 0.9,+ // compressionRatio is tokensAfter / tokensBefore, so savings is 1 - ratio.+ compressionRatio: 0.1,transformsApplied: ['smart_crusher', 'cache_aligner'],messages: [],ccrHashes: [],@@ -166,7 +167,7 @@ const result = {console.log(`Tokens before: ${result.tokensBefore}`);console.log(`Tokens after: ${result.tokensAfter}`);console.log(`Tokens saved: ${result.tokensSaved}`);-console.log(`Compression: ${(result.compressionRatio * 100).toFixed(0)}%`);+console.log(`Compression: ${((1 - result.compressionRatio) * 100).toFixed(0)}%`);console.log(`Transforms: ${result.transformsApplied.join(', ')}`);```@@ -236,11 +237,14 @@ The biggest savings come from tool outputs -- search results, database rows, log| Content type | Compressor | Typical savings ||---|---|---|-| JSON arrays | SmartCrusher | 70--90% |-| Source code | CodeCompressor | 40--70% |-| Build/test logs | LogCompressor | 80--95% |-| Search results | SearchCompressor | 60--80% |-| Plain text | Kompress | 30--50% |+| JSON arrays | SmartCrusher | varies with array size and redundancy |+| Source code | CodeCompressor | opt-in; disabled by default |+| Build/test logs | LogCompressor | varies with log verbosity |+| Search results | SearchCompressor | varies with result set size |+| Plain text | Kompress | varies with redundancy |++Savings depend heavily on how repetitive the content is -- see+[Benchmarks](/docs/benchmarks) for measured numbers on real workloads.## Next stepsdiff --git a/docs/content/docs/releases.mdx b/docs/content/docs/releases.mdxindex c876f4080..dabe1ccdf 100644--- a/docs/content/docs/releases.mdx+++ b/docs/content/docs/releases.mdx@@ -1,42 +1,42 @@-----title: Releases & CI/CD+---+title: Releases & CI/CDdescription: Automated release pipeline with release-please, semantic versioning, multi-package publishing, and changelog generation.------## Overview-+---++## Overview+Headroom uses `release-please` to maintain a release PR from conventional commits on `main`. Merging that release PR creates the release tag and GitHub Release, which triggers `.github/workflows/release.yml` to publish all packages, build version-matched Docker images, and attach release assets.The release workflow also calls `.github/workflows/docker.yml` as a reusable workflow so GHCR images are published in the same release run with the exact same synced version as PyPI, npm, and GitHub release assets.For the end-to-end visual flow, see [CI/CD Flow Diagrams](/docs/ci-cd-flows).--## Packages & Registries--| Package | Type | Registry | Environment Variable |-|---------|------|----------|----------------------|-| `headroom-ai` | Python | PyPI | `PYPI_PACKAGE` |++## Packages & Registries++| Package | Type | Registry | Environment Variable |+|---------|------|----------|----------------------|+| `headroom-ai` | Python | PyPI | `PYPI_PACKAGE` || `headroom-ai` | TypeScript SDK | npmjs.org | `NPM_SDK_PACKAGE` || `headroom-openclaw` | TypeScript plugin | npmjs.org | `NPM_OPENCLAW_PACKAGE` || `headroom-opencode` | TypeScript plugin | npmjs.org | `NPM_OPENCODE_PACKAGE` || `@{owner}/headroom-ai` | TypeScript SDK | GitHub Package Registry | — || `@{owner}/headroom-openclaw` | TypeScript plugin | GitHub Package Registry | — || `headroom-ai-{version}.tar.gz` / `headroom_ai-{version}-py3-none-any.whl` | Python package distributions | GitHub Release (`{owner}/headroom`) | — |-| `headroom-ai-{version}.tgz` / `headroom-openclaw-{version}.tgz` | Node release assets | GitHub Release (`{owner}/headroom`) | — |-| `ghcr.io/{owner}/headroom` | Docker image | GitHub Container Registry | — |--## Version Strategy-+| `headroom-ai-{version}.tgz` / `headroom-openclaw-{version}.tgz` | Node release assets | GitHub Release (`{owner}/headroom`) | — |+| `ghcr.io/{owner}/headroom` | Docker image | GitHub Container Registry | — |++## Version Strategy+Release Please calculates the release version from conventional commits and the release manifest. The release workflow still computes and verifies the version it is about to publish:-+1. `.release-please-config.json` defines release-please behavior.2. `.release-please-manifest.json` tracks current package versions.3. The release PR updates versions and changelog content.4. Merging the release PR publishes a GitHub Release tagged `vX.Y.Z`.5. `release.yml` uses that tag as the manual version for the publish run.--### Version Files-++### Version Files+- `.release-please-config.json` - release-please package configuration- `.release-please-manifest.json` - release-please version manifest- `pyproject.toml` - `[project].version`@@ -46,7 +46,7 @@ Release Please calculates the release version from conventional commits and the- `sdk/typescript/package.json` - `version`, synced at build time`release.yml` does not commit back to the repo. Version synchronization happens inside the release build workspace.-+## Conventional Commits & Semantic BumpingRelease Please analyzes unreleased conventional commits and applies the highest required bump level:@@ -61,25 +61,31 @@ Release Please analyzes unreleased conventional commits and applies the highestCommits are linted in CI via `commitlint` using `@commitlint/config-conventional`.The release PR is the place where version and changelog changes are reviewed before publishing.--## Release Workflow-++## Release Workflow+The `release.yml` workflow runs when a GitHub Release is published, which normally happens when the release-please PR is merged. It also supports manual `workflow_dispatch` and PR dry-runs for release-critical workflow/package changes.--```-detect-version → build → build-wheels → collect-dist → smoke-import-wheels- ↘ publish-pypi- ↘ publish-npm- ↘ publish-github-packages- ↘ publish-docker- → create-release+```+detect-version → build → build-wheels ─┬→ collect-dist ─┐+ │ └→ smoke-import-wheels ─┬→ publish-pypi ─┐+ ├──────────────────────────────────────┼→ publish-docker ┤+ ├→ publish-npm ──────────────────────────────────────────┤+ └→ publish-github-packages ──────────────────────────────┴→ create-release+```++`build-wheels` fans out to `collect-dist` and `smoke-import-wheels` in+parallel (both only need the wheel artifacts, not each other).+`publish-npm` and `publish-github-packages` only need `detect-version` ++`build` -- they do not wait on the wheel matrix at all. `publish-pypi` and+`publish-docker` both gate on `smoke-import-wheels`. `create-release` is the+only job that waits on everything (`.github/workflows/release.yml:78-1004`).The workflow never commits back to the repo.-+### detect-versionResolves the release version from the trigger. On `release: published`, it uses the published tag (`vX.Y.Z`) as the manual version for the run. On `workflow_dispatch`, it uses the optional `version` input when provided. PR dry-runs compute a version without publishing.-+### build1. Syncs version across package files via `scripts/version-sync.py --version {npm_version}`2. Verifies package versions with `scripts/verify-versions.py`@@ -88,72 +94,72 @@ Resolves the release version from the trigger. On `release: published`, it uses5. Uploads release asset artifacts for downstream publish jobs### build-wheels-Builds the Python wheel matrix for Linux x86_64, Linux arm64, and Apple Silicon macOS, plus one source distribution. Linux wheels are audited for glibc symbol compatibility.+Builds the Python wheel matrix for Linux x86_64, Linux arm64, Apple Silicon macOS, Intel macOS, and Windows x86_64, plus one source distribution (`.github/workflows/release.yml:214-264`). Linux wheels are audited for glibc symbol compatibility.### collect-distCollects the wheel matrix, source distribution, and npm tarballs into the canonical artifacts used by publishing and GitHub Release asset upload.### smoke-import-wheelsInstalls the built wheels into representative customer environments and imports `headroom._core`. This blocks publishing if a wheel builds successfully but cannot import on its promised platform floor.--### publish-pypi-Downloads the Python dist artifact and publishes to PyPI via `pypa/gh-action-pypi-publish@release/v1` (trusted publisher).--### publish-npm++### publish-pypi+Downloads the Python dist artifact and publishes to PyPI via `pypa/[email protected]` (trusted publisher).++### publish-npmPublishes all npm packages to npmjs.org:- `sdk/typescript/` as `headroom-ai`- `plugins/openclaw/` as `headroom-openclaw`- `plugins/opencode/` as `headroom-opencode`--### publish-github-packages-Publishes both Node packages to GitHub Package Registry (`npm.pkg.github.com`) using the current repository owner as the npm scope:-- `sdk/typescript/` as `@{owner}/headroom-ai`-- `plugins/openclaw/` as `@{owner}/headroom-openclaw`--### GitHub release assets++### publish-github-packages+Publishes both Node packages to GitHub Package Registry (`npm.pkg.github.com`) using the current repository owner as the npm scope:+- `sdk/typescript/` as `@{owner}/headroom-ai`+- `plugins/openclaw/` as `@{owner}/headroom-openclaw`++### GitHub release assetsUploads the built Python distributions and both npm tarballs to the GitHub Release created in the current repository. GitHub Packages does not provide a PyPI-compatible package registry, so the workflow publishes Python wheels and sdists to GitHub as release assets while npm packages go to GitHub Package Registry and Docker images go to GHCR.--### publish-docker-Calls the reusable Docker workflow to publish GHCR images with the same semantic version and synced package metadata as the rest of the release.-++### publish-docker+Calls the reusable Docker workflow to publish GHCR images with the same semantic version and synced package metadata as the rest of the release.+### create-releaseCreates or updates the GitHub Release in the current repo and uploads the built Python distributions and npm tarballs as release assets. PyPI publish is a hard gate unless `PYPI_SKIP=true`, so release notes and assets do not advertise a version that failed to publish to PyPI.--## Configuration--All package names, registry URLs, and environment names are defined as top-level `env` constants:--```yaml-env:- PYPI_PACKAGE: headroom-ai- PYPI_ENVIRONMENT: pypi++## Configuration++All package names, registry URLs, and environment names are defined as top-level `env` constants:++```yaml+env:+ PYPI_PACKAGE: headroom-ai+ PYPI_ENVIRONMENT: pypiNPM_REGISTRY_URL: https://registry.npmjs.orgNPM_SDK_PACKAGE: headroom-aiNPM_OPENCLAW_PACKAGE: headroom-openclawNPM_OPENCODE_PACKAGE: headroom-opencodeGITHUB_PACKAGES_REGISTRY_URL: https://npm.pkg.github.com-```--To rename a package, update the corresponding constant — all references throughout the workflow update automatically.--## Safety Gates--Each publish job requires **both** of the following to be false:--```yaml-if: github.event.inputs.dry_run != 'true' && vars.PYPI_SKIP != 'true'-```--To skip a publish target, set the corresponding GitHub Actions variable:--| Variable | Effect |-|----------|--------|-| `PYPI_SKIP=true` | Skip PyPI publish |-| `NPM_SKIP=true` | Skip both npm publishes |-| `GH_PACKAGES_SKIP=true` | Skip GitHub Package Registry publish |--Set these in: **GitHub repo → Settings → Variables → Actions Variables → New repository variable**.-+```++To rename a package, update the corresponding constant — all references throughout the workflow update automatically.++## Safety Gates++Each publish job requires all of the following to be true (`.github/workflows/release.yml:768`, PyPI shown; npm/GitHub Packages mirror it with their own skip variable):++```yaml+if: github.event_name != 'pull_request' && github.event.inputs.dry_run != 'true' && vars.PYPI_SKIP != 'true'+```++To skip a publish target, set the corresponding GitHub Actions variable:++| Variable | Effect |+|----------|--------|+| `PYPI_SKIP=true` | Skip PyPI publish |+| `NPM_SKIP=true` | Skip both npm publishes |+| `GH_PACKAGES_SKIP=true` | Skip GitHub Package Registry publish |++Set these in: **GitHub repo → Settings → Variables → Actions Variables → New repository variable**.+PyPI publishing is a hard gate for GitHub Releases unless `PYPI_SKIP=true`.If the PyPI upload fails, the workflow stops before creating or updating theGitHub Release, so release notes cannot advertise a version that was not@@ -201,33 +207,34 @@ on:required: falsedry_run:description: "Skip publish"- type: boolean- default: false-```+ type: boolean+ default: false+```- **Normal release:** merge the release-please PR; the bot publishes a GitHub Release, which triggers `release.yml`.- **PR dry-run:** release-critical PRs build and smoke-import wheels before merge, but do not publish.- **Manual dispatch:** use `version` to override the release version and `dry_run: true` to skip publish steps.--## Local Testing with `act`--### Prerequisites--```bash-# Install act-winget install act--# Optional: install actionlint for schema validation-winget install actionlint-```--### Dry-run Test--```bash-act workflow_dispatch -W .github/workflows/release.yml -e .github/act/dry-run.json-```--This runs the full workflow end-to-end with `dry_run=true`, skipping all publish steps.-++## Local Testing with `act`++### Prerequisites++```bash+# macOS+brew install act actionlint++# Windows+winget install act+winget install actionlint+```++### Dry-run Test++```bash+act workflow_dispatch -W .github/workflows/release.yml -e .github/act/dry-run.json+```++This runs the full workflow end-to-end with `dry_run=true`, skipping all publish steps.+### Simulate Release Please```bash@@ -243,53 +250,53 @@ act release -W .github/workflows/release.yml -e .github/act/release-published.js```The `release-published.json` event file simulates the event emitted when the release-please PR is merged.--### Validate the Release and Docker Workflows--```bash-bash scripts/validate-workflows.sh-```--This runs `actionlint` plus `act -n` against the release and Docker workflows using the checked-in `.github/act/*.json` event fixtures. CI runs the same script in the `workflow-validation` job so branch changes to release automation are validated before merge.--### Local Secrets--```bash-cp .env.act.example .env.act-# Edit .env.act and add your test tokens-```--`act` automatically reads `.env` and passes values as workflow secrets.--## Workflow Files Reference--| File | Purpose |-|------|---------|++### Validate the Release and Docker Workflows++```bash+bash scripts/validate-workflows.sh+```++This runs `actionlint` plus `act -n` against the release and Docker workflows using the checked-in `.github/act/*.json` event fixtures. CI runs the same script in the `workflow-validation` job so branch changes to release automation are validated before merge.++### Local Secrets++```bash+cp .env.act.example .env.act+# Edit .env.act and add your test tokens+```++`act` automatically reads `.env` and passes values as workflow secrets.++## Workflow Files Reference++| File | Purpose |+|------|---------|| `.github/workflows/release.yml` | Main release pipeline || `.github/workflows/release-please.yml` | Release PR aggregation from conventional commits || `.github/workflows/ci.yml` | CI — lint, test, commitlint || `.github/workflows/publish.yml` | Manual-only PyPI fallback (superseded by `release.yml`) |-| `.commitlintrc.json` | Conventional commit rules |-| `scripts/version-sync.py` | Sync version across all packages |-| `scripts/changelog-gen.py` | Generate changelog from git log |-| `scripts/verify-versions.py` | Pre-release version alignment check |+| `.commitlintrc.json` | Conventional commit rules |+| `scripts/version-sync.py` | Sync version across all packages |+| `scripts/changelog-gen.py` | Generate changelog from git log |+| `scripts/verify-versions.py` | Pre-release version alignment check || `.github/act/dry-run.json` | `act` event file for dry-run testing || `.github/act/push-feat.json` | `act` event file for feat commit testing || `.github/act/release-published.json` | `act` event file for release publish simulation || `.github/act/docker-version.json` | `act` event file for Docker workflow validation |-| `scripts/validate-workflows.sh` | Shared `actionlint` + `act -n` workflow validation script |-| `.actrc` | Default `act` flags (Ubuntu runner, reuse, quiet) |-| `.actrc.local.example` | Local `act` override template |--## Required GitHub Secrets--| Secret | Purpose | Where to Get |-|--------|---------|--------------|-| `NPM_TOKEN` | Publishing to npmjs.org | npmjs.com → Account → Access Tokens |-| `GITHUB_TOKEN` | GitHub Package Registry (auto-provided) | Automatically available in GitHub Actions |--The PyPI publish uses trusted publisher OIDC — no secret required, only the `pypi` GitHub Environment must be configured with your PyPI project.-+| `scripts/validate-workflows.sh` | Shared `actionlint` + `act -n` workflow validation script |+| `.actrc` | Default `act` flags (Ubuntu runner, reuse, quiet) |+| `.actrc.local.example` | Local `act` override template |++## Required GitHub Secrets++| Secret | Purpose | Where to Get |+|--------|---------|--------------|+| `NPM_TOKEN` | Publishing to npmjs.org | npmjs.com → Account → Access Tokens |+| `GITHUB_TOKEN` | GitHub Package Registry (auto-provided) | Automatically available in GitHub Actions |++The PyPI publish uses trusted publisher OIDC — no secret required, only the `pypi` GitHub Environment must be configured with your PyPI project.+## Release CadenceDay to day:diff --git a/docs/content/docs/savings.mdx b/docs/content/docs/savings.mdxindex b0a3f6d6b..02ed3eda1 100644--- a/docs/content/docs/savings.mdx+++ b/docs/content/docs/savings.mdx@@ -1,6 +1,6 @@---title: Savings Tracking-description: Durable, over-time compression savings — cost avoided plus Today / Last 7 days / All time and per-model / per-client breakdowns via `headroom savings`.+description: Durable, over-time compression savings — cost avoided plus Today / Last 7 days / Last 30 days and per-model / per-client breakdowns via `headroom savings`.---`headroom savings` shows how much Headroom has saved you over time — cost avoided, token counts, and breakdowns by model and client. Unlike `headroom_stats` (a single in-memory session snapshot), it reads a **durable ledger** that survives proxy and agent restarts.@@ -10,7 +10,7 @@ description: Durable, over-time compression savings — cost avoided plus Today```bashheadroom savings # human-readable summaryheadroom savings --json # machine-readable report-headroom savings --days 30 # restrict the lookback/retention window+headroom savings --days 7 # restrict the lookback window (1-30, default 30)headroom savings --reset # delete the ledger and start fresh```@@ -19,7 +19,7 @@ headroom savings --reset # delete the ledger and start fresh```textToday ███████████░░░░░ 67.9% saved 19,000 / 28,000 tokens $0.0850Last 7 days ███████████░░░░░ 67.1% saved 47,000 / 70,000 tokens $0.2250-All time ██████████░░░░░░ 65.0% saved 78,000 / 120,000 tokens $0.2680+Last 30 days ██████████░░░░░░ 65.0% saved 78,000 / 120,000 tokens $0.2680Cost avoided per model:claude-opus-4-8 $0.1750@@ -38,7 +38,7 @@ Every compression appends one line to an **append-only, file-locked event ledger- **Durable** — the ledger is on disk, so totals survive proxy and agent restarts.- **Accurate under concurrency** — Headroom's MCP server runs as multiple processes (the main agent plus each subagent), and the proxy is a separate process. An append-only, locked log lets every writer contribute without the lost-update races a single shared mutable file would suffer.-- **Self-pruning** — events older than the retention window (365 days by default) are dropped on read, and the file is compacted once it grows large.+- **Self-pruning** — events older than the retention window (30 days, which is also the hard maximum for `--days`) are dropped on read, and the file is compacted once it grows large.Both compression paths feed the same ledger:@@ -47,7 +47,7 @@ Both compression paths feed the same ledger:### Cost basis-Cost avoided is the dollar value of the saved **input** tokens. Headroom uses [litellm](https://headroom-docs.vercel.app/docs/litellm) list pricing where the model is known (proxy traffic). MCP-tool compressions don't know the agent's upstream model, so they record `model="unknown"` and fall back to a blended per-token rate rather than reporting `$0`.+Cost avoided is the dollar value of the saved **input** tokens. Headroom uses [litellm](https://docs.headroomlabs.ai/docs/litellm) list pricing where the model is known (proxy traffic). MCP-tool compressions don't know the agent's upstream model, so they record `model="unknown"` and fall back to a blended per-token rate rather than reporting `$0`.## Configurationdiff --git a/docs/content/docs/simulation.mdx b/docs/content/docs/simulation.mdxindex 6f40a435c..6090413f2 100644--- a/docs/content/docs/simulation.mdx+++ b/docs/content/docs/simulation.mdx@@ -45,12 +45,12 @@ plan = client.chat.completions.simulate(messages=messages,)-waste = plan.waste_signals-print(f"JSON bloat: {waste.json_bloat_tokens} tokens")-print(f"HTML noise: {waste.html_noise_tokens} tokens")-print(f"Whitespace: {waste.whitespace_tokens} tokens")-print(f"Dynamic dates: {waste.dynamic_date_tokens} tokens")-print(f"Repetition: {waste.repetition_tokens} tokens")+waste = plan.waste_signals # dict[str, int]+print(f"JSON bloat: {waste['json_bloat']} tokens")+print(f"HTML noise: {waste['html_noise']} tokens")+print(f"Whitespace: {waste['whitespace']} tokens")+print(f"Dynamic dates: {waste['dynamic_date']} tokens")+print(f"Repetition: {waste['repetition']} tokens")```Waste signals help you understand which parts of your input are contributing the most unnecessary tokens.@@ -124,7 +124,7 @@ else:Test different configurations to find the best settings for your workload:```python-from headroom import HeadroomClient, OpenAIProvider+from headroom import HeadroomClient, HeadroomConfig, OpenAIProviderfrom headroom.transforms import SmartCrusherConfigconfigs = [@@ -133,14 +133,14 @@ configs = [SmartCrusherConfig(max_items_after_crush=50),]-for config in configs:+for smart_crusher_config in configs:client = HeadroomClient(original_client=OpenAI(),provider=OpenAIProvider(),- smart_crusher_config=config,+ config=HeadroomConfig(smart_crusher=smart_crusher_config),)plan = client.chat.completions.simulate(model="gpt-4o", messages=messages)- print(f"max_items={config.max_items_after_crush}: "+ print(f"max_items={smart_crusher_config.max_items_after_crush}: "f"{plan.tokens_saved} tokens saved ({plan.tokens_saved/plan.tokens_before*100:.1f}%)")```diff --git a/docs/content/docs/smart-crusher.mdx b/docs/content/docs/smart-crusher.mdxindex 1c787f639..b2bf1c75d 100644--- a/docs/content/docs/smart-crusher.mdx+++ b/docs/content/docs/smart-crusher.mdx@@ -1,13 +1,17 @@---title: SmartCrusher-description: Statistical JSON and array compression that keeps important items and drops the rest, achieving 70-90% token reduction.+description: Statistical JSON and array compression that keeps important items and drops the rest.----SmartCrusher is Headroom's compressor for JSON tool outputs. It analyzes arrays statistically, keeps the important items (errors, anomalies, relevant matches), and drops the rest. This is the compressor that fires automatically when ContentRouter detects JSON arrays.+SmartCrusher is Headroom's compressor for JSON tool outputs. This is the compressor that fires automatically when ContentRouter detects JSON arrays.++<Callout type="info" title="Lossless-first, not keep/drop-first">+ By default SmartCrusher tries a **lossless** compaction first: if the array is cleanly tabular (a consistent set of keys across items), it re-encodes every item into a compact `csv-schema` form and keeps it *if that saves at least 30% of the bytes* -- no items are dropped, they're just represented more compactly. Only when that lossless fold doesn't clear the 30% bar (or the array isn't cleanly tabular) does SmartCrusher fall back to the scored keep/drop behavior described below. See `headroom/transforms/smart_crusher.py:415-419`. Set `with_compaction=False` on `SmartCrusher(...)` to force the pre-lossless keep/drop-only path (this is also what Headroom's retention-property tests use).+</Callout>## How It Works-SmartCrusher doesn't blindly truncate arrays. It scores each item across five dimensions:+When the lossy keep/drop path runs, SmartCrusher doesn't blindly truncate arrays -- it scores each item across five dimensions:1. **First/Last items** -- Context for pagination and recency2. **Error items** -- 100% preservation of error states (never dropped)@@ -15,7 +19,7 @@ SmartCrusher doesn't blindly truncate arrays. It scores each item across five di4. **Relevant items** -- Matches to the user's query via BM25/embeddings5. **Change points** -- Significant transitions in data-The result: a 1,000-item array becomes ~50 items with all the information the LLM actually needs.+On that path, the target size is `max_items_after_crush` (15 by default): a 1,000-item array becomes ~15 items with all the information the LLM actually needs (measured: a 1,000-item array with `with_compaction=False` compressed to 16 items).## What Gets Preserved@@ -53,15 +57,18 @@ console.log(`Tokens saved: ${result.tokensSaved}`);</Tab><Tab value="Python">```python+import jsonfrom headroom import SmartCrushercrusher = SmartCrusher()-# Before: 1000 search results (45,000 tokens)-tool_output = {"results": ["...1000 items..."]}+# crush() takes a JSON string, not a dict+tool_output = json.dumps({"results": ["...1000 items..."]})-# After: ~50 important items (4,500 tokens) -- 90% reduction-compressed = crusher.crush(tool_output, query="user's question")+# Returns a CrushResult; the compressed JSON string is `.compressed`+result = crusher.crush(tool_output, query="user's question")+print(result.compressed)+print(result.strategy) # e.g. "lossless:table(...)" or "smart_sample(1000->15)"```</Tab></Tabs>@@ -89,7 +96,7 @@ from headroom import SmartCrusher, SmartCrusherConfigconfig = SmartCrusherConfig(min_tokens_to_crush=200, # Only compress if > 200 tokens- max_items_after_crush=15, # Keep at most 15 items+ max_items_after_crush=15, # Keep at most 15 items (lossy path only)first_fraction=0.3, # Keep first 30% of itemslast_fraction=0.15, # Keep last 15% of itemsvariance_threshold=2.0, # Statistical variance threshold@@ -97,7 +104,7 @@ config = SmartCrusherConfig()crusher = SmartCrusher(config)-compressed = crusher.crush(tool_output, query="find payment failures")+result = crusher.crush(tool_output, query="find payment failures")```</Tab></Tabs>@@ -135,11 +142,11 @@ Consider a tool that returns 1,000 search results:]}-# After SmartCrusher: 4,500 tokens (90% reduction)-# Kept: first 3, last 2, the error at id=998, statistical sample+# After SmartCrusher's lossy keep/drop path (with_compaction=False):+# ~15-16 items kept -- first items, last items, and the error at id=998```-The LLM sees the structure, the error, and a representative sample -- everything it needs to answer "find errors in the last 24 hours" without wading through 1,000 identical success responses.+The LLM sees the structure, the error, and a representative sample -- everything it needs to answer "find errors in the last 24 hours" without wading through 1,000 identical success responses. Note this specific shape (mostly-identical items, one error) is also exactly what the lossless table fold favors (see the callout above), so with default settings this array is more likely to be re-encoded compactly with every item still present than reduced to ~15 items -- the numbers above illustrate the scored keep/drop path, not a guarantee of which path a given array takes.<Callout type="info" title="Automatic routing">You don't need to call SmartCrusher directly. The ContentRouter detects JSON arrays and routes them to SmartCrusher automatically. Direct usage is available when you want fine-grained control over the configuration.diff --git a/docs/content/docs/strands.mdx b/docs/content/docs/strands.mdxindex 90fccf831..2f2681235 100644--- a/docs/content/docs/strands.mdx+++ b/docs/content/docs/strands.mdx@@ -108,6 +108,8 @@ The model wrapper uses the full Headroom pipeline (CacheAligner, ContentRouter).## Structured output+`structured_output()` is an async generator (it delegates to the wrapped model's own `structured_output()`), so it must be consumed with `async for`:+```pythonfrom pydantic import BaseModel@@ -116,7 +118,8 @@ class Analysis(BaseModel):root_cause: strrecommendation: str-result = optimized.structured_output(Analysis, messages)+async for event in optimized.structured_output(Analysis, messages):+ result = event```## Metricsdiff --git a/docs/content/docs/text-and-logs.mdx b/docs/content/docs/text-and-logs.mdxindex 6514d43a8..2b46baa14 100644--- a/docs/content/docs/text-and-logs.mdx+++ b/docs/content/docs/text-and-logs.mdx@@ -7,11 +7,11 @@ Headroom provides specialized compressors for text-based content that isn't JSON| Compressor | Input Type | What It Preserves | Typical Savings ||---|---|---|---|-| `SearchCompressor` | grep/ripgrep output | Relevant matches, file diversity | 80-95% |-| `LogCompressor` | Build/test logs | Errors, stack traces, summaries | 85-95% |-| `DiffCompressor` | Unified diffs | Changed lines, context | 60-80% |-| `TextCrusher` | General text | Relevant sentences, anchors | 30-60% |-| `KompressCompressor` | General text fallback | Learned token scoring via ONNX | 30-50% |+| `SearchCompressor` | grep/ripgrep output | Relevant matches, file diversity | 80-95% (measured ~91% on a synthetic 40-file corpus) |+| `LogCompressor` | Build/test logs | Errors, stack traces, summaries | 85-95% (measured ~93% on a synthetic 1,000-line log) |+| `DiffCompressor` | Unified diffs | Changed lines, context | 60-80% (measured ~70% on a multi-file diff) |+| `TextCrusher` | General text | Relevant sentences, anchors | 30-60% (its `target_ratio` defaults to 0.5; measured ~50% on real docs prose) |+| `KompressCompressor` | General text fallback | Learned token scoring via ONNX | Highly variable -- `target_ratio` defaults to `None` ("model decides"), which measured only 6-24% on real prose; an explicit `target_ratio=0.5` measured ~40%. There is no fixed default range; see `benchmarks/text_crusher_quality_eval.py`. |## SearchCompressor@@ -159,9 +159,11 @@ print(f"Saved: {result.savings_percentage:.1f}%")If you're building your own routing logic, you can use the content type detector directly:```python-from headroom.transforms import detect_content_type, ContentType+from headroom.transforms import detect_content_type, ContentType, SearchCompressor, LogCompressor-content = "src/main.py:42:def process():"+# A single file:line:content line isn't enough signal -- the detector wants+# several matching lines before it calls something SEARCH_RESULTS.+content = "src/main.py:42:def process():\nsrc/utils.py:10:def helper():\nsrc/models.py:5:class Foo:"detection = detect_content_type(content)if detection.content_type == ContentType.SEARCH_RESULTS:@@ -182,15 +184,18 @@ The ContentRouter selects the right compressor automatically. Here's when each f| `file:line:content` lines | SearchCompressor | grep/ripgrep output format || pytest, npm, cargo markers | LogCompressor | Build tool output patterns || `---/+++` and `@@` markers | DiffCompressor | Unified diff format |-| Prose, documentation | TextCrusher | Fallback for non-structured text |-| Long plain text | KompressCompressor | ContentRouter fallback |+| Prose, documentation | KompressCompressor | ContentRouter's default for `PLAIN_TEXT` (`CompressionStrategy.TEXT` and `KOMPRESS` share the same ML compressor dispatch -- see `headroom/transforms/content_router.py:3524-3540`) |+| Long plain text that exceeds Kompress's size gate | TextCrusher | Request-path-safe fallback when the content is too large for synchronous ONNX inference (`_kompress_max_tokens`); TextCrusher is not ContentRouter's default path for ordinary prose |## Performance-| Compressor | Typical Input | Output | Speed |+Speed depends heavily on input size and shape; the figures below are one+measurement each (warm process, this package version), not a guarantee:++| Compressor | Measured Input | Measured Output | Measured Speed (warm) ||---|---|---|---|-| SearchCompressor | 1,000 matches | 30-50 matches | ~2ms |-| LogCompressor | 5,000 lines | 100-200 lines | ~3ms |-| DiffCompressor | Large diff | Changed hunks only | ~2ms |-| TextCrusher | 10,000 chars | 2,000 chars | ~2ms |-| KompressCompressor | Plain text | 50-70% of original | model-dependent |+| SearchCompressor | 1,000 matches across 60 files | 30 matches | ~2.0ms |+| LogCompressor | 5,000 lines, ~12 errors | 67 lines | ~17ms |+| DiffCompressor | 30-file / 90-hunk synthetic diff | changed hunks only | ~0.4ms |+| TextCrusher | 10,000 chars of prose | ~50% of input tokens (`target_ratio` default) | ~0.7ms |+| KompressCompressor | Plain text | Highly variable (see the ranges above) | model-dependent; first call after process start pays a one-time model-load cost |diff --git a/docs/content/docs/troubleshooting.mdx b/docs/content/docs/troubleshooting.mdxindex 5b796b371..0372d41ff 100644--- a/docs/content/docs/troubleshooting.mdx+++ b/docs/content/docs/troubleshooting.mdx@@ -150,7 +150,7 @@ config.smart_crusher.min_tokens_to_crush = 100 # Default is 200**Where the savings show up**: Look at the **Prefix Cache Impact** panel and the **Compression vs Cache** tile on the dashboard — these reflect cache-read savings rather than per-request compression. The headline "Tokens Saved" tile only counts compression, so in cache mode it understates the real benefit.-**To get 0.27.0-style compression numbers back**: run the proxy in token mode, which prioritizes visible compression:+**To get 0.27.0-style compression numbers back**: run the proxy in token mode, which prioritizes visible compression. Use this to compare or diagnose, not as a permanent setting — `cache` is the default because prefix-cache stability is usually worth more on a real agent workload than a larger headline compression number:```bash# Per run@@ -244,19 +244,22 @@ See [Server-managed settings platform availability](https://code.claude.com/docsconfig = HeadroomConfig()config.smart_crusher.max_items_after_crush = 50 # Default: 15-# 2. Skip compression for specific tools-response = client.chat.completions.create(- model="gpt-4o",- messages=messages,- headroom_tool_profiles={- "important_tool": {"skip_compression": True},- },-)--# 3. Disable SmartCrusher entirely+# 2. Disable SmartCrusher entirelyconfig.smart_crusher.enabled = False```+<Callout type="warning" title="headroom_tool_profiles has no effect in 0.37.0">+ `client.chat.completions.create(..., headroom_tool_profiles={...})` is+ accepted but not currently wired through `TransformPipeline.apply()` --+ the kwarg is documented in the pipeline's own docstring but never read+ in its body (`headroom/transforms/pipeline.py`), so passing it changes+ nothing. There is also no `skip_compression` key on the per-tool+ compression profile (`CompressionProfile` in `headroom/config.py` only+ has `bias`, `min_k`, `max_k`) -- passing a plain dict there would raise+ `AttributeError` if a code path did consume it. Use options 1 and 2+ above instead.+</Callout>+## High Latency**Symptom**: Requests take longer than expected.@@ -286,7 +289,9 @@ config.smart_crusher.min_tokens_to_crush = 500# 3. Disable transforms you don't needconfig.cache_aligner.enabled = False-config.rolling_window.enabled = False+# Note: the old rolling-window "drop messages from history" stage was+# retired (Phase B PR-B1); `HeadroomConfig` has no `rolling_window` field+# any more (`headroom/config.py`), so there is nothing left to disable there.```## Installation Issues@@ -535,7 +540,7 @@ plan = client.chat.completions.simulate()print(f"Tokens: {plan.tokens_before} -> {plan.tokens_after}")-print(f"Transforms: {plan.transforms_applied}")+print(f"Transforms: {plan.transforms}")print(f"Waste signals: {plan.waste_signals}")import json@@ -545,13 +550,16 @@ print(json.dumps(plan.messages_optimized, indent=2))### Test Transforms Directly```python-from headroom import SmartCrusher, Tokenizer+from headroom import SmartCrusher, Tokenizer, OpenAIProviderfrom headroom.config import SmartCrusherConfigimport jsonconfig = SmartCrusherConfig()crusher = SmartCrusher(config)-tokenizer = Tokenizer()+# Tokenizer wraps a provider-specific TokenCounter -- it takes no+# zero-argument form (headroom/tokenizer.py).+provider = OpenAIProvider()+tokenizer = Tokenizer(provider.get_token_counter("gpt-4o"), "gpt-4o")messages = [{diff --git a/headroom/config.py b/headroom/config.pyindex 146db921c..0cbc35bf2 100644--- a/headroom/config.py+++ b/headroom/config.py@@ -240,10 +240,22 @@ DEFAULT_EXCLUDE_TOOLS: frozenset[str] = frozenset(# plugin that supplies only the first half cannot be relied on to be# installed."read_file",+ # Skill bodies (Claude Code's `Skill` tool) are INSTRUCTIONS, not tool+ # output, and lossy compression on a directive does not degrade it --+ # it inverts it. "do not guess at model names" losing its "not" is a+ # correctness failure, not a quality tradeoff. Measured across 40 real+ # SKILL.md bodies on the lossy path: only 73.5% of negations (not,+ # never, avoid, unless, without) and 65.5% of modals (must, always,+ # only, required) survived; two skills kept 0/2 and 1/6 of theirs.+ # Bodies load on demand and are read once, so the tokens at stake are+ # small and the downside is unbounded. Named below as well, because+ # protecting a tool needs both halves.+ "Skill",# Lowercase variants for case-insensitive matching"read","glob","grep",+ "skill","write","edit","web_search",@@ -324,6 +336,15 @@ DEFAULT_BYTE_EXACT_EXCLUDE_TOOLS: frozenset[str] = frozenset(# partner-trial repo, which reported `read_file` reaching the provider# seam once the plugin started excluding it."read_file",+ # Skill bodies. The other half of the protection added above: excluding+ # `Skill` from the lossy path routes it INTO the excluded-tool fold, and+ # the fold rewrites what the model is SHOWN. On tool output that is a+ # fair trade; on a directive it is not, because the folds that collapse+ # repeated lines or hoist paths into headings can merge two distinct+ # instructions into one. Skill bodies are prose and fold poorly anyway,+ # so this costs close to nothing and removes the whole class.+ "Skill",+ "skill",})diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex dde28dabc..1bb9f7bbe 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -3627,7 +3627,11 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:# only names listed in config.proxy_extensions (CLI: --proxy-extension,# env: HEADROOM_PROXY_EXTENSIONS) actually get installed. Discovery alone# never runs third-party code. An extension that raises from its install()- # is a deliberate fail-closed signal and aborts startup.+ # disables *itself*: `install_all` logs it, prints a SKIPPED line to stderr+ # and the proxy keeps serving without that extension (extensions.py:169-183).+ # One bad plugin must not brick the proxy. Note the consequence: a plugin+ # whose licence gate raises is absent, not fatal — the feature fails closed,+ # the process does not.from headroom.proxy.extensions import install_all as _install_extensions_install_extensions(app, config, enabled=getattr(config, "proxy_extensions", None))diff --git a/headroom/transforms/kompress_compressor.py b/headroom/transforms/kompress_compressor.pyindex 67103ec3b..770b32476 100644--- a/headroom/transforms/kompress_compressor.py+++ b/headroom/transforms/kompress_compressor.py@@ -55,6 +55,19 @@ _KOMPRESS_MUST_KEEP_RE = re.compile(r"|\.[a-z]{2,4}\b" # extensions: .py .so .jsonr"|--?[a-z][\w-]*" # flags: --verbose, -nr"|\b[A-Z][a-z]+[A-Z]\w*" # CamelCase: EXC_BAD_INSTRUCTION, IndexError+ # Directive words. Every other class above protects a token the model could+ # not RECONSTRUCT; these protect tokens whose loss INVERTS the surrounding+ # sentence. Compressed prompts carry instructions as often as they carry+ # tool output, and "do not guess at model names" without its "not" is not a+ # degraded instruction, it is the opposite instruction. Measured over 40+ # real skill bodies with THIS pattern: negation retention rose+ # 73.5% -> 91.9% and modal retention 65.5% -> 96.8%, for 0.2 percentage+ # points of compression (ratio 0.716 -> 0.718) -- these are short, common+ # words, so the model was already keeping most of them and pinning the rest+ # costs almost nothing.+ r"|(?i:\b(?:not|never|none|cannot|can't|don't|doesn't|didn't|won't|shouldn't"+ r"|mustn't|isn't|aren't|avoid|refuse|prohibited|forbidden|disallow|unless"+ r"|except|without|must|should|shall|required|always|only|mandatory)\b)")_KOMPRESS_MUST_KEEP_ENV = "HEADROOM_KOMPRESS_MUST_KEEP"KOMPRESS_BACKEND_ENV = "HEADROOM_KOMPRESS_BACKEND"