Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

Add CompressConfig: user-facing compression options for compress() API

chopratejas62ba612c7c7d
diff --git a/headroom/__init__.py b/headroom/__init__.py
index d162eb801..8fe042c22 100644
--- a/headroom/__init__.py
+++ b/headroom/__init__.py
@@ -74,7 +74,7 @@ from importlib import import_module
from typing import Any
from ._version import __version__ # noqa: F401
-from .compress import CompressResult, compress
+from .compress import CompressConfig, CompressResult, compress
# Keep a real callable bound for the one-function compression API so
# `from headroom import compress` is never shadowed by the submodule object.
@@ -169,6 +169,7 @@ __all__ = [
"EmbedderBackend",
# One-function compression API
"compress",
+ "CompressConfig",
"CompressResult",
# Hooks
"CompressionHooks",
diff --git a/headroom/compress.py b/headroom/compress.py
index 71808a9c9..1ae8636a8 100644
--- a/headroom/compress.py
+++ b/headroom/compress.py
@@ -72,6 +72,55 @@ _pipeline = None
_pipeline_lock = threading.Lock()
+@dataclass
+class CompressConfig:
+ """User-facing compression options.
+
+ Controls what gets compressed, how aggressively, and with which model.
+ Pass to ``compress()`` or any integration that uses headroom.
+
+ Examples::
+
+ # Coding agent (default — skip user messages, protect recent)
+ compress(messages, model="gpt-4o")
+
+ # Financial document (compress everything, keep 50%)
+ compress(messages, model="claude-opus-4-20250514",
+ compress_user_messages=True,
+ target_ratio=0.5,
+ protect_recent=0,
+ )
+
+ # Aggressive (logs, search results)
+ compress(messages, model="gpt-4o", target_ratio=0.2)
+ """
+
+ # What to compress
+ compress_user_messages: bool = False
+ """Compress user messages too (default: skip them for coding agents).
+ Set True for document compression, RAG pipelines, or when user messages
+ contain large tool outputs."""
+
+ protect_recent: int = 4
+ """Don't compress the last N messages (they're the active conversation).
+ Set 0 to compress everything."""
+
+ protect_analysis_context: bool = True
+ """Detect 'analyze'/'review' intent and protect code from compression."""
+
+ # How aggressive
+ target_ratio: float | None = None
+ """Keep ratio for Kompress. None = model decides (~15% kept, aggressive).
+ 0.5 = keep 50% (safe for documents). 0.7 = keep 70% (conservative).
+ Only affects Kompress (text compression). SmartCrusher (JSON) has its
+ own logic based on array dedup."""
+
+ # Model variant
+ kompress_model: str | None = None
+ """Kompress model variant. None = default ModernBERT. Future: 'finance'
+ for number-preserving compression on financial documents."""
+
+
@dataclass
class CompressResult:
"""Result of compressing messages.
@@ -99,6 +148,8 @@ def compress(
model_limit: int = 200000,
optimize: bool = True,
hooks: Any = None,
+ config: CompressConfig | None = None,
+ **kwargs: Any,
) -> CompressResult:
"""Compress messages using Headroom's full compression pipeline.
@@ -111,13 +162,36 @@ def compress(
model_limit: Model's context window size in tokens.
optimize: Whether to actually compress (False = passthrough for A/B testing).
hooks: Optional CompressionHooks instance for custom behavior.
+ config: Compression options (CompressConfig). Overrides defaults.
+ **kwargs: Shorthand for CompressConfig fields. These override config:
+ compress_user_messages, target_ratio, protect_recent,
+ protect_analysis_context, kompress_model.
Returns:
CompressResult with compressed messages and metrics.
+
+ Examples::
+
+ # Default (coding agent)
+ result = compress(messages, model="gpt-4o")
+
+ # Financial document (keep 50%, compress everything)
+ result = compress(messages, model="claude-opus-4-20250514",
+ compress_user_messages=True,
+ target_ratio=0.5,
+ protect_recent=0,
+ )
"""
if not messages or not optimize:
return CompressResult(messages=messages)
+ # Build config from explicit config + kwargs
+ cfg = config or CompressConfig()
+ config_fields = {f.name for f in cfg.__dataclass_fields__.values()}
+ for key, value in kwargs.items():
+ if key in config_fields:
+ setattr(cfg, key, value)
+
pipeline = _get_pipeline()
try:
@@ -141,6 +215,11 @@ def compress(
model_limit=model_limit,
context=context,
biases=biases,
+ # Pass CompressConfig options through to transforms
+ compress_user_messages=cfg.compress_user_messages,
+ target_ratio=cfg.target_ratio,
+ protect_recent=cfg.protect_recent,
+ protect_analysis_context=cfg.protect_analysis_context,
)
tokens_before = result.tokens_before
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index ca081ebaf..30abedcc5 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -1546,10 +1546,27 @@ class OpenAIHandlerMixin:
if token_budget and isinstance(token_budget, int)
else self.openai_provider.get_context_limit(model)
)
+ # Extract CompressConfig options from request body
+ compress_config = body.get("config", {})
+ compress_user_messages = compress_config.get("compress_user_messages", False)
+ target_ratio = compress_config.get("target_ratio")
+ protect_recent = compress_config.get("protect_recent")
+ protect_analysis_context = compress_config.get("protect_analysis_context")
+
+ pipeline_kwargs: dict = {"model_limit": context_limit}
+ if compress_user_messages:
+ pipeline_kwargs["compress_user_messages"] = True
+ if target_ratio is not None:
+ pipeline_kwargs["target_ratio"] = float(target_ratio)
+ if protect_recent is not None:
+ pipeline_kwargs["protect_recent"] = int(protect_recent)
+ if protect_analysis_context is not None:
+ pipeline_kwargs["protect_analysis_context"] = bool(protect_analysis_context)
+
result = self.openai_pipeline.apply(
messages=messages,
model=model,
- model_limit=context_limit,
+ **pipeline_kwargs,
)
return JSONResponse(
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index c7c051887..936066ba0 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -1093,7 +1093,10 @@ class ContentRouter(Transform):
if compressor:
try:
result = compressor.compress(
- text_to_compress, context=context, question=question
+ text_to_compress,
+ context=context,
+ question=question,
+ target_ratio=getattr(self, "_runtime_target_ratio", None),
)
compressed = result.compressed
compressed_tokens = result.compressed_tokens
@@ -1446,6 +1449,18 @@ class ContentRouter(Transform):
lifecycle_transforms = []
lifecycle_ccr_hashes = []
+ # Runtime overrides from CompressConfig (via kwargs from compress())
+ # These override self.config defaults for this call only.
+ skip_user = (
+ kwargs.get("compress_user_messages") is not True and self.config.skip_user_messages
+ )
+ protect_recent = kwargs.get("protect_recent", self.config.protect_recent_code)
+ protect_analysis = kwargs.get(
+ "protect_analysis_context", self.config.protect_analysis_context
+ )
+ # Store target_ratio on self for access by _route_and_compress_block
+ self._runtime_target_ratio: float | None = kwargs.get("target_ratio")
+
tokens_before = sum(tokenizer.count_text(str(m.get("content", ""))) for m in messages)
context = kwargs.get("context", "")
hook_biases: dict[int, float] = kwargs.get("biases") or {}
@@ -1611,8 +1626,8 @@ class ContentRouter(Transform):
tool_name = tool_name_map.get(tool_call_id, "")
bias = self._get_tool_bias(tool_name) if tool_name else 1.0
- # Protection 1: Never compress user messages
- if self.config.skip_user_messages and role == "user":
+ # Protection 1: Never compress user messages (unless overridden)
+ if skip_user and role == "user":
result_slots[i] = message
transforms_applied.append("router:protected:user_message")
route_counts["user_msg"] += 1
@@ -1630,18 +1645,14 @@ class ContentRouter(Transform):
# Protection 2: Don't compress recent CODE
messages_from_end = num_messages - i
- if (
- self.config.protect_recent_code > 0
- and messages_from_end <= self.config.protect_recent_code
- and is_code
- ):
+ if protect_recent > 0 and messages_from_end <= protect_recent and is_code:
result_slots[i] = message
transforms_applied.append("router:protected:recent_code")
route_counts["recent_code"] += 1
continue
# Protection 3: Don't compress CODE when analysis intent detected
- if analysis_intent and is_code:
+ if protect_analysis and analysis_intent and is_code:
result_slots[i] = message
transforms_applied.append("router:protected:analysis_context")
route_counts["analysis_ctx"] += 1