Distil

Un conector MCP de compresión de prompts sin servidor que comprime prompts rápidamente y devuelve métricas estilo Distil — tokens, coste, latencia, carga de cómputo, energía y carbono — donde cada número es medido o una estimación claramente etiquetada. Consulta SPEC.md para el diseño completo.

Construido en torno a la capa de Prompt Intelligence + token/coste/cómputo/energía/carbono del whitepaper original (la parte construible — no se requiere hardware GPU).

Destacados

• Extensión de navegador: comprime lo que escribes directamente en claude.ai, chatgpt.com y gemini.google.com — no se necesita clave API, funciona dentro de tu sesión de chat normal con sesión iniciada. Consulta extension/README.md.

• Puerta de enlace LLM: proxy de sustitución para OpenAI/Anthropic/Gemini — apunta tu base_url a Distil y cada solicitud se comprime (opcionalmente gobernada) antes de llegar al proveedor real, incluido el streaming. Ver más abajo.

• Rápido y sin servidor: la compresión heurística predeterminada es Python puro (~3 ms, sin modelo, sin clave API). Modo opcional gpt-4o-mini para mayor calidad.

• Conector MCP: expone 5 herramientas + un recurso de métricas sobre HTTP transmisible.

• Métricas Distil: token/coste/latencia (medidos) + energía/carbono/carga de GPU (estimados, etiquetados). La intención de GPU se preserva mediante un modelo de carga de cómputo, no se falsifica.

• Panel en vivo + endpoint público /metrics.

• Honesto por diseño: cada estimación marcada como estimated: true; los parámetros de modelos cerrados marcados como params_known: false.

Related MCP server: token-optimization-mcp

Puerta de enlace LLM (proxy de sustitución) — el producto comercial

Apunta tu cliente existente de OpenAI/Anthropic/Gemini a Distil en lugar de al proveedor directamente. Distil comprime el prompt, lo reenvía al proveedor real usando tu propia clave API y transmite la respuesta directamente — misma forma de solicitud/respuesta, por lo que tu código no cambia más allá de la URL base.

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

Cambio de una línea (SDK de OpenAI):

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 (prueba la compresión + una respuesta normal + cabeceras de ahorro):

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 y Gemini funcionan de la misma manera — solo cambian la URL base/ruta y la cabecera de autenticación (tu biblioteca de cliente existente se encarga de eso):

Comportamiento

• Tu clave, tu factura. Distil reenvía la Authorization/x-api-key/key que envías en cada solicitud directamente al proveedor real. Distil nunca la almacena — solo se mantiene un hash unidireccional en memoria, utilizado únicamente como identidad de limitación de velocidad/medición.

• Qué se comprime por defecto: el texto de cada mensaje con rol user (OpenAI/Anthropic) o entrada contents con rol user (Gemini) — cubre tanto "el último mensaje" como cualquier contexto/documento grande pegado en él. Los turnos system/system_instruction y los turnos anteriores assistant/model se dejan intactos. Los esquemas de función/herramienta (bloques tools, tool_calls, tool_result) nunca se tocan.

• A prueba de fallos: si la compresión o la gobernanza falla por cualquier motivo, Distil reenvía tu solicitud original sin comprimir en lugar de romper la llamada.

• Streaming: "stream": true se comprime una vez al inicio, luego la respuesta SSE del proveedor se retransmite fragmento a fragmento, sin almacenamiento en búfer (verificado localmente contra una fuente de prueba lenta — los fragmentos llegan al ritmo del propio proveedor, no en lotes).

• Modos de gobernanza mediante x-distil-govern: off (por defecto log) nunca bloquea; log ejecuta comprobaciones de clasificación/PII/inyección/modernización y registra violaciones pero aún reenvía la solicitud; enforce devuelve un error 4xx con forma de proveedor en lugar de reenviar cuando el veredicto es block.

Cabeceras de configuración (todas opcionales)

Notas de honestidad

• La compresión es solo heurística en la puerta de enlace (sin llamada LLM por solicitud para comprimir — eso duplicaría tu latencia y coste). Puede leerse un poco entrecortada; sube x-distil-ratio (por ejemplo, 0.7) si la calidad de las respuestas se degrada en tus prompts, y prueba antes de confiar en ella en producción.

• Verificado contra las APIs de los proveedores en vivo, no adivinado: las formas de solicitud/respuesta/error/SSE de OpenAI y Anthropic se confirmaron enviando solicitudes reales a api.openai.com y api.anthropic.com (con una clave inválida, para observar el sobre de error real) e inspeccionando la respuesta byte a byte. La forma de solicitud/respuesta/error de generateContent de Gemini se verificó de la misma manera; su marco de streaming (:streamGenerateContent?alt=sse) es el modo SSE documentado en los ejemplos REST de Google, pero no se verificó en vivo con una clave válida de Gemini — prueba esta ruta antes de depender de ella.

• Los campos usage/recuento de tokens dentro del cuerpo de respuesta del propio proveedor son los números reales y autoritativos del proveedor (Distil no los toca). Las cabeceras x-distil-* son el propio recuento de Distil de lo que comprimió.

