Distil

Серверный MCP-коннектор для сжатия промптов, который быстро сжимает промпты и возвращает метрики в стиле Distil — токены, стоимость, задержку, вычислительную нагрузку, энергию и углерод — где каждое число либо измерено, либо является явно помеченной оценкой. Полный дизайн см. в SPEC.md.

Построен вокруг Prompt Intelligence из исходного whitepaper + слоя токенов/стоимости/вычислений/энергии/углерода (реализуемая часть — без GPU-оборудования).

Основные возможности

• Расширение для браузера: сжимает то, что вы вводите прямо в claude.ai, chatgpt.com и gemini.google.com — не требуется API-ключ, работает внутри вашей обычной авторизованной чат-сессии. См. extension/README.md.

• LLM Gateway: прокси-замена для OpenAI/Anthropic/Gemini — укажите base_url на Distil, и каждый запрос будет сжат (при необходимости с управлением) до того, как он достигнет реального провайдера, включая стриминг. См. ниже.

• Быстро и без сервера: эвристическое сжатие по умолчанию — чистый Python (~3 мс, без модели, без API-ключа). Опциональный режим gpt-4o-mini для более высокого качества.

• MCP-коннектор: предоставляет 5 инструментов + ресурс метрик через потоковый HTTP.

• Метрики Distil: токены/стоимость/задержка (измеренные) + энергия/углерод/GPU-нагрузка (оценённые, помеченные). Намерение GPU сохраняется через модель вычислительной нагрузки, а не подделывается.

• Живая панель мониторинга + публичный эндпоинт /metrics.

• Честно по дизайну: каждая оценка помечена estimated: true; параметры закрытых моделей помечены params_known: false.

Related MCP server: token-optimization-mcp

LLM Gateway (прокси-замена) — коммерческий продукт

Укажите ваш существующий клиент OpenAI/Anthropic/Gemini на Distil вместо прямого обращения к провайдеру. Distil сжимает промпт, пересылает его реальному провайдеру с использованием вашего собственного API-ключа и стримит ответ обратно — та же форма запроса/ответа, так что ваш код не меняется, кроме базового URL.

your app → Distil (/v1/...)  →  compress + optional governance  →  real provider  →  same answer back to you

Изменение в одну строку (OpenAI SDK):

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_OWN_OPENAI_KEY",       # unchanged — sent straight through, never stored
    base_url="https://getdistil.vercel.app/v1",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Could you please possibly explain, in a very detailed way, what a REST API is?"}],
)

curl (доказывает сжатие + обычный ответ + заголовки экономии):

curl -i https://getdistil.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Could you please possibly explain, in a very detailed way, what a REST API is?"}]
  }'
# Response body is a normal OpenAI chat.completion object.
# Response headers include:
#   x-distil-original-tokens, x-distil-sent-tokens, x-distil-tokens-saved

Anthropic и Gemini работают так же — меняются только базовый URL/путь и заголовок авторизации (ваша клиентская библиотека справится с этим):

Поведение

• Ваш ключ, ваш счёт. Distil пересылает Authorization/x-api-key/key, которые вы отправляете в каждом запросе, напрямую реальному провайдеру. Distil никогда не хранит его — в памяти сохраняется только односторонний хэш, используемый исключительно как идентификатор для ограничения скорости/учёта.

• Что сжимается по умолчанию: текст каждого сообщения с ролью user (OpenAI/Anthropic) или записи contents с ролью user (Gemini) — охватывает как «последнее сообщение», так и любой большой контекст/документы, вставленные в него. system/system_instruction и предыдущие ходы assistant/model не трогаются. Схемы функций/инструментов (блоки tools, tool_calls, tool_result) никогда не изменяются.

• Отказоустойчивость: если сжатие или управление по любой причине выдаёт ошибку, Distil пересылает ваш исходный несжатый запрос, а не прерывает вызов.

• Стриминг: "stream": true сжимается один раз заранее, затем SSE-ответ провайдера ретранслируется обратно по частям, без буферизации (проверено локально на медленном тестовом источнике — части приходят в собственном темпе провайдера, а не пакетами).

• Режимы управления через x-distil-govern: off (по умолчанию log) никогда не блокирует; log выполняет проверки classify/PII/injection/moderation и записывает нарушения, но всё равно пересылает запрос; enforce возвращает ошибку 4xx в форме провайдера вместо пересылки, когда вердикт — block.

Заголовки конфигурации (все необязательные)

Примечания о честности

• Сжатие в шлюзе — только эвристическое (без LLM-вызова на каждый запрос для сжатия — это удвоило бы задержку и стоимость). Текст может читаться слегка отрывисто; увеличьте x-distil-ratio (например, 0.7), если качество ответов на ваших промптах ухудшается, и протестируйте перед использованием в продакшене.

• Проверено на живых API провайдеров, а не угадано: формы запросов/ответов/ошибок/SSE для OpenAI и Anthropic были подтверждены отправкой реальных запросов на api.openai.com и api.anthropic.com (с недействительным ключом, чтобы наблюдать реальную оболочку ошибки) и побайтовым анализом ответа. Форма запроса/ответа/ошибки generateContent для Gemini была проверена тем же способом; его потоковая структура (:streamGenerateContent?alt=sse) — это режим SSE, описанный в REST-примерах Google, но не проверен вживую с действительным ключом Gemini — протестируйте этот путь, прежде чем полагаться на него.

• Поля usage/количество токенов внутри тела ответа самого провайдера — это реальные авторитетные числа провайдера (Distil их не трогает). Заголовки x-distil-* — это собственный подсчёт Distil того, что он сжал.

Быстрый старт (локально)

