Distil

Ein serverloser Prompt-Komprimierungs-MCP-Connector, der Prompts schnell komprimiert und Distil-Metriken zurückgibt — Tokens, Kosten, Latenz, Rechenlast, Energie und Kohlenstoff — wobei jede Zahl entweder gemessen oder eine klar gekennzeichnete Schätzung ist. Siehe SPEC.md für das vollständige Design.

Aufgebaut um die Prompt Intelligence- und Token/Kosten/Rechen-/Energie/Kohlenstoff-Schicht des Quell-Whitepapers (der umsetzbare Teil — keine GPU-Hardware erforderlich).

Highlights

• Browser-Erweiterung: komprimiert, was Sie direkt in claude.ai, chatgpt.com und gemini.google.com eingeben — kein API-Schlüssel erforderlich, funktioniert in Ihrer normalen angemeldeten Chat-Sitzung. Siehe extension/README.md.

• LLM-Gateway: Drop-in-Proxy für OpenAI/Anthropic/Gemini — richten Sie Ihre base_url auf Distil und jede Anfrage wird komprimiert (optional gesteuert), bevor sie den echten Anbieter erreicht, einschließlich Streaming. Siehe unten.

• Schnell + serverlos: Die standardmäßige heuristische Komprimierung ist reines Python (~3 ms, kein Modell, kein API-Schlüssel). Optionaler gpt-4o-mini-Modus für höhere Qualität.

• MCP-Connector: stellt 5 Tools + eine Metriken-Ressource über streambares HTTP bereit.

• Distil-Metriken: Token/Kosten/Latenz (gemessen) + Energie/Kohlenstoff/GPU-Last (geschätzt, gekennzeichnet). GPU-Absicht wird über ein Rechenlastmodell bewahrt, nicht vorgetäuscht.

• Live-Dashboard + öffentlicher /metrics-Endpunkt.

• Ehrlich von Natur aus: Jede Schätzung wird mit estimated: true gekennzeichnet; Parameter geschlossener Modelle mit params_known: false.

Related MCP server: token-optimization-mcp

LLM Gateway (drop-in proxy) — the business product

Richten Sie Ihren bestehenden OpenAI/Anthropic/Gemini-Client anstelle des Anbieters direkt auf Distil. Distil komprimiert den Prompt, leitet ihn mit Ihrem eigenen API-Schlüssel an den echten Anbieter weiter und streamt die Antwort direkt zurück — gleiche Anfrage-/Antwortstruktur, sodass sich Ihr Code außer der Basis-URL nicht ändert.

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

