chopratejas/headroom

Сжимает вывод инструментов, логи, файлы и RAG-чанки до их отправки в LLM. На 20% меньше токенов для coding-агентов, на 60-95% меньше для JSON, те же ответы. Библиотека, прокси, MCP-сервер.

Инструменты⭐ 78 956Pythonпоследний релиз: v0.43.1

Открыть на GitHub ↗Сайт проекта ↗

Что это за инструмент

Headroom — это локальный слой сжатия контекста для AI-агентов, который уменьшает количество токенов в запросах к LLM без потери качества ответов.

Зачем нужен

Инструмент оптимизирует затраты на API, сжимая входные данные (логи, RAG-чанки, код, JSON) перед отправкой модели. Он позволяет использовать те же модели с меньшим бюджетом, сохраняя точность результатов за счет обратимого сжатия.

Что можно реализовать

Снижение стоимости вызовов LLM для агентов, работающих с большими объемами кода или логов
Интеграция сжатия в существующие проекты через библиотеку, прокси или MCP-сервер без изменения основного кода
Автоматическое обучение агентов на ошибках через команду 'headroom learn' для улучшения системных промптов
Управление кросс-агентной памятью с дедупликацией данных между разными LLM-клиентами

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

Сокращение токенов на 60–95% для JSON и на 15–20% для кода при сохранении качества ответов
Поддержка нескольких форматов интеграции: Python/TS библиотека, локальный прокси, обертка для IDE (Cursor, Claude Code) и MCP-сервер
Использование специализированных компрессоров (SmartCrusher, CodeCompressor) и модели Kompress-v2-base
Обратимое сжатие (CCR): оригинальные данные кэшируются локально для восстановления по запросу LLM
Локальная обработка данных, обеспечивающая безопасность и отсутствие утечек в сторонние сервисы

👤 Кому подойдёт: Разработчики AI-агентов, инженеры по машинному обучению и технические лидеры, оптимизирующие расходы на LLM и работающие с большими контекстами

Релизы

v0.43.1patch

🕐 16 ч назад · релиз на GitHub ↗

Исправления в модулях памяти, роутера, прокси и CCR; обновление зависимостей.

Fixed: Исправлена работа очереди в памяти: предотвращено случайное удаление восстановленных записей.
Fixed: Улучшена обработка памяти: корректное чтение ключей отношений и полная перестройка HNSW-индекса при реиндексации.
Fixed: Оптимизирован роутер: тегируемые блоки исключены из лоссного гейта, логирование ONNX-фолбэков переведено в уровень info.
Fixed: Устранены проблемы в прокси: ограничены кэши токенизаторов и бекенов, для ChatGPT-стриминга переключен HTTP/1.1.
Fixed: Исправлено принятие 12-символьных хэшей в headroom_retrieve, устранено неявное обнаружение runtime в ort и нормализация PR-конвертов.

v0.42.0minor

🕐 10 дн назад · релиз на GitHub ↗

Релиз v0.42.0: улучшена экономия токенов, добавлена поддержка переписывания запросов OpenAI Responses через прокси и исправлены баги кэширования.

Added: Прокси теперь позволяет хукам переписывать запросы OpenAI Responses по HTTP и WebSocket.
Added: Добавлены детальные записи об экономии токенов и сохранение токенов в OutcomeSnapshot для каждого запроса.
Added: Шлюз /v1/compress теперь корректно отчитывается об экономии, совпадающей с путем прокси.
Fixed: Исправлено кэширование: ограничена память роутера, сжатие Gemini и нормализация пробелов OpenAI.
Fixed: Обновлены зависимости (rustls, mcp, hf-xet) для устранения уязвимостей и стабилизации работы.

v0.41.0minor

🕐 22 дн назад · релиз на GitHub ↗

Релиз v0.41.0: интеграция Google Antigravity IDE, поддержка OpenCode 2.x, дашборд Rust-прокси и множество исправлений багов.