Inicio rápido (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)

Herramientas MCP

Recurso: metrics://summary.

Cada resultado de compress_prompt también lleva tramos de traza distribuida (§2.2) — tiempos de sub-pasos medidos (route, cache_lookup, compress, token_metrics, estimates).

Caché semántica (§8.2) y enrutamiento multi-modelo (§8.4)

• Caché — de dos niveles, apta para serverless: exacta (hash normalizado) + similitud (coseno léxico, DISTIL_CACHE_THRESHOLD, por defecto 0.92) para que prompts casi idénticos reutilicen una compresión previa. Con espacio de nombres por (ratio, calidad, modelo). Por instancia activa. La tasa de acierto se muestra en el panel.

• Enrutamiento — route_prompt / target_model="auto" puntúa la complejidad del prompt (verbos de razonamiento, código, estructura, longitud) y elige un modelo pequeño vs grande, con estimaciones de coste por modelo para que la elección sea transparente.

Flujo de gobernanza

Más allá del veredicto permitir/avisar/bloquear de govern, Distil admite:

• Política de modelo — DISTIL_MODEL_POLICY_MODE (denylist por defecto | allowlist)

  • DISTIL_DENIED_MODELS / DISTIL_ALLOWED_MODELS. Comprobado en la puerta de enlace (model en el cuerpo de la solicitud → 403 model_not_allowed) y en process_prompt.

• Redactar / poner en cuarentena / requerir aprobación — process_prompt(..., enforcement=) es "block" (por defecto), "redact" (enmascarar PII/secretos y continuar), "quarantine" (retener para revisión de seguridad) o "approval" (retener pendiente de aprobación). Cuarentena/aprobación devuelven un id de revisión inmediatamente — nada se comprime hasta que resolve_review lo aprueba o rechaza. La puerta de enlace LLM en vivo solo admite block/redact (cabecera x-distil-enforcement) — una llamada proxy síncrona no tiene forma de pausar para un humano, por lo que cuarentena/aprobación son solo /process + MCP.

• Flujo de excepciones — grant_exception(scope, value, tenant?, ttl_hours?, reason?) concede una anulación limitada y con caducidad de un bloqueo de paquete o modelo en lugar de deshabilitar toda la política. Comprobado automáticamente por check_packages / check_model_policy.

• Escaneo de licencias — scan_licenses(text) clasifica paquetes referenciados (permisiva / copyleft_débil / copyleft / desconocida) contra un pequeño registro offline; un acierto copyleft eleva la gobernanza a warn (una marca de revisión legal, no un bloqueo duro). Los paquetes desconocidos se marcan, no se adivinan.

• Registro de auditoría — cada llamada a govern (incluida la de permitir) escribe una entrada de grado evidencial — id de decisión, tenant, veredicto, razones, un hash del prompt * vista previa de 60 caracteres (nunca el contenido completo del prompt) — separado del registro de violaciones para que el volumen de auditoría no contamine /metrics. export_audit_log(fmt="csv") para entregar a un auditor.

• Alertas — DISTIL_ALERT_WEBHOOK_URL (+ DISTIL_ALERT_MIN_SEVERITY, por defecto high) dispara un webhook en un bloqueo de gobernanza o en un envío de cuarentena/aprobación. Payload de doble forma: un campo text compatible con Slack más un distil_event estructurado para automatización de PagerDuty/Jira o una ingesta genérica de tickets. A prueba de fallos — un webhook roto nunca afecta a la solicitud que lo disparó.

• Enrutamiento entre proveedores — route_provider_prompt(text) (frente a la recomendación solo de nivel de route_prompt) elige un proveedor + modelo real: un prompt con PII/secretos detectados se restringe a DISTIL_TRUSTED_PROVIDERS (por defecto local) cuando hay uno configurado; los candidatos se ordenan por salud reciente (core.availability, alimentada por tráfico real de la puerta de enlace) y luego por coste entre todos los proveedores con clave configurada, no solo los niveles pequeño/grande de OpenAI.

Los endpoints de administración (/audit, /review-queue/*, /exceptions/*, /alerts/test) están protegidos igual que el resto de la API — establece DISTIL_ADMIN_KEY para un requisito dedicado de x-admin-key; Distil no tiene separación de roles más allá de eso por ahora, así que sin ella cualquier clave Distil válida puede llamarlos.

Despliegue (serverless, Vercel)

1. Sube a GitHub, importa en Vercel (Python / Fluid Compute — auto-detectado).

2. Establece variables de entorno: CONNECTOR_API_KEY (protege /mcp), opcional OPENAI_API_KEY (modo calidad), opcional UPSTASH_REDIS_REST_URL + _TOKEN (métricas persistentes; se usa un archivo JSON local en caso contrario).

3. Añade a Claude mediante la configuración del conector → https://<app>.vercel.app/mcp.

Panel de métricas: https://<app>.vercel.app/.

Referencia de métricas

Diseño

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)

Reutilizado del Agente de Compresión de Prompts

conteo de tiktoken, la lista de rellenos + lógica de análisis, el patrón de dataclass de métricas y la conexión con OpenAI (para la ruta LLM opcional).