pip install -r requirements.txt
python demo.py                    # try the core on a sample
python eval/run_eval.py           # measured eval over sample prompts
pytest tests/                     # test suite
python mcp_server.py              # run the MCP server over stdio
uvicorn api.index:app --port 8000 # run the HTTP server + dashboard
# → open http://localhost:8000/  (dashboard) and /mcp (connector)

Инструменты MCP

Ресурс: metrics://summary.

Каждый результат compress_prompt также содержит спаны распределённой трассировки (§2.2) — измеренные тайминги подэтапов (route, cache_lookup, compress, token_metrics, estimates).

Семантическое кэширование (§8.2) и маршрутизация по нескольким моделям (§8.4)

• Кэш — двухуровневый, подходит для serverless: точный (нормализованный хэш) + по сходству (лексический косинус, DISTIL_CACHE_THRESHOLD, по умолчанию 0.92), чтобы почти идентичные промпты использовали предыдущее сжатие. Пространство имён: (ratio, quality, model). На каждый тёплый инстанс. Доля попаданий отображается на панели управления.

• Маршрутизация — route_prompt / target_model="auto" оценивает сложность промпта (глаголы рассуждения, код, структура, длина) и выбирает малую или большую модель, с оценкой стоимости для каждой модели, чтобы выбор был прозрачным.

Рабочий процесс управления

Помимо вердикта allow/warn/block от govern, Distil поддерживает:

• Политика моделей — DISTIL_MODEL_POLICY_MODE (denylist по умолчанию | allowlist)

  • DISTIL_DENIED_MODELS / DISTIL_ALLOWED_MODELS. Проверяется на шлюзе (model в теле запроса → 403 model_not_allowed) и в process_prompt.

• Редактирование / карантин / требование одобрения — process_prompt(..., enforcement=) может быть "block" (по умолчанию), "redact" (маскировать PII/секреты и продолжить), "quarantine" (удержать для проверки безопасности) или "approval" (удержать до подписания). Карантин/одобрение немедленно возвращают идентификатор проверки — ничего не сжимается, пока resolve_review не одобрит или не отклонит. Живой LLM-шлюз поддерживает только block/redact (заголовок x-distil-enforcement) — синхронный прокси-вызов не может приостановиться для человека, поэтому карантин/ одобрение доступны только через /process и MCP.

• Рабочий процесс исключений — grant_exception(scope, value, tenant?, ttl_hours?, reason?) предоставляет узкое истекающее переопределение блокировки пакета или модели вместо отключения всей политики. Автоматически проверяется check_packages / check_model_policy.

• Сканирование лицензий — scan_licenses(text) классифицирует упомянутые пакеты (permissive / weak_copyleft / copyleft / unknown) по небольшому офлайн-реестру; попадание copyleft повышает уровень управления до warn (флаг для юридической проверки, а не жёсткая блокировка). Неизвестные пакеты помечаются, а не угадываются.

• Журнал аудита — каждый вызов govern (включая allow) записывает запись уровня доказательности — идентификатор решения, тенант, вердикт, причины, хэш промпта

  • превью из 60 символов (никогда полное содержимое промпта) — отдельно от журнала нарушений, чтобы объём аудита не загрязнял /metrics. export_audit_log(fmt="csv") для передачи аудитору.

• Оповещения — DISTIL_ALERT_WEBHOOK_URL (+ DISTIL_ALERT_MIN_SEVERITY, по умолчанию high) отправляет вебхук при блокировке управления или отправке карантина/одобрения. Двухформатная полезная нагрузка: совместимое со Slack поле text плюс структурированное distil_event для автоматизации PagerDuty/Jira или общего приёма тикетов. Отказоустойчивость — сломанный вебхук никогда не влияет на запрос, который его вызвал.

• Маршрутизация между провайдерами — route_provider_prompt(text) (в отличие от рекомендации только по уровням в route_prompt) выбирает реального провайдера + модель: промпт с обнаруженными PII/секретами ограничивается DISTIL_TRUSTED_PROVIDERS (по умолчанию local), если он настроен; кандидаты ранжируются по недавнему состоянию (core.availability, питается реальным трафиком шлюза), затем по стоимости среди всех провайдеров с настроенным ключом, а не только по малым/большим уровням OpenAI.

Админ-эндпоинты (/audit, /review-queue/*, /exceptions/*, /alerts/test) защищены так же, как и остальной API — установите DISTIL_ADMIN_KEY для отдельного требования x-admin-key; в Distil пока нет разделения ролей помимо этого, поэтому без него любой действительный ключ Distil может их вызывать.

Развёртывание (serverless, Vercel)

1. Запушьте в GitHub, импортируйте в Vercel (Python / Fluid Compute — определяется автоматически).

2. Установите переменные окружения: CONNECTOR_API_KEY (защищает /mcp), опционально OPENAI_API_KEY (режим качества), опционально UPSTASH_REDIS_REST_URL + _TOKEN (постоянные метрики; в противном случае используется локальный JSON-файл).

3. Добавьте в Claude через настройки коннектора → https://<app>.vercel.app/mcp.

Панель метрик: https://<app>.vercel.app/.

Справочник по метрикам

Структура

core/                 compression + intelligence + estimates + metrics store
core/gateway.py        LLM Gateway request rewriting (no networking; pure logic)
mcp_server.py          FastMCP tools/resource
api/index.py            serverless ASGI entrypoint (MCP + dashboard + /metrics + auth)
api/gateway_routes.py   LLM Gateway HTTP routes (/v1/chat/completions, /v1/messages, /v1beta/...)
dashboard/             static metrics page
eval/                  measured evaluation
tests/                 unit tests (tests/test_gateway.py covers the gateway)

Переиспользовано из Prompt Compression Agent

подсчёт tiktoken, список слов-паразитов + логика анализа, паттерн dataclass для метрик и интеграция с OpenAI (для опционального пути LLM).