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
README: replace plain text architecture with Mermaid diagrams
chopratejasa80ed157a291
diff --git a/README.md b/README.mdindex d24f59a72..30ff0aa67 100644--- a/README.md+++ b/README.md@@ -122,18 +122,45 @@ Full methodology: [Benchmarks](docs/benchmarks.md) | Run yourself: `python -m he## How It Works+```mermaid+flowchart LR+ App["Your App"] --> H["Headroom"] --> LLM["LLM Provider"]+ LLM --> Resp["Response"]```-Your App → Headroom → LLM Provider- ↓- CacheAligner: stabilizes prefix for KV cache hits- ContentRouter: routes to optimal compressor per content type- → SmartCrusher (JSON) | CodeCompressor (code) | LLMLingua (text)- IntelligentContext: score-based token fitting- CCR: stores originals for retrieval if LLM needs more- Query Echo: re-injects user question for fresh attention after compression++### Inside Headroom++```mermaid+flowchart TB+ subgraph Pipeline["Transform Pipeline"]+ CA["1. CacheAligner\nStabilizes prefix for KV cache"]+ CR["2. ContentRouter\nDetects content type, picks compressor"]+ IC["3. IntelligentContext\nScore-based token fitting"]+ QE["4. Query Echo\nRe-injects user question"]+ CA --> CR --> IC --> QE+ end++ subgraph Compressors["ContentRouter dispatches to"]+ SC["SmartCrusher\nJSON arrays"]+ CC["CodeCompressor\nAST-aware code"]+ LL["LLMLingua\nML-based text"]+ end++ subgraph CCR["CCR: Compress-Cache-Retrieve"]+ Store[("Compressed\nStore")]+ Tool["headroom_retrieve"]+ Tool <--> Store+ end++ CR --> Compressors+ SC -. "stores originals +\nsummary of what's omitted" .-> Store+ QE --> LLM["LLM Provider"]+ LLM -. "retrieves when\nit needs more" .-> Tool```-Headroom never throws data away. It compresses aggressively and retrieves precisely. When it compresses 500 items to 20, it tells the LLM *what was omitted* ("87 passed, 2 failed, 1 error") so the LLM knows when to ask for more.+> Headroom never throws data away. It compresses aggressively and retrieves precisely.+> When it compresses 500 items to 20, it tells the LLM *what was omitted*+> ("87 passed, 2 failed, 1 error") so the LLM knows when to ask for more.### Verified on Real Workloads