headroom

O Headroom atua como uma camada de compressão contextual para agentes de IA. Ele comprime tudo o que um agente lê — incluindo saídas de ferramentas, logs, chunks de RAG, arquivos e histórico de conversas — antes que esses dados alcancem o LLM (Large Language Model). O objetivo é manter a integridade das respostas enquanto reduz significativamente o consumo de tokens. A compressão ocorre localmente; prompts e conteúdos de arquivos não são enviados para outros serviços para compressão. Capacidades: - Biblioteca: função `compress(messages)` em Python ou TypeScript, utilizável inline em qualquer aplicação. - Proxy: `headroom proxy --port 8787` é um proxy local plug-and-play que não exige alterações no código e funciona com qualquer cliente compatível com OpenAI. - Wrapper de Agente: `headroom wrap` suporta 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 e outros; `headroom unwrap` reverte a configuração. - Servidor MCP: expõe as ferramentas `headroom_compress`, `headroom_retrieve` e `headroom_stats` para qualquer cliente MCP. - Memória cross-agent: armazenamento compartilhado e deduplicado entre Claude, Codex, Gemini e Grok. - `headroom learn`: minera sessões falhas e grava correções em `CLAUDE.local.md` (padrão, ignorado pelo git) ou outros arquivos de instrução do agente. - Redução de tokens de saída: roteamento opcional de esforço e direcionamento de verbosidade no lado do proxy para reduzir os tokens gerados pelo modelo, não apenas os enviados. - Compressão reversível (CCR): originais são armazenados em cache localmente e recuperados sob demanda via `headroom_retrieve`. Funcionamento: um ContentRouter detecta o tipo de conteúdo e seleciona um compressor — SmartCrusher para JSON, CodeCompressor (consciente da AST, suportando Python, JS/TS, Go, Rust, Java, C/C++ e Perl) e Kompress-v2-base (um modelo do Hugging Face treinado em traces agênticos) para prosa. O CacheAligner sinaliza conteúdo volátil que poderia invalidar o prefixo KV-cache do provedor sem reescrever prompts; a compressão na zona ativa mantém o prefixo congelado byte a byte idêntico, permitindo que os caches do provedor sobrevivam. Adaptadores de framework estão disponíveis para Anthropic/OpenAI SDKs, Vercel AI SDK, LiteLLM, LangChain, Agno, Strands, aplicativos ASGI e SharedContext multi-agente. O README relata benchmarks offline validados: economia de 21% em busca de código, 57% em depuração de incidentes SRE, 42% em exploração de codebases e 30% em triagem de issues do GitHub, com payloads repetidos de JSON/logs limpando 90%. A latência de compressão é relatada como bem abaixo de um milissegundo para 10K tokens. Avaliações de precisão no README mostram nenhuma diferença detectável no GSM8K e TruthfulQA, e 97% no SQuAD v2 e BFCL com compressão de 19–32%. Instalação: `uv tool install --python 3.13 "headroom-ai[all]"`, `pip install "headroom-ai[all]"`, `npm install headroom-ai` (SDK TypeScript apenas, sem CLI) ou imagem Docker `ghcr.io/headroomlabs-ai/headroom`. Requer Python 3.10+; licenciado sob Apache 2.0. Extras granulares incluem `[proxy]`, `[mcp]`, `[ml]`, `[code]`, `[memory]`, `[vector]`, `[image]` e adaptadores de framework.