Added: Добавлена нативная интеграция с Google Antigravity IDE.
Added: Реализована поддержка плагина OpenCode 2.x.
Added: В Rust-прокси добавлены нативная статистика расходов и дашборд.
Added: В ModelRoute добавлено условие max_output_tokens.
Fixed: Исправлены проблемы с кэшированием, аутентификацией и маршрутизацией в Codex, Copilot и Claude Code.

v0.40.0majorbreaking

🕐 1 мес назад · релиз на GitHub ↗

В Headroom v0.40.0 добавлена поддержка Unix-сокетов, сжатие для Live-Agent и учёт CO₂, но изменена логика лицензирования.

Breaking: Чтение лицензии перенесено в переменную HEADROOM_LICENSE, а отчёт об использовании переведён в режим opt-in.
Breaking: Удалён extra-пакет crewai для исключения chromadb из файла зависимостей lockfile.
Added: Добавлена поддержка Unix domain socket (флаг --uds) и заголовка x-headroom-keep-last-turns для обрезки контекста.
Added: В Live-Agent внедрён режим сжатия densify (без потерь и с кэшированием), а в аналитику добавлен бэкенд agy.
Added: На дашборде появилась карточка «CO₂ Saved», а метрики экономии консолидированы в едином центре.
Fixed: Исправлены ошибки в бэкендах: сохранение сбоев Anthropic CCR, маппинг tool_choice и корректная обработка статусов LiteLLM.

v0.39.1patch

🕐 1 мес назад · релиз на GitHub ↗

Исправлена ошибка в прокси, из-за которой лимитер TPM блокировал запросы с большим контекстом.

Fixed: Исправлена ошибка в прокси, из-за которой лимитер TPM в версии 0.39.0 бесконечно отклонял запросы с большим контекстом.

v0.39.0minor

🕐 1 мес назад · релиз на GitHub ↗

v0.39.0: улучшена прозрачность CCR-сжатия, добавлено блокирующее хуковое veto, исправлены баги кэша и пропущенных изображений.

Added: CCR-сжатие теперь описывает, какие именно данные были отброшены, а не только объём экономии.
Added: Добавлен хук protect_messages для жёсткого запрета сжатия отдельных сообщений.
Added: SDK поддерживает переопределение конфигурации в каждом вызове compress().
Fixed: Исправлена потеря блоков изображений в запросах /v1/messages через бэкенд litellm.
Fixed: Устранены проблемы с кэшированием: сохранение схем cache_control, префиксов OpenAI и корректная обработка таймзон.
Fixed: Исправлена ошибка отклонения ping-only SSE от Anthropic и ложных предупреждений о компакции.

v0.38.0minor

🕐 1 мес назад · релиз на GitHub ↗

Релиз v0.38.0: улучшена маршрутизация, сжатие и кэширование, добавлена поддержка OpenAI Responses и бенчмарк Gemini 3.8 Flash.

Added: Beacon v2: новые сигналы обучения маршрутизации и сжатию, транспорт с gzip.
Added: Прокси: поддержка формата OpenAI Responses на этапе turn и условие require_tools.
Added: Dashboard: карточки экономии, отображение затрат за сессию и глобально, оценка TTL кэша.
Added: Router: оптимизация сжатия для машиногенерируемых строк и бенчмарк Gemini 3.8 Flash.
Fixed: Исправления: корректное сжатие cache_control, защита Bash, регистр Bearer-авторизации и доступность интерфейса.

v0.37.0minor

🕐 2 мес назад · релиз на GitHub ↗

Объединение сжатия, защита от SSRF, исправление маршрутизации и багов кэширования в Headroom v0.37.0

Added: Объединено сжатие прокси и сайдкара на едином движке сессий
Added: Добавлен endpoint /v1/compress в режиме сайдкара и ретрансляция /v1/usage
Fixed: Закрыта уязвимость SSRF в Vertex через валидацию региона
Fixed: Исправлена маршрутизация managed Kimi Code и сохранение enterprise-маршрутизации Copilot
Fixed: Исправлено сжатие смешанного вывода сабентов и защита чтения файлов от потерь

