Distil

서버리스 프롬프트 압축 MCP 커넥터로, 프롬프트를 빠르게 압축하고 Distil 스타일 메트릭(토큰, 비용, 지연 시간, 컴퓨트 부하, 에너지, 탄소)을 반환합니다. 모든 숫자는 측정값이거나 명확히 라벨링된 추정치입니다. 전체 설계는 SPEC.md를 참조하세요.

원본 백서의 Prompt Intelligence + 토큰/비용/컴퓨트/에너지/탄소 레이어를 기반으로 구축되었습니다 (구현 가능한 부분 — GPU 하드웨어 불필요).

주요 기능

• 브라우저 확장 프로그램: claude.ai, chatgpt.com, gemini.google.com에 직접 입력하는 내용을 압축합니다 — API 키가 필요 없으며, 일반 로그인 채팅 세션 내에서 작동합니다. extension/README.md 참조.

• LLM 게이트웨이: OpenAI/Anthropic/Gemini용 드롭인 프록시 — base_url을 Distil로 지정하면 모든 요청이 실제 제공업체에 도달하기 전에 압축(선택적으로 거버넌스 적용)되며, 스트리밍도 포함됩니다. 아래 참조.

• 빠르고 서버리스: 기본 휴리스틱 압축은 순수 Python입니다(~3ms, 모델 불필요, API 키 불필요). 더 높은 품질을 위한 선택적 gpt-4o-mini 모드.

• MCP 커넥터: 스트리밍 가능한 HTTP를 통해 5개의 도구 + 메트릭 리소스를 노출합니다.

• Distil 메트릭: 토큰/비용/지연 시간(측정값) + 에너지/탄소/GPU 부하(추정치, 라벨링됨). GPU 의도는 컴퓨트 부하 모델을 통해 보존되며, 가짜로 처리되지 않습니다.

• 라이브 대시보드 + 공개 /metrics 엔드포인트.

• 설계상 정직함: 모든 추정치는 estimated: true로 표시되고, 폐쇄형 모델 매개변수는 params_known: false로 표시됩니다.

Related MCP server: token-optimization-mcp

LLM 게이트웨이(드롭인 프록시) — 비즈니스 제품

기존 OpenAI/Anthropic/Gemini 클라이언트를 제공업체에 직접 연결하는 대신 Distil로 지정하세요. Distil이 프롬프트를 압축하고, 사용자의 API 키를 사용하여 실제 제공업체로 전달한 다음, 답변을 그대로 스트리밍합니다 — 요청/응답 형태가 동일하므로 base 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도 동일한 방식으로 작동합니다 — base URL/경로와 인증 헤더만 변경됩니다(기존 클라이언트 라이브러리가 처리합니다):

동작 방식

• 사용자의 키, 사용자의 청구서. Distil은 모든 요청에 포함된 Authorization/x-api-key/key를 실제 제공업체에 그대로 전달합니다. Distil은 이를 저장하지 않으며, 메모리에 일방향 해시만 유지하여 요율 제한/계량 식별에만 사용합니다.

• 기본적으로 압축되는 대상: 모든 user 역할 메시지(OpenAI/Anthropic) 또는 user 역할 contents 항목(Gemini)의 텍스트 — "최신 메시지"와 여기에 붙여넣은 대용량 컨텍스트/문서를 모두 포함합니다. system/system_instruction 및 이전 assistant/model 턴은 그대로 둡니다. 함수/도구 스키마(tools, tool_calls, tool_result 블록)는 절대 건드리지 않습니다.

• 안전 장치: 압축이나 거버넌스가 어떤 이유로든 예외를 발생시키면, Distil은 호출을 중단하는 대신 원본의 압축되지 않은 요청을 전달합니다.

• 스트리밍: "stream": true는 먼저 한 번 압축된 후, 제공업체의 SSE 응답이 청크 단위로 버퍼링 없이 그대로 중계됩니다(느린 테스트 소스에 대해 로컬에서 검증됨 — 청크는 제공업체 자체의 주기로 도착하며, 배치되지 않음).

• 거버넌스 모드는 x-distil-govern을 통해 설정: off(기본값 log)는 절대 차단하지 않음; log는 분류/PII/주입/모더레이션 검사를 실행하고 위반을 기록하지만 요청은 계속 전달; enforce는 판정이 block일 때 전달 대신 제공업체 형태의 4xx 오류를 반환합니다.

구성 헤더(모두 선택 사항)

정직성 참고 사항

• 압축은 게이트웨이에서 휴리스틱 전용입니다(압축을 위한 요청별 LLM 호출 없음 — 지연 시간과 비용이 두 배가 되기 때문). 문장이 약간 어색하게 읽힐 수 있습니다. 프롬프트에서 답변 품질이 저하되면 x-distil-ratio를 높이고(예: 0.7), 프로덕션에서 의존하기 전에 테스트하세요.

• 라이브 제공업체 API로 검증되었지 추측이 아닙니다: OpenAI와 Anthropic의 요청/응답/오류/SSE 형태는 api.openai.com과 api.anthropic.com에 실제 요청을 보내(잘못된 키로, 실제 오류 봉투를 관찰하기 위해) 응답을 바이트 단위로 검사하여 확인했습니다. Gemini의 generateContent 요청/응답/오류 형태도 동일한 방식으로 검증했으며, 스트리밍 프레이밍(:streamGenerateContent?alt=sse)은 Google REST 예제에 문서화된 SSE 모드이지만 유효한 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)

• 캐시 — 2계층, 서버리스 친화적: 정확(정규화 해시) + 유사도 (어휘-코사인, DISTIL_CACHE_THRESHOLD, 기본값 0.92)로 거의 동일한 프롬프트가 이전 압축 결과를 재사용합니다. (ratio, quality, model)별로 네임스페이스가 지정됩니다. 웜 인스턴스별로 적용됩니다. 적중률은 대시보드에 표시됩니다.

• 라우팅 — route_prompt / target_model="auto"는 프롬프트 복잡도 (추론 동사, 코드, 구조, 길이)를 점수화하여 소형 vs 대형 모델을 선택하며, 모델별 비용 추정치를 제공하여 선택이 투명하게 이루어집니다.

거버넌스 워크플로

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"(승인 대기)입니다. 격리/승인은 즉시 검토 ID를 반환합니다 — 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 호출(허용 포함)은 증거 등급 항목을 기록합니다 — 결정 ID, 테넌트, 판정, 사유, 프롬프트 해시

  • 60자 미리보기(전체 프롬프트 내용은 절대 아님) — 위반 로그와 분리되어 감사 볼륨이 /metrics를 오염시키지 않습니다. export_audit_log(fmt="csv")로 감사인에게 전달할 수 있습니다.

• 알림 — DISTIL_ALERT_WEBHOOK_URL (+ DISTIL_ALERT_MIN_SEVERITY, 기본값 high)은 거버넌스 차단 또는 격리/ 승인 제출 시 웹훅을 발생시킵니다. 이중 형태 페이로드: Slack 호환 text 필드 및 PagerDuty/Jira 자동화 또는 일반 티켓 수집을 위한 구조화된 distil_event. 안전 장치 — 손상된 웹훅은 이를 트리거한 요청에 절대 영향을 미치지 않습니다.

• 교차 공급자 라우팅 — 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 키로 모두 호출할 수 있습니다.

배포 (서버리스, 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)

프롬프트 압축 에이전트에서 재사용된 항목

tiktoken 계산, 필러 목록 + 분석 로직, 메트릭 데이터클래스 패턴, OpenAI 연결 (선택적 LLM 경로용).