headroom

Headroom est une couche de compression de contexte pour les agents IA. Elle compresse tout ce que l'agent lit — sorties d'outils, logs, chunks RAG, fichiers et historique de conversation — avant qu'il n'atteigne le LLM, dans le but de préserver l'intégrité des réponses tout en réduisant l'utilisation de tokens. La compression s'effectue localement ; les invites et le contenu des fichiers ne sont jamais envoyés ailleurs pour être compressés. Fonctionnalités : - Bibliothèque : `compress(messages)` en Python ou TypeScript, utilisable en ligne dans n'importe quelle application. - Proxy : `headroom proxy --port 8787` est un proxy local plug-and-play qui ne nécessite aucun changement de code et fonctionne avec tout client compatible OpenAI. - Wrapper d'agent : `headroom wrap` prend en charge Claude Code, Codex, Grok CLI, Cursor, Aider, Copilot CLI, VS Code Copilot, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands, Mistral Vibe, Oh My Pi, Kimi CLI, ZCode et d'autres ; `headroom unwrap` annule la configuration. - Serveur MCP : expose les outils `headroom_compress`, `headroom_retrieve` et `headroom_stats` pour tout client MCP. - Mémoire inter-agent : un stockage partagé et dédoublonné entre Claude, Codex, Gemini et Grok. - `headroom learn` : analyse les sessions échouées et écrit des corrections dans `CLAUDE.local.md` (par défaut, ignoré par git) ou d'autres fichiers d'instructions d'agent. - Réduction des tokens de sortie : pilotage optionnel de la verbosité côté proxy et routage des efforts pour réduire les tokens écrits par le modèle, pas seulement ceux envoyés. - Compression réversible (CCR) : les originaux sont mis en cache localement et récupérés à la demande via `headroom_retrieve`. Fonctionnement : un ContentRouter détecte le type de contenu et sélectionne un compresseur — SmartCrusher pour JSON, CodeCompressor (conscient de l'AST, supportant Python, JS/TS, Go, Rust, Java, C/C++ et Perl) et Kompress-v2-base (un modèle Hugging Face entraîné sur des traces d'agents) pour le texte. CacheAligner identifie le contenu volatil qui perturberait le préfixe du cache KV du fournisseur sans réécrire les invites ; la compression en zone vivante garde le préfixe figé identique au niveau des octets, permettant aux caches fournisseurs de survivre. Des adaptateurs de framework sont fournis pour les SDK Anthropic/OpenAI, Vercel AI SDK, LiteLLM, LangChain, Agno, Strands, applications ASGI et SharedContext multi-agents. Le README présente des benchmarks hors ligne : 21 % d'économie sur la recherche de code, 57 % sur le débogage d'incidents SRE, 42 % sur l'exploration de codebase et 30 % sur le tri des issues GitHub, avec des charges JSON/logs répétées réduites de 90 %. La latence de compression est inférieure à 1 ms pour 10K tokens. Les évaluations de précision dans le README montrent aucune différence détectable sur GSM8K et TruthfulQA, et 97 % sur SQuAD v2 et BFCL avec une compression de 19 à 32 %. Installation : `uv tool install --python 3.13 "headroom-ai[all]"`, `pip install "headroom-ai[all]"`, `npm install headroom-ai` (SDK TypeScript uniquement, pas d'interface CLI), ou image Docker `ghcr.io/headroomlabs-ai/headroom`. Requiert Python 3.10+. Sous licence Apache 2.0. Des extras granulaires incluent `[proxy]`, `[mcp]`, `[ml]`, `[code]`, `[memory]`, `[vector]`, `[image]` et les adaptateurs de framework.