v0.36.5patch

🕐 2 мес назад · релиз на GitHub ↗

Исправлено определение авторизации ChatGPT и корректная маршрутизация Claude в проекте.

Fixed: Codex: корректное определение авторизации ChatGPT через id_token claims.
Fixed: Doctor: исправлена маршрутизация Claude в рамках проекта вместо ложного отрицания.

v0.36.4patch

🕐 2 мес назад · релиз на GitHub ↗

Исправление безопасности, стабильности стриминга OpenAI и настройка бюджетов в Serena.

Fixed: Безопасность: добавлена валидация upstream-адресов, передаваемых вызывающей стороной, на всех путях разрешения.
Fixed: Прокси: исправлена передача дополнительных инструментов Codex (additional_tools) в ответе.
Fixed: OpenAI: устранена проблема дедупликации указателей между ходами при стриминге чата.
Fixed: Dashboard: зафиксированы MIME-типы для встроенных статических активов.
Added: Wrap: бюджет простоя предварительного индексирования Serena теперь настраивается.

v0.36.2patch

🕐 2 мес назад · релиз на GitHub ↗

Исправления в Copilot, Kompress и Proxy; обновлены зависимости ai, TypeScript, tiktoken-rs и другие.

Fixed: Copilot: привязка токена minted к передаваемому ID интеграции.
Fixed: Proxy: подсчёт выходных токенов по тексту потока, а не по размеру wire.
Fixed: Kompress: удалённый компрессор теперь принимает ccr_original.
Added: Обновлена библиотека ai с 6.x до 7.0.59 в SDK и документации.
Added: Обновлён TypeScript до 7.0.2 в плагинах openclaw и opencode.
Added: Обновлены зависимости: tiktoken-rs, tokenizers, md-5, ruff и другие.

v0.36.0minor

🕐 2 мес назад · релиз на GitHub ↗

Релиз v0.36.0: детерминированный контроль роутинга, интеграция экономии в дашборд и исправления CCR.

Added: Добавлен детерминированный контроль роутинга во время выполнения.
Added: Прокси теперь позволяет расширениям сообщать об экономии и собственной задержке.
Added: Атрибуция экономии унифицирована в статистике, метриках и дашборде.
Added: Модель для fallback --1m в Claude стала настраиваемой через переменную HEADROOM_1M_MODEL.
Fixed: Исправлено корректное ценообразование и поддержка тиража 1M-контекста для Anthropic.
Fixed: Устранены проблемы с буферизацией, обработкой потоков и безопасностью маркеров в CCR.

v0.35.0minor

🕐 2 мес назад · релиз на GitHub ↗

Релиз v0.35.0: оптимизация производительности, исправления прокси и бекендов, новые функции CLI и улучшения безопасности.

Added: Добавлен CLI-интерфейс для расширений и тарификация TTL кэша промптов.
Added: Внедрена маршрутизация расширений с выбором бэкенда для каждого запроса.
Fixed: Снижена задержка в критическом пути на 27% за счёт мемоизации и оптимизации загрузки.
Fixed: Исправлены утечки памяти, проблемы с потоками ONNX и корректность подсчёта токенов.
Fixed: Улучшена стабильность прокси: исправлен поиск инструментов, корректное завершение работы и биллинг.

v0.34.0minor

🕐 3 мес назад · релиз на GitHub ↗

Релиз 0.34.0: поддержка Claude Code, прозрачный прокси VS Code Copilot, PHP в CodeAwareCompressor и исправления стоимости.

Added: Добавлена поддержка Claude Code в VS Code.
Added: Реализован прозрачный прокси для моделей VS Code Copilot.
Added: В CodeAwareCompressor добавлена поддержка PHP.
Fixed: Исправлена передача полного промпта в LiteLLM для корректного расчёта стоимости.
Fixed: Устранена проблема с ценообразованием современных блоков контента.
Fixed: Обновлены зависимости aiohttp и cryptography для устранения уязвимостей CVE.