Getting Started

Install Distil in seconds, run the corpus gate, and drop compression into your existing agent with one line of code.

Install

Distil has a zero-dependency stdlib-only core and ships as a command-line app (PyPI package distil-llm; the command is distil). Pick the format that fits your workflow — the corpus is bundled in every distribution.

uvx --from distil-llm distil bench

pipx install distil-llm
distil certify

brew install dshakes/tap/distil
distil bench

docker build -t distil .
docker run distil bench

make pyz
python dist/distil.pyz bench

python3 -m venv .venv && source .venv/bin/activate
pip install distil-llm

Billing-grade tokenizer (optional)

The default tokenizer is an offline heuristic — compression ratios are robust, but absolute dollar figures are approximate. To get billing-grade token counts and certify against the live model, install the live extra and export your key:

# with pipx (isolated):
pipx install 'distil-llm[live]'
# or one-off with uvx:  uvx --from 'distil-llm[live]' distil certify --runner anthropic
export ANTHROPIC_API_KEY=sk-ant-…
distil savings --tokenizer anthropic
distil certify --runner anthropic

60-second quickstart

Three commands cover the core workflow. Run them against the bundled multi-domain corpus (no API key required).

1. Benchmark savings across 7 domains

distil bench is the corpus-wide CI gate. It prices four strategies, certifies Distil is non-inferior on every trajectory, and confirms the gate rejects the aggressive lossy strategy. This is the command you run in CI.

$ distil bench
corpus gate — 7 trajectories | model claude-opus-4-8 | tokenizer=heuristic

domain            trajectory               $ saved   distil   aggr  pruned
---------------------------------------------------------------------------
ops/sre           sre-disk-incident          33.1%     PASS   FAIL     615
coding            coding-bugfix              28.7%     PASS   FAIL     736
support           support-refund             32.6%     PASS   FAIL     765
research          research-synthesis         25.7%     PASS   FAIL     809
data-analysis     data-analysis-sql          18.1%     PASS   FAIL     965
devops            devops-rollback            25.0%     PASS   FAIL     857
finance           finance-reconcile          29.1%     PASS   FAIL    1014
---------------------------------------------------------------------------
aggregate: distil cuts $0.14212 -> $0.10402 (26.8% cheaper) losslessly; 5761 tokens prunable.

GATE: PASS — every trajectory certified non-inferior; aggressive rejected on all.

2. Certify a strategy

Run the TOST non-inferiority gate on a single trajectory and strategy. Exits 0 on pass, 1 on fail — plug it into any CI pipeline.

$ distil certify --strategy distil
certifying strategy 'distil' on 'sre-disk-incident' (runner=deterministic)

  turn 0: ok
  turn 1: ok
  turn 2: ok
  turn 3: ok

decision-equivalence match rate: 100.0%
TOST non-inferiority (margin=0.02, alpha=0.05): mean diff=+0.000, p=0.0000

VERDICT: PASS  (certified non-inferior)

3. Discover causally inert blocks

distil prune ablates each context block, replays the trajectory, and identifies what never changed a decision — provably free to drop.

$ distil prune
causal ablation over 'sre-disk-incident' — what is free to drop?

block                  occ   tokens  verdict
doc-0                    4      312  PRUNE (causally inert)
doc-1                    4      303  PRUNE (causally inert)
obs-0                    4      234  keep (changed a decision)
obs-1                    4      198  keep (changed a decision)
system                   4      218  keep (changed a decision)

tokens provably free to drop: 615 across 2 block(s).

Drop-in adoption: wrap(client)

The fastest path to production compression — no changes to your call sites. Wrap your existing Anthropic client once and every subsequent messages.create call is transparently compressed and cache-pinned.

import anthropic
from distil.adapters.anthropic import wrap

# One-line drop-in — no call-site changes needed
client = wrap(anthropic.Anthropic())

# Works exactly like the original client
response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    system="You are a helpful assistant.",
    messages=[{"role": "user", "content": "Analyse this log output…"}],
)

The wrapper applies Tier-0 lossless transforms (JSON minification, run-length collapse) and Tier-1 reversible digests to large tool results. It also pins the stable system prefix for cache-control so repeated calls get the ~10× cache-read discount automatically.

Alternative: provider proxy

Prefer a network-level approach that works with any SDK, framework, or language? See the Adapters page for distil proxy.

What to read next

• Concepts — why decision-equivalence beats byte-equivalence, and why cache misses (not token size) dominate cost.
• Techniques — deep-dive into every compression technique: cache-aware, causal pruning, the learned keep-model, gist caching, and more.
• CLI Reference — every flag and sample output for all commands.
• Architecture — tier model, the measure→discover→certify loop, byte-fidelity invariants.