Headroom: сжатие контекста для LLM на 60–95% без потери качества

«Headroom — это моя попытка решить проблему контекстного раздувания правильно: не эвристиками и усечением, а статистическим анализом и обратимым сжатием.» — автор проекта Tejas Chopra

Что это и для кого

Headroom сжимает всё, что читает ваш AI-агент — результаты вызовов инструментов, логи, RAG-чанки, файлы и историю диалога — прежде чем это доходит до LLM. Результат: на 60–95% меньше токенов при сохранении тех же ответов.

Целевая аудитория:

• AI-агенты и команды разработчиков, строящие инструментозависимые пайплайны (Claude Code, Codex, Cursor, Aider)
• ML-инженеры, работающие с RAG и большими JSON-ответами внешних API
• SRE/DevOps, отлаживающие инциденты через LLM с тысячами строк логов
• Стартапы и продукты, где стоимость токенов напрямую влияет на unit-экономику

AI-агенты и инструментозависимые приложения генерируют огромные контексты: результаты инструментов с тысячами строк поиска, записи логов, ответы API. Длинные истории диалогов упираются в лимиты токенов. Системные промпты с динамическими датами ломают кэширование провайдеров.

Как это работает

90% данных в выводе инструмента — это просто схемные «леса». LLM не нужно видеть status: active, повторённое тысячу раз. Ему нужны аномалии.

graph LR
    A[Приложение / Агент] --> B[Headroom Layer]
    B --> C{Content Router}
    C -->|JSON / массивы| D[SmartCrusher]
    C -->|Код Python/JS/Go| E[CodeCompressor]
    C -->|Текст / логи| F[Kompress-base]
    C -->|История диалога| G[RollingWindow]
    D --> H[CacheAligner]
    E --> H
    F --> H
    G --> H
    H --> I[LLM Provider]
    I -->|CCR retrieve| B

Алгоритмы сжатия (6 трансформов)

Трансформы выполняют всю работу: CacheAligner, ContentRouter, SmartCrusher, CodeCompressor, Kompress-base, IntelligentContext / RollingWindow.

SmartCrusher — ключевой алгоритм для JSON:

SmartCrusher запускает статистический анализ перед обработкой данных. Если каждый элемент массива имеет "type": "file", он не повторяет это 2 000 раз — он извлекает константы один раз.

Вычисляется стандартное отклонение числовых полей. Сохраняются выбросы — значения, отклоняющиеся более чем на 2σ от среднего. Именно они, как правило, имеют значение.

Жёсткое правило: никогда не удалять строки, похожие на стек-трейсы, сообщения об ошибках или сбоях. Ошибки священны.

CodeCompressor — AST-aware компрессор для Python, JS, Go, Rust, Java, C++.

Kompress-base — собственная модель на HuggingFace, обученная на агентных трассах.

CCR (обратимое сжатие) — хранит оригиналы локально; LLM вызывает headroom_retrieve, если ему нужны исходные данные.

Ключевые возможности

Три режима подключения

Library — compress(messages) в Python или TypeScript, встроенный в любое приложение. Proxy — headroom proxy --port 8787, нулевые изменения кода, любой язык. Agent wrap — headroom wrap claude|codex|cursor|aider|copilot одной командой. MCP server — headroom_compress, headroom_retrieve, headroom_stats для любого MCP-клиента.

Широкая совместимость с фреймворками

Headroom интегрируется через: compress(messages) для Python и TypeScript-приложений, withHeadroom(new Anthropic()) / withHeadroom(new OpenAI()) для SDK, wrapLanguageModel для Vercel AI SDK, HeadroomCallback() для LiteLLM, HeadroomChatModel для LangChain, ASGI middleware для веб-приложений, SharedContext().put / .get для мультиагентных систем.

Cross-agent memory

Cross-agent memory — общее хранилище с провенансом агента и автоматической дедупликацией. SharedContext — передача сжатого контекста в мультиагентных рабочих процессах.

Работает локально

Headroom работает полностью локально. Никакие данные не покидают вашу машину (кроме отправки к OpenAI/Anthropic как обычно).

Пример использования

Быстрый старт

# Установка
pip install "headroom-ai[all]"  # Python
npm install headroom-ai         # Node / TypeScript

# Режим proxy (нулевые изменения кода)
headroom proxy --port 8787

# Перенаправить Claude Code
ANTHROPIC_BASE_URL=http://localhost:8787 claude

# Посмотреть статистику сжатия
headroom stats

Использование как библиотека (Python)

from headroom import compress

# Сжать сообщения перед отправкой в LLM
compressed = compress(messages, model="gpt-4o")

# LangChain интеграция
from headroom.integrations import HeadroomChatModel
from langchain_openai import ChatOpenAI

llm = HeadroomChatModel(ChatOpenAI(model="gpt-4o"))
response = llm.invoke("Найди баг в логах")

Мониторинг сжатия

summary = client.get_summary()
print(f"Сохранено токенов: {summary['total_tokens_saved']}")
print(f"Среднее сжатие:   {summary['avg_compression_ratio']:.1%}")
print(f"Экономия ($):     ${summary['total_cost_saved_usd']:.2f}")

Реальные результаты сжатия

Характеристики Headroom

Бенчмарки на реальных нагрузках

Результаты на реальных задачах:

Живой пример: 10 144 → 1 260 токенов — тот же критический FATAL найден.

Тарифы и цены

Headroom полностью бесплатен и открыт. Лицензия Apache-2.0. Никаких платных планов, SaaS-подписок или rate limits нет — инструмент запускается локально в вашей инфраструктуре.

Экономия формируется исключительно за счёт снижения токенов у провайдеров (OpenAI, Anthropic и др.). По заявлению авторов, можно сократить затраты на LLM на 50–90% без потери точности.

Плюсы и минусы

Сравнение с альтернативами

Вердикт

Рейтинг: 8.5 / 10

Headroom закрывает реальную инженерную проблему: для агента усечение контекста опасно. Если обрезать середину лог-файла, можно потерять единственную строку ошибки, объясняющую сбой. Если обрезать список файлов, можно потерять именно тот конфиг, который запросил пользователь.

Кому подойдёт:

• Разработчикам AI-агентов (Claude Code, Codex, Cursor) — Headroom ставится одной командой и сразу даёт экономию без изменения кода
• ML-командам с RAG-пайплайнами — SmartCrusher и Kompress-base дают 70–92% сжатия на JSON и текстовых чанках
• SRE/DevOps, работающим с лог-анализом через LLM — экономия на инцидентной отладке составляет 90%+
• Стартапам с ограниченным бюджетом на API — инструмент бесплатный, эффект ощутим сразу

Кому не подойдёт:

• Командам, которым нужна enterprise-поддержка и SLA
• Проектам на Python < 3.10
• Кейсам с короткими промптами (< 1 000 токенов) — накладные расходы на сжатие не окупятся

Следующие шаги для читателя:

1. Запустите pip install "headroom-ai[proxy]" && headroom proxy --port 8787 — это займёт 30 секунд
2. Добавьте ANTHROPIC_BASE_URL=http://localhost:8787 в ваш агент и запустите headroom stats после первой сессии
3. Если вы работаете с JSON-ответами API — изучите SmartCrusher отдельно, его можно использовать как библиотеку без прокси
4. Для мультиагентных систем — посмотрите документацию по SharedContext и CCR-сжатию