How to Perform Basic Compression with the Headroom Python Library

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. 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:

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, 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

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

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

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

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

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: Main entry point, CompressConfig dataclass, and CompressResult definitions
• headroom/transforms/pipeline.py: TransformPipeline orchestration and sequence management
• headroom/transforms/content_router.py: Routes each message to the appropriate compressor
• headroom/transforms/kompress_compressor.py: ML-backed text compression implementation
• headroom/transforms/smart_crusher.py: JSON-array compression for tool results
• headroom/utils.py: Helper functions for user query extraction
• 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.

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