# Distil — compression with a quality contract

Distil is a cache-aware, causally-pruned context compressor for LLM agentic
runtimes. It compresses input and output context, certifies that the agent's
decisions are statistically unchanged (non-inferiority test), and is the only
compressor that proves its guarantees rather than assuming them. Zero runtime
dependencies. Four ways to use it, and they do not all reach the same tier:

  - Agent wrap: `distil wrap -- <agent>` for claude, codex, gemini, aider,
    opencode, qwen, goose. Zero config.
  - HTTP proxy for Anthropic, OpenAI (Chat Completions + Responses API), and
    Google Gemini. Point any base_url client at it.
  - Python library: `from distil import compress_messages, expand_handle`.
  - TypeScript library: `compress(messages)` from the `distil-llm` npm package,
    plus `distilMiddleware()` for the Vercel AI SDK's wrapLanguageModel.

Framework hooks (in-process, no network hop): LiteLLM, LangChain, LangGraph,
Agno, Strands. An MCP server exposes distil_compress / distil_expand /
distil_savings to any MCP client.

IMPORTANT for anyone integrating: the reversible DIGEST tier is reached by the
proxy, wrap, and MCP paths. The in-process LIBRARIES are LOSSLESS-tier only, on
purpose — the digest mints restore handles that must share one store with the
proxy, and it is the tier the decision-equivalence certificate measures. The
TypeScript port is held byte-identical to the Python engine by a conformance
suite; where it cannot match Python's bytes it declines rather than emitting
output the certificate does not cover.

Graded on SWE-bench Verified: 42.0% task success
vs 39.2% full context (paired non-inferiority certified; superiority not
significant). 83.2% savings at 0% decision-change rate on a live head-to-head.

## Key sources

README (canonical overview, install, head-to-head table, security):
https://github.com/dshakes/distil/blob/main/README.md

CHANGELOG (per-version feature list):
https://github.com/dshakes/distil/blob/main/CHANGELOG.md

THREAT_MODEL.md (what distil protects against and explicitly does not):
https://github.com/dshakes/distil/blob/main/THREAT_MODEL.md

docs/EVALUATION.md (evaluation methodology, what the numbers mean):
https://dshakes.github.io/distil/EVALUATION.md

benchmarks/README.md (reproducible head-to-head harness):
https://github.com/dshakes/distil/blob/main/benchmarks/README.md

## Site pages

Getting started (install, quickstart, wrap presets, proof ledger):
https://dshakes.github.io/distil/getting-started.html

Architecture (module map, tier model, cert loop, OTel, Proof Ledger):
https://dshakes.github.io/distil/architecture.html

CLI reference (every subcommand, flags, sample output):
https://dshakes.github.io/distil/cli.html

Deploy & Security (topologies, encrypt-at-rest, gateway keys, OTel session id):
https://dshakes.github.io/distil/deploy-security.html

Metrics & Observability (Prometheus /distil/metrics exposition and its admin
gate, OpenTelemetry counters + GenAI spans, what to alert on):
https://dshakes.github.io/distil/metrics.html

FAQ (decision-equivalence, nightly gate, OpenAI/Gemini adapters, troubleshooting):
https://dshakes.github.io/distil/faq.html

Benchmark (certified compression frontier, live head-to-head):
https://dshakes.github.io/distil/benchmark.html

Provider Compaction (pre-registered A/B of Anthropic context editing & OpenAI
server-side compaction: does the provider's own context manipulation change
agent decisions? clearing changed 92.5% of agent decisions at keep=0 and 95-100% at the
shipped keep=3 default, where the failure shifts from stalling to acting on the
wrong facts; OpenAI compaction 12.5-20%):
https://dshakes.github.io/distil/provider-compaction.html

Reproduce the numbers (all CI gates, real-model grading, scorecard):
https://dshakes.github.io/distil/benchmarks.html

Compare (distil vs LLMLingua-2 vs Headroom):
https://dshakes.github.io/distil/compare.html

Techniques (tiers, causal pruning, query-aware salience, learned keep-model):
https://dshakes.github.io/distil/techniques.html

Concepts (DERC certificate, conformal risk control, trajectory certificate):
https://dshakes.github.io/distil/concepts.html

Library API (embed distil in your own agent — Python and TypeScript, the tier
boundary, and why the in-process path is lossless-only):
https://dshakes.github.io/distil/library.html

IDE agents (Cursor, Cline, Continue, Windsurf via the proxy; why `wrap` cannot
reach them, and why GitHub Copilot is not supportable at all):
https://github.com/dshakes/distil/blob/main/docs/IDE-AGENTS.md

Enterprise (Helm chart, OIDC + RBAC, audit receipts, and an honest commercial
status: no SOC 2, no SLA, no SAML today):
https://github.com/dshakes/distil/blob/main/docs/ENTERPRISE.md

Security whitepaper (data residency, encrypt-at-rest, supply chain, what is
explicitly out of scope):
https://github.com/dshakes/distil/blob/main/docs/SECURITY-WHITEPAPER.md
