How to Configure Tool-Specific Compression Profiles in Headroom

You configure tool-specific compression profiles in Headroom by instantiating a custom CompressionPolicy with a list of ToolProfile objects that map regex patterns to item limits, then passing that policy to the TransformPipeline via the compression_policy parameter.

Headroom is an open-source proxy framework that optimizes LLM context windows through intelligent compression. While the system defaults to per-authentication-mode policies, production deployments often need granular control over how individual tools are compressed. This guide demonstrates how to configure tool-specific compression profiles using Headroom's policy architecture as implemented in the chopratejas/headroom repository.

Understanding Headroom's Compression Architecture

Headroom's compression behavior is governed by the CompressionPolicy dataclass defined in headroom/transforms/compression_policy.py. The policy system operates on a per-auth-mode basis, with transforms like CacheAligner, SmartCrusher, and ContentRouter accessing the runtime policy via self._runtime_compression_policy.

The pipeline injects this policy into every transform through kwargs["compression_policy"], allowing downstream compressors to adjust their behavior based on the active configuration. By default, the system resolves policies using policy_for_mode(AuthMode) or the resolve_policy(auth_mode) helper, but you can override this with custom tool-specific mappings.

Creating Tool-Specific Profiles

Tool-specific profiles allow you to define different compression limits for different tools using regex pattern matching. This is particularly useful when certain tools (like database queries) need higher context retention than others (like Slack searches).

Define the ToolProfile Structure

While Headroom's core compressors expect a specific profile shape, you define custom profiles using a dataclass that includes a regex pattern, a maximum item limit, and an enable flag. The get_profile(tool_name: str) helper in headroom/transforms/compression_units.py selects the first matching profile from your list.

from dataclasses import dataclass
import re
from typing import List

@dataclass(frozen=True, slots=True)
class ToolProfile:
    """Defines compression behavior for a specific tool or tool group."""
    tool_name_pattern: re.Pattern[str]   # Regex matching the tool identifier

    max_items: int                       # Maximum items the compressor retains

    enabled: bool = True                 # Gate to disable compression entirely

Build Profile Lists with Fallbacks

Create a prioritized list where the first matching pattern wins. Include a catch-all entry at the end to define default behavior for unmatched tools.

custom_profiles: List[ToolProfile] = [
    ToolProfile(re.compile(r"slack", re.I), max_items=25),
    ToolProfile(re.compile(r"database|sql", re.I), max_items=30),
    ToolProfile(re.compile(r"github", re.I), max_items=20),
    # Fallback profile matches any tool name

    ToolProfile(re.compile(r".*"), max_items=20),
]

Attaching Profiles to the Compression Policy

The CompressionPolicy dataclass does not include a profiles field by default, so you attach your custom list as a dynamic attribute. This pattern is safe because the MCP compressor reads the attribute directly from the policy object.

Instantiate and Customize the Policy

Start with a base policy using policy_for_mode(), then attach your profile list using setattr().

from headroom.transforms.compression_policy import CompressionPolicy, policy_for_mode
from headroom.types import AuthMode

# Start with PAYG or SUBSCRIPTION base policy

base_policy = policy_for_mode(AuthMode.PAYG)

# Build custom policy preserving core fields

custom_policy = CompressionPolicy(
    live_zone_only=base_policy.live_zone_only,
    cache_aligner_enabled=base_policy.cache_aligner_enabled,
    volatile_token_threshold=base_policy.volatile_token_threshold,
    max_lossy_ratio=base_policy.max_lossy_ratio,
    toin_read_only=base_policy.toin_read_only,
)

# Attach tool-specific profiles (not a dataclass field, but expected by compressor)

setattr(custom_policy, "profiles", custom_profiles)

Configure the Transform Pipeline

Pass the customized policy to TransformPipeline during initialization. The pipeline forwards this policy to all transforms via their kwargs.

from headroom.transforms.pipeline import TransformPipeline
from headroom.transforms.smart_crusher import SmartCrusher

pipeline = TransformPipeline(
    transforms=[
        SmartCrusher(),
        # Additional transforms...

    ],
    compression_policy=custom_policy,
)