Einzeilige Änderung (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 (beweist Komprimierung + eine normale Antwort + Spar-Header):

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 und Gemini funktionieren auf die gleiche Weise — nur die Basis-URL/der Pfad und der Auth-Header ändern sich (Ihre bestehende Client-Bibliothek übernimmt das):

Behavior

• Ihr Schlüssel, Ihre Rechnung. Distil leitet die Authorization/x-api-key/key, die Sie bei jeder Anfrage senden, direkt an den echten Anbieter weiter. Distil speichert sie nie — nur ein Einweg-Hash wird im Speicher gehalten, der ausschließlich als Rate-Limit-/Mess-Identität dient.

• Was standardmäßig komprimiert wird: der Text jeder Nachricht mit der Rolle user (OpenAI/Anthropic) oder jedes contents-Eintrags mit der Rolle user (Gemini) — deckt sowohl „die neueste Nachricht" als auch große Kontexte/Dokumente ab, die darin eingefügt wurden. system/system_instruction und frühere assistant/model-Runden bleiben unberührt. Funktions-/Tool-Schemata (tools, tool_calls, tool_result-Blöcke) werden nie angefasst.

• Fail-safe: Wenn Komprimierung oder Governance aus irgendeinem Grund einen Fehler wirft, leitet Distil Ihre ursprüngliche, unkomprimierte Anfrage weiter, anstatt den Aufruf zu unterbrechen.

• Streaming: "stream": true wird einmal im Voraus komprimiert, dann wird die SSE-Antwort des Anbieters chunk-für-chunk ungepuffert zurückgeleitet (lokal gegen eine langsame Testquelle verifiziert — Chunks kommen im eigenen Rhythmus des Anbieters an, nicht gebündelt).

• Governance-Modi über x-distil-govern: off (Standard log) blockiert nie; log führt Klassifizierungs-/PII-/Injektions-/Moderationsprüfungen durch und protokolliert Verstöße, leitet die Anfrage aber trotzdem weiter; enforce gibt einen anbieterförmigen 4xx-Fehler zurück, anstatt weiterzuleiten, wenn das Urteil block ist.

Config headers (all optional)

Honesty notes

• Die Komprimierung ist im Gateway nur heuristisch (kein LLM-Aufruf pro Anfrage zum Komprimieren — das würde Ihre Latenz und Kosten verdoppeln). Sie kann etwas abgehackt wirken; erhöhen Sie x-distil-ratio (z. B. 0.7), wenn die Antwortqualität bei Ihren Prompts nachlässt, und testen Sie, bevor Sie sich in Produktion darauf verlassen.

• Gegen die Live-Provider-APIs verifiziert, nicht geraten: Die OpenAI- und Anthropic-Anfrage-/Antwort-/Fehler-/SSE-Strukturen wurden bestätigt, indem echte Anfragen an api.openai.com und api.anthropic.com gesendet wurden (mit einem ungültigen Schlüssel, um die echte Fehlerhülle zu beobachten) und die Antwort Byte für Byte untersucht wurde. Die generateContent-Anfrage-/Antwort-/Fehlerstruktur von Gemini wurde auf die gleiche Weise verifiziert; sein Streaming-Framing (:streamGenerateContent?alt=sse) ist der in Googles REST-Beispielen dokumentierte SSE-Modus, wurde aber nicht live mit einem gültigen Gemini-Schlüssel verifiziert — testen Sie diesen Pfad, bevor Sie sich darauf verlassen.

• Die usage/Token-Anzahl-Felder im Antwortkörper des Anbieters sind die echten, maßgeblichen Zahlen des Anbieters (Distil berührt sie nicht). Die x-distil-*-Header sind Distils eigene Zählung dessen, was es komprimiert hat.

Quick start (local)

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 tools

Ressource: metrics://summary.

Jedes compress_prompt-Ergebnis trägt außerdem Distributed-Trace-Spans (§2.2) – gemessene Teilschritt-Zeiten (route, cache_lookup, compress, token_metrics, estimates).

Semantisches Caching (§8.2) & Multi-Modell-Routing (§8.4)

• Cache – zweistufig, serverless-freundlich: exakt (normalisierter Hash) + Ähnlichkeit (lexikalisch-kosinus, DISTIL_CACHE_THRESHOLD, Standard 0.92), sodass nahezu identische Prompts eine frühere Komprimierung wiederverwenden. Namensraum-basiert nach (ratio, quality, model). Pro warmem Instance. Die Trefferquote wird im Dashboard angezeigt.

• Routing – route_prompt / target_model="auto" bewertet die Prompt-Komplexität (Denkverben, Code, Struktur, Länge) und wählt ein kleines vs. großes Modell, mit Kostenprognosen pro Modell, damit die Wahl transparent ist.

Governance-Workflow

Über das Erlauben-/Warnen-/Blockieren-Urteil von govern hinaus unterstützt Distil:

• Modellrichtlinie – DISTIL_MODEL_POLICY_MODE (denylist Standard | allowlist)

  • DISTIL_DENIED_MODELS / DISTIL_ALLOWED_MODELS. Wird am Gateway geprüft (model im Request-Body → 403 model_not_allowed) und in process_prompt.

• Redigieren / Quarantäne / Genehmigung erforderlich – process_prompt(..., enforcement=) ist "block" (Standard), "redact" (PII/Geheimnisse maskieren und fortfahren), "quarantine" (für Sicherheitsprüfung zurückhalten) oder "approval" (bis zur Freigabe zurückhalten). Quarantäne/Genehmigung geben sofort eine Review-ID zurück – nichts wird komprimiert, bis resolve_review es genehmigt oder ablehnt. Das Live-LLM-Gateway unterstützt nur block/redact (x-distil-enforcement-Header) – ein synchroner Proxy-Aufruf kann nicht auf einen Menschen warten, daher sind Quarantäne/ Genehmigung nur über /process + MCP verfügbar.

• Ausnahmeworkflow – grant_exception(scope, value, tenant?, ttl_hours?, reason?) gewährt eine enge, ablaufende Überschreibung einer Paket- oder Modellsperre, anstatt die gesamte Richtlinie zu deaktivieren. Wird automatisch von check_packages / check_model_policy geprüft.

• Lizenzscan – scan_licenses(text) klassifiziert referenzierte Pakete (permissiv / weak_copyleft / copyleft / unbekannt) gegen ein kleines Offline- Register; ein Copyleft-Treffer stuft Governance auf warn hoch (ein Rechtsprüfungs-Flag, keine harte Sperre). Unbekannte Pakete werden gekennzeichnet, nicht geraten.

• Prüfpfad – jeder govern-Aufruf (auch erlaubte) schreibt einen beweistauglichen Eintrag – Entscheidungs-ID, Mandant, Urteil, Gründe, einen Prompt-Hash

  • 60-Zeichen-Vorschau (niemals den vollständigen Prompt-Inhalt) – getrennt vom Verstoßprotokoll, damit das Prüfvolumen /metrics nicht verunreinigt. export_audit_log(fmt="csv") zur Übergabe an einen Prüfer.

• Alarme – DISTIL_ALERT_WEBHOOK_URL (+ DISTIL_ALERT_MIN_SEVERITY, Standard high) löst einen Webhook bei einem Governance-Block oder einer Quarantäne-/ Genehmigungseinreichung aus. Doppelt geformte Nutzlast: ein Slack-kompatibles text-Feld plus ein strukturiertes distil_event für PagerDuty/Jira-Automatisierung oder einen generischen Ticketing-Ingest. Ausfallsicher – ein defekter Webhook beeinträchtigt niemals die Anfrage, die ihn ausgelöst hat.

• Anbieterübergreifendes Routing – route_provider_prompt(text) (im Gegensatz zur Nur-Tier-Empfehlung von route_prompt) wählt einen echten Anbieter + ein Modell: ein Prompt mit erkannten PII/Geheimnissen ist auf DISTIL_TRUSTED_PROVIDERS beschränkt (Standard local), wenn einer konfiguriert ist; Kandidaten werden nach aktueller Gesundheit (core.availability, gespeist aus echtem Gateway-Verkehr) und dann nach Kosten über jeden Anbieter mit konfiguriertem Schlüssel bewertet, nicht nur über die kleinen/großen Tiers von OpenAI.

Admin-Endpunkte (/audit, /review-queue/*, /exceptions/*, /alerts/test) sind genauso abgesichert wie der Rest der API – setzen Sie DISTIL_ADMIN_KEY für eine dedizierte x-admin-key-Anforderung; Distil hat darüber hinaus keine Rollentrennung, daher kann ohne diesen Schlüssel jeder gültige Distil-Schlüssel sie aufrufen.

Bereitstellung (serverless, Vercel)

1. Nach GitHub pushen, in Vercel importieren (Python / Fluid Compute – automatisch erkannt).

2. Umgebungsvariablen setzen: CONNECTOR_API_KEY (sichert /mcp), optional OPENAI_API_KEY (Qualitätsmodus), optional UPSTASH_REDIS_REST_URL + _TOKEN (persistente Metriken; andernfalls wird eine lokale JSON-Datei verwendet).

3. Zu Claude über die Connector-Einstellungen hinzufügen → https://<app>.vercel.app/mcp.

Metrik-Dashboard: https://<app>.vercel.app/.

Metrik-Referenz

Layout

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)

Wiederverwendet aus dem Prompt-Compression-Agent

tiktoken-Zählung, die Füllwortliste + Analyselogik, das Metrik-Dataclass- Muster und die OpenAI-Verdrahtung (für den optionalen LLM-Pfad).