# How to Perform Basic Compression with the Headroom Python Library

> Learn how to perform basic compression with the Headroom Python library. Reduce LLM message token counts efficiently while preserving meaning using the headroom.compress function.

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

---

**Headroom provides a single-function API (`headroom.compress`) that executes a lazy-initialized transformation pipeline to reduce LLM message token counts while preserving semantic meaning, returning detailed compression statistics and the optimized message list.**

The Headroom Python library (chopratejas/headroom) optimizes LLM context windows through intelligent message compression. To perform basic compression with the Headroom Python library, you invoke the `compress()` function exposed in the top-level package namespace. This interface orchestrates a sophisticated sequence of Rust-backed transforms while maintaining a simple, synchronous Python API.

## The `compress()` Entry Point

Headroom exposes a one-line integration pattern through [`headroom/compress.py`](https://github.com/chopratejas/headroom/blob/main/headroom/compress.py). The `compress()` function serves as the sole entry point for all compression operations, eliminating the need for manual pipeline management.

When you call `compress(messages, model=...)`, the function initializes a lazy singleton `TransformPipeline` via the internal `_get_pipeline()` helper (lines 45-66). This pipeline is cached for the process lifetime, ensuring subsequent calls avoid re-initialization overhead. The function then extracts the user query using `_extract_user_query(messages)` (lines 30-34) to provide context for relevance scoring, applies the configured transforms via `pipeline.apply()`, and returns a `CompressResult` containing the compressed messages and token metrics.

## Inside the Compression Pipeline

The pipeline executes five distinct phases according to the source implementation in [`headroom/compress.py`](https://github.com/chopratejas/headroom/blob/main/headroom/compress.py):

1. **Lazy Singleton Initialization**. The `_get_pipeline()` function creates the `TransformPipeline` on first use and caches it for the lifetime of the process.

2. **Query Extraction**. The function extracts the user query so downstream transforms can score relevance during compression.

3. **Transform Application**. A configurable series runs: **CacheAligner** → **ContentRouter** → specific compressors such as **SmartCrusher**, **CodeCompressor**, and **Kompress**.

4. **Metrics Collection**. The function builds a `CompressResult` containing tokens before/after, savings, and compression ratio (lines 20-27).

5. **Failure Handling**. If Rust-backed compressors are missing or an exception occurs, the original messages return unchanged with a logged warning (lines 29-42).

## Configuring Compression Behavior

Customize behavior via the `CompressConfig` dataclass (defined in [`headroom/compress.py`](https://github.com/chopratejas/headroom/blob/main/headroom/compress.py), lines 76-95). This configuration object exposes fine-grained control over the compression process:

- **`compress_user_messages`**: Whether to compress user-authored content (default: False)
- **`target_ratio`**: Desired compression level (e.g., 0.5 keeps 50% of tokens)
- **`min_tokens_to_compress`**: Threshold below which compression is skipped
- **`protect_recent`**: Number of recent messages to exempt from compression

You can pass `CompressConfig` as the `config` parameter or use inline keyword arguments for convenience.

## Practical Implementation Examples

### Basic Usage

```python
from headroom import compress

messages = [
    {"role": "user", "content": "Explain the theory of relativity in simple terms."},
    {"role": "assistant", "content": "Sure... (very long explanation)"},
]

result = compress(messages, model="gpt-4o")
print("Compressed messages:", result.messages)
print("Tokens saved:", result.tokens_saved)
print("Compression ratio:", result.compression_ratio)

```

### Advanced Configuration

```python
from headroom import compress, CompressConfig

cfg = CompressConfig(
    compress_user_messages=True,
    target_ratio=0.5,
    protect_recent=0,
)

result = compress(messages, model="claude-opus-4-20250514", config=cfg)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.1%} reduction)")

```

### Shortcut Keyword Arguments

```python
from headroom import compress

result = compress(
    messages,
    model="gpt-4o",
    compress_user_messages=True,
    target_ratio=0.3,
    min_tokens_to_compress=100,
)

print("Transforms applied:", result.transforms_applied)

```

### Anthropic SDK Integration

```python
from anthropic import Anthropic
from headroom import compress

client = Anthropic()
raw_messages = [{"role": "user", "content": "Give me a long JSON report"}]

compressed = compress(raw_messages, model="claude-3-5-sonnet-20240620")
response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    messages=compressed.messages,
)

```

### Inspecting Pipeline Steps

```python
result = compress(messages, model="gpt-4o")
print("Pipeline steps used:", result.transforms_applied)

# Output: ['CacheAligner', 'ContentRouter', 'Kompress', 'SmartCrusher']

```

## Core Source Files and Architecture

The compression workflow spans these key modules:

- **[`headroom/compress.py`](https://github.com/chopratejas/headroom/blob/main/headroom/compress.py)**: Main entry point, `CompressConfig` dataclass, and `CompressResult` definitions
- **[`headroom/transforms/pipeline.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/pipeline.py)**: `TransformPipeline` orchestration and sequence management
- **[`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py)**: Routes each message to the appropriate compressor
- **[`headroom/transforms/kompress_compressor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/kompress_compressor.py)**: ML-backed text compression implementation
- **[`headroom/transforms/smart_crusher.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/smart_crusher.py)**: JSON-array compression for tool results
- **[`headroom/utils.py`](https://github.com/chopratejas/headroom/blob/main/headroom/utils.py)**: Helper functions for user query extraction
- **[`headroom/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/__init__.py)**: Public API exports including `compress` and `CompressConfig`

## Summary

- Invoke `headroom.compress()` to execute the full compression pipeline via a single function call.
- The `TransformPipeline` initializes lazily on first use and caches for subsequent calls.
- Configure behavior through the `CompressConfig` dataclass or inline keyword arguments.
- The function returns a `CompressResult` containing compressed messages, token savings, and compression ratios.
- If compression fails, the library returns original messages unchanged and logs a warning.

## Frequently Asked Questions

### What happens if the Rust-backed compressors are not installed?

If the Rust extensions are missing or an exception occurs during processing, the `compress()` function catches the error and returns the original messages unchanged. It logs a warning via the standard logging module and provides a no-op `CompressResult` indicating zero compression, ensuring your application remains functional even without the native dependencies.

### Does the model parameter affect the compression algorithm?

The `model` parameter primarily determines token counting behavior used for metrics calculation, not the compression algorithm itself. While you should pass the specific model name (e.g., "gpt-4o" or "claude-3-5-sonnet-20240620") for accurate token statistics, the transforms apply semantic compression based on content type rather than model-specific formatting.

### How do I prevent recent messages from being excluded from compression?

Set the `protect_recent` parameter in `CompressConfig` to `0`, or pass `protect_recent=0` as a keyword argument to `compress()`. By default, Headroom protects recent messages to preserve conversational context, but setting this to zero allows the pipeline to compress the entire message history regardless of recency.

### Can I see which transforms were applied to my messages?

Yes. The `CompressResult` object returned by `compress()` includes a `transforms_applied` attribute containing a list of transform names (e.g., `['CacheAligner', 'ContentRouter', 'Kompress']`). Inspect this list to understand which specific compressors processed your messages and verify the pipeline execution path.