When the pipeline processes a request, transforms access self._runtime_compression_policy (populated from kwargs["compression_policy"]) to determine compression behavior. The MCP compressor calls get_profile(tool_name)—passing the tool name from request metadata—to retrieve the appropriate ToolProfile and apply its max_items limit.

Alternative Policy Resolution Methods

You can override policy selection without modifying pipeline construction by using environment variables or manual resolution.

Environment Variable Approach: Set HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT=disabled to force PAYG-style policies for all tools, bypassing the automatic resolution logic.

Manual Resolution: Call headroom.transforms.compression_policy.resolve_policy(auth_mode) directly and substitute the returned object with your custom policy before passing it to transforms.

Complete Working Example

This end-to-end example demonstrates building a per-tool profile list and executing the pipeline:

import re
from dataclasses import dataclass
from typing import List

from headroom.transforms.compression_policy import CompressionPolicy, policy_for_mode
from headroom.transforms.pipeline import TransformPipeline
from headroom.transforms.smart_crusher import SmartCrusher
from headroom.types import AuthMode

# 1. Define tool-specific profiles

@dataclass(frozen=True, slots=True)
class ToolProfile:
    tool_name_pattern: re.Pattern[str]
    max_items: int
    enabled: bool = True

profiles = [
    ToolProfile(re.compile(r"slack", re.I), max_items=25),
    ToolProfile(re.compile(r"database|sql", re.I), max_items=30),
    ToolProfile(re.compile(r"github", re.I), max_items=20),
    ToolProfile(re.compile(r".*"), max_items=20),  # fallback

]

# 2. Create custom compression policy

base = policy_for_mode(AuthMode.PAYG)
custom_policy = CompressionPolicy(
    live_zone_only=base.live_zone_only,
    cache_aligner_enabled=base.cache_aligner_enabled,
    volatile_token_threshold=base.volatile_token_threshold,
    max_lossy_ratio=base.max_lossy_ratio,
    toin_read_only=base.toin_read_only,
)
setattr(custom_policy, "profiles", profiles)

# 3. Initialize pipeline with custom policy

pipeline = TransformPipeline(
    transforms=[SmartCrusher()],
    compression_policy=custom_policy,
)

# 4. Execute with specific tool name

# messages = [...]  # Your message list

# tokenizer = tokenizer_factory()

# result = pipeline.apply(messages, tokenizer, tool_name="mcp__slack__search")

Summary

• Tool-specific compression in Headroom relies on creating ToolProfile objects with regex patterns and max_items limits.
• Policy attachment requires setting the profiles attribute on a CompressionPolicy instance (via setattr) because it is not a native dataclass field.
• Pipeline injection occurs through the compression_policy parameter in TransformPipeline, which propagates to all transforms via kwargs.
• Profile selection happens at runtime via get_profile(tool_name: str) in headroom/transforms/compression_units.py, using the first matching regex pattern.
• File locations: Policy logic lives in headroom/transforms/compression_policy.py, profile utilities in headroom/transforms/compression_units.py, and pipeline orchestration in headroom/transforms/pipeline.py.

Frequently Asked Questions

Where is the CompressionPolicy dataclass defined?

The CompressionPolicy dataclass is defined in headroom/transforms/compression_policy.py. This file also contains the policy_for_mode() and resolve_policy() helper functions that the system uses to select default policies based on authentication modes.

How does the pipeline pass the compression policy to transforms?

The TransformPipeline class (in headroom/transforms/pipeline.py) stores the policy in self._runtime_compression_policy and injects it into each transform via the kwargs["compression_policy"] argument. Transforms like SmartCrusher and ContentRouter then read this value to adjust their compression behavior.

Can I disable compression for specific tools while keeping it enabled for others?

Yes. Set enabled=False in the ToolProfile for tools you want to exclude from compression. When get_profile(tool_name) returns a profile with enabled=False, the compressor bypasses compression for that request while continuing to process other tools normally.

What is the difference between AuthMode.PAYG and AuthMode.SUBSCRIPTION policies?

AuthMode.PAYG (Pay As You Go) and AuthMode.SUBSCRIPTION represent different billing tiers that trigger distinct default CompressionPolicy configurations. policy_for_mode(AuthMode) returns a policy with settings optimized for each tier's cost and performance characteristics, which you can then customize with tool-specific profiles as shown above.

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