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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
Add CompressConfig: user-facing compression options for compress() API
chopratejas62ba612c7c7d
diff --git a/headroom/__init__.py b/headroom/__init__.pyindex d162eb801..8fe042c22 100644--- a/headroom/__init__.py+++ b/headroom/__init__.py@@ -74,7 +74,7 @@ from importlib import import_modulefrom typing import Anyfrom ._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.pyindex 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."""++@dataclassclass 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_beforediff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 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.pyindex 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.compressedcompressed_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] = messagetransforms_applied.append("router:protected:user_message")route_counts["user_msg"] += 1@@ -1630,18 +1645,14 @@ class ContentRouter(Transform):# Protection 2: Don't compress recent CODEmessages_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] = messagetransforms_applied.append("router:protected:recent_code")route_counts["recent_code"] += 1continue# 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] = messagetransforms_applied.append("router:protected:analysis_context")route_counts["analysis_ctx"] += 1