How to Configure the Target Compression Ratio in Headroom

Set the target_ratio parameter (between 0 and 1) in Headroom's compress() function or transform pipeline to specify the exact fraction of tokens to retain during compression.

Headroom (chopratejas/headroom) is an open-source text compression library that lets you control how aggressively content is reduced through a configurable target compression ratio. By passing a target_ratio value to the compression API, you dictate the precise proportion of tokens to keep, ensuring deterministic output lengths across tool outputs and assistant messages.

Understanding the Target Compression Ratio

The target_ratio parameter accepts a float between 0 and 1, representing the fraction of tokens to retain. For example, target_ratio=0.3 preserves approximately 30% of the original tokens (equivalent to 70% compression). When omitted, the compressor falls back to an internal score_threshold and lets the model decide how many tokens to preserve based on its own scoring logic.

How Target Ratio Flows Through the System

According to the Headroom source code, the target_ratio propagates unchanged through three architectural layers:

High-Level API Entry Point

In headroom/compress.py, the public compress() helper function accepts the target_ratio argument and forwards it to the underlying transform pipeline.

ContentRouter Injection

The ContentRouter transform in headroom/transforms/content_router.py extracts the runtime target_ratio kwarg from the request context on line 1475 and injects it into downstream compressors.

KompressCompressor Selection Logic

The actual token-selection algorithm lives in headroom/transforms/kompress_compressor.py. When target_ratio is provided, the compressor scores every token, sorts the scores, and keeps the top int(num_tokens × target_ratio) tokens (see the num_keep calculation on line 695). This deterministic top-k selection ensures the exact keep-count is respected.

Practical Code Examples

Direct Call to the compress() Helper

Use the high-level compress function from headroom/compress.py for simple integrations:

from headroom.compress import compress

messages = [
    {"role": "assistant", "content": "A very long answer …"},
    {"role": "tool", "content": "Results from a heavy computation …"},
]

# Keep only 25% of the original tokens.

compressed = compress(messages, model="gpt-4o", target_ratio=0.25)

print(compressed)   # → list of messages with shortened content

Manual Pipeline Configuration

For advanced use cases, manually wire the ContentRouter and KompressCompressor:

from headroom.transforms.kompress_compressor import KompressCompressor
from headroom.transforms.content_router import ContentRouter

# Build a pipeline that includes the ContentRouter and Kompress.

router = ContentRouter()
kompress = KompressCompressor()

# Supply the ratio through the router's kwargs.

router_kwargs = {"target_ratio": 0.4}   # keep 40% of tokens

# The router forwards the kwarg to KompressCompressor internally.

router.apply(messages, transformer=kompress, **router_kwargs)

Batch Compression with Per-Text Ratios

Process multiple texts with individual compression ratios using compress_batch():

from headroom.transforms.kompress_compressor import KompressCompressor

compressor = KompressCompressor()
texts = [
    "First long paragraph …",
    "Second long paragraph …",
    "Third short one.",
]

# Provide a list – each entry corresponds to the respective text.

ratios = [0.3, 0.5, None]   # third text uses the model's default decision

results = compressor.compress_batch(texts, target_ratio=ratios)

for r in results:
    print(r.compression_ratio, r.compressed)

Summary

• Set target_ratio between 0 and 1 to control the fraction of tokens Headroom retains.
• The value flows from headroom/compress.py through ContentRouter (line 1475) to KompressCompressor (line 695).
• KompressCompressor performs deterministic top-k selection based on int(num_tokens × target_ratio).
• Other transformers like SmartCrusher in headroom/transforms/smart_crusher.py also respect the target_ratio convention.
• Omitting target_ratio causes the model to rely on its internal score_threshold instead.

Frequently Asked Questions

What happens if I omit the target_ratio parameter?

When target_ratio is not provided, the compressor ignores the explicit keep-count logic and instead uses an internal score_threshold to determine which tokens to preserve, allowing the model to decide the compression level dynamically based on token importance scores.

Can I apply different compression ratios to different texts in a single batch?

Yes. Pass a list of values to target_ratio in compress_batch(), where each element corresponds to the respective text. Use None for specific items to let the model use its default threshold for those entries, as shown in the batch processing example above.

Is the resulting compression ratio guaranteed to be exact?

The compression is deterministic but not guaranteed to be mathematically exact to the decimal. The system calculates num_keep = int(num_tokens × target_ratio), which truncates to the nearest integer, potentially causing minor variance of one token depending on the input length.

Which transformers support the target_ratio configuration?

According to the Headroom source code, KompressCompressor in headroom/transforms/kompress_compressor.py implements the primary selection logic. Additionally, SmartCrusher in headroom/transforms/smart_crusher.py respects the same target_ratio convention, allowing consistent ratio-based compression across different pipeline stages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}