How Compression Works

Headroom automatically detects what kind of content you're sending and routes it to the right compressor. You don't need to configure anything -- just call compress() and the pipeline handles the rest.

The Pipeline

Every request flows through a short pipeline:

┌──────────────┐     ┌────────────────┐
│ CacheAligner │────>│ ContentRouter  │
│ (off by      │     │                │
│  default)    │     │ Detect type &  │
│ report drift │     │ route to best  │
│ for cache    │     │ compressor     │
└──────────────┘     └────────────────┘

1. CacheAligner (detector-only, off by default) reports dynamic-prefix drift (dates, session context) so callers can keep the static prefix cacheable. It never rewrites your messages.
2. ContentRouter inspects each content block and routes it to one compressor -- SmartCrusher for JSON arrays, CodeAwareCompressor for source code, LogCompressor for build output, and so on. This is where essentially all compression happens.

Content Type Detection

The router auto-detects content type by analyzing structure and patterns. No manual hints required.

Quick Start

import { compress } from "headroom-ai";

const messages = [
  { role: "system" as const, content: "You are a helpful assistant." },
  { role: "user" as const, content: "Summarize this data" },
  { role: "tool" as const, content: '{"results": [...]}', tool_call_id: "call_1" },
];

const result = await compress(messages);
console.log(`Tokens saved: ${result.tokensSaved}`);
console.log(`Compression ratio: ${result.compressionRatio}`);

Configuring the Compressor

import { compress } from "headroom-ai";

const result = await compress(messages, {
  model: "gpt-4o",
  tokenBudget: 50000,
});

console.log(`Before: ${result.tokensBefore} tokens`);
console.log(`After: ${result.tokensAfter} tokens`);
console.log(`Transforms: ${result.transformsApplied.join(", ")}`);

Structure Preservation

Headroom doesn't blindly truncate. It identifies what matters in each content type and preserves it:

Real Compression Ratios

Compression ratio and latency both depend heavily on the shape of the input (how redundant the data is, how large the payload is, and -- for Kompress -- what target_ratio is configured). There's no single number that holds across workloads, so treat the ranges in the table above as directional and reproduce them on your own traffic with the harnesses in benchmarks/ (for example compression_benchmark.py, bench_transforms.py, text_crusher_quality_eval.py). What stays constant across content types is what's preserved:

Compressing multiple documents

The public compress() API accepts an LLM message list. Put documents in separate messages or call it once per independent request; this preserves the same message shape you will send to the provider:

from headroom import compress

messages = [
    {"role": "user", "content": "Compare these documents."},
    {"role": "tool", "tool_call_id": "doc_1", "content": first_document},
    {"role": "tool", "tool_call_id": "doc_2", "content": second_document},
]
result = compress(messages, model="gpt-4o")

What Happens Under the Hood

When you call compress(), here is the full sequence:

1. Safety gates -- protected tools, recent turns, frozen cache prefixes, and minimum-size rules decide what may change.
2. Content detection -- Magika when available plus deterministic pattern matching identifies the content type.
3. Structural compression -- format-specific handlers compact JSON, logs, search results, tables, configuration, HTML, and other recognized structures.
4. Fallback compression -- Kompress handles eligible text when its runtime is available; a no-saving or failed transform passes the original through.
5. CCR storage in proxy flows -- when CCR is enabled, originals for marker-bearing compression are retained for later retrieval. --lossless and --no-ccr intentionally use different contracts; see Reversible Compression.