# How to Configure the Target Compression Ratio in Headroom

> Control token retention in Headroom by setting the target_ratio parameter. Learn how to specify the exact fraction of tokens to retain during compression.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-12

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/compress.py) for simple integrations:

```python
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`:

```python
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()`:

```python
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/kompress_compressor.py) implements the primary selection logic. Additionally, **`SmartCrusher`** in [`headroom/transforms/smart_crusher.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/smart_crusher.py) respects the same `target_ratio` convention, allowing consistent ratio-based compression across different pipeline stages.