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 one-function compress() API, ASGI middleware, LiteLLM callback
chopratejasdde2f9f848c9
diff --git a/headroom/__init__.py b/headroom/__init__.pyindex 69096bf55..f48bf61c1 100644--- a/headroom/__init__.py+++ b/headroom/__init__.py@@ -219,4 +219,15 @@ __all__ = ["HierarchicalMemory","MemoryConfig","EmbedderBackend",+ # One-function API+ "compress",+ "CompressResult",+ # Hooks+ "CompressionHooks",+ "CompressContext",+ "CompressEvent",]++# One-function compression API+from headroom.compress import CompressResult, compress # noqa: E402+from headroom.hooks import CompressContext, CompressEvent, CompressionHooks # noqa: E402diff --git a/headroom/compress.py b/headroom/compress.pynew file mode 100644index 000000000..187c9ac31--- /dev/null+++ b/headroom/compress.py@@ -0,0 +1,199 @@+"""One-function compression API for Headroom.++The simplest way to use Headroom — no proxy, no config, just compress:++ from headroom import compress++ result = compress(messages, model="claude-sonnet-4-5-20250929")+ result.messages # Compressed messages (same format, fewer tokens)+ result.tokens_saved # Tokens saved+ result.compression_ratio # e.g., 0.35 means 65% saved++Works with any LLM client, any proxy, any framework. Just compress+the messages before sending them.++Examples:++ # With Anthropic SDK+ from anthropic import Anthropic+ from headroom import compress++ client = Anthropic()+ messages = [{"role": "user", "content": huge_tool_output}]+ compressed = compress(messages, model="claude-sonnet-4-5-20250929")+ response = client.messages.create(+ model="claude-sonnet-4-5-20250929",+ messages=compressed.messages,+ )++ # With OpenAI SDK+ from openai import OpenAI+ from headroom import compress++ client = OpenAI()+ messages = [{"role": "user", "content": "analyze this"}, {"role": "tool", "content": big_data}]+ compressed = compress(messages, model="gpt-4o")+ response = client.chat.completions.create(model="gpt-4o", messages=compressed.messages)++ # With LiteLLM+ import litellm+ from headroom import compress++ messages = [...]+ compressed = compress(messages, model="bedrock/claude-sonnet")+ response = litellm.completion(model="bedrock/claude-sonnet", messages=compressed.messages)++ # With any HTTP client+ import httpx+ from headroom import compress++ compressed = compress(messages, model="claude-sonnet-4-5-20250929")+ httpx.post("https://api.anthropic.com/v1/messages", json={+ "model": "claude-sonnet-4-5-20250929",+ "messages": compressed.messages,+ })+"""++from __future__ import annotations++import logging+from dataclasses import dataclass, field+from typing import Any++logger = logging.getLogger(__name__)++# Lazy-initialized singleton pipeline+_pipeline = None+_pipeline_lock = None+++@dataclass+class CompressResult:+ """Result of compressing messages.++ Attributes:+ messages: The compressed messages (same format as input).+ tokens_before: Token count before compression.+ tokens_after: Token count after compression.+ tokens_saved: Tokens removed by compression.+ compression_ratio: Ratio of tokens saved (0.0 = no savings, 1.0 = 100% removed).+ transforms_applied: List of transforms that were applied.+ """++ messages: list[dict[str, Any]]+ tokens_before: int = 0+ tokens_after: int = 0+ tokens_saved: int = 0+ compression_ratio: float = 0.0+ transforms_applied: list[str] = field(default_factory=list)+++def compress(+ messages: list[dict[str, Any]],+ model: str = "claude-sonnet-4-5-20250929",+ model_limit: int = 200000,+ optimize: bool = True,+ hooks: Any = None,+) -> CompressResult:+ """Compress messages using Headroom's full compression pipeline.++ This is the simplest way to use Headroom. No proxy, no config needed.+ Just pass messages and get compressed messages back.++ Args:+ messages: List of messages in Anthropic or OpenAI format.+ model: Model name (used for token counting and context limit).+ 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.++ Returns:+ CompressResult with compressed messages and metrics.+ """+ if not messages or not optimize:+ return CompressResult(messages=messages)++ pipeline = _get_pipeline()++ try:+ # Compute biases from hooks if provided+ biases = None+ if hooks:+ from headroom.hooks import CompressContext++ ctx = CompressContext(model=model)+ messages = hooks.pre_compress(messages, ctx)+ biases = hooks.compute_biases(messages, ctx)++ result = pipeline.apply(+ messages=messages,+ model=model,+ model_limit=model_limit,+ biases=biases,+ )++ tokens_before = result.tokens_before+ tokens_after = result.tokens_after+ tokens_saved = tokens_before - tokens_after+ ratio = tokens_saved / tokens_before if tokens_before > 0 else 0.0++ # Post-compress hook+ if hooks and tokens_saved > 0:+ from headroom.hooks import CompressEvent++ hooks.post_compress(+ CompressEvent(+ tokens_before=tokens_before,+ tokens_after=tokens_after,+ tokens_saved=tokens_saved,+ compression_ratio=ratio,+ transforms_applied=result.transforms_applied,+ model=model,+ )+ )++ return CompressResult(+ messages=result.messages,+ tokens_before=tokens_before,+ tokens_after=tokens_after,+ tokens_saved=tokens_saved,+ compression_ratio=ratio,+ transforms_applied=result.transforms_applied,+ )++ except Exception as e:+ logger.warning("Compression failed, returning original messages: %s", e)+ return CompressResult(messages=messages)+++def _get_pipeline() -> Any:+ """Get or create the singleton compression pipeline."""+ global _pipeline++ if _pipeline is not None:+ return _pipeline++ import threading++ global _pipeline_lock+ if _pipeline_lock is None:+ _pipeline_lock = threading.Lock()++ with _pipeline_lock:+ if _pipeline is not None:+ return _pipeline++ from headroom.transforms import ContentRouter, SmartCrusher, TransformPipeline++ _pipeline = TransformPipeline(+ transforms=[+ ContentRouter(),+ SmartCrusher(),+ ],+ # No provider needed — pipeline uses tokenizer registry which+ # auto-detects the right tokenizer per model:+ # OpenAI → tiktoken (exact), Anthropic → calibrated estimation,+ # Open models → HuggingFace (if installed)+ )+ logger.debug("Headroom compression pipeline initialized")+ return _pipelinediff --git a/headroom/integrations/asgi.py b/headroom/integrations/asgi.pynew file mode 100644index 000000000..bc9f2027d--- /dev/null+++ b/headroom/integrations/asgi.py@@ -0,0 +1,160 @@+"""ASGI Middleware — add Headroom compression to any Python proxy.++Drop-in middleware for FastAPI, Starlette, LiteLLM proxy, or any ASGI app.+Intercepts LLM requests, compresses messages, forwards the smaller payload.++Usage with LiteLLM proxy:++ from litellm.proxy.proxy_server import app+ from headroom.integrations.asgi import CompressionMiddleware++ app.add_middleware(CompressionMiddleware)++Usage with any FastAPI app:++ from fastapi import FastAPI+ from headroom.integrations.asgi import CompressionMiddleware++ app = FastAPI()+ app.add_middleware(CompressionMiddleware)+ # Your existing routes...++Configuration:++ app.add_middleware(+ CompressionMiddleware,+ min_tokens=500, # Only compress if messages > 500 tokens+ model_limit=200000, # Context window size+ )+"""++from __future__ import annotations++import json+import logging+from typing import Any++from starlette.types import ASGIApp, Receive, Scope, Send++logger = logging.getLogger(__name__)++# Paths that contain LLM messages to compress+_LLM_PATHS = (+ "/v1/messages", # Anthropic+ "/v1/chat/completions", # OpenAI+ "/v1/responses", # OpenAI Responses API+ "/chat/completions", # LiteLLM (without /v1 prefix)+)+++class CompressionMiddleware:+ """ASGI middleware that compresses LLM request messages.++ Intercepts POST requests to LLM endpoints, compresses the messages+ using Headroom's full pipeline, and forwards the smaller payload.++ Response headers include compression metrics:+ - x-headroom-tokens-before: original token count+ - x-headroom-tokens-after: compressed token count+ - x-headroom-tokens-saved: tokens removed+ """++ def __init__(+ self,+ app: ASGIApp,+ min_tokens: int = 500,+ model_limit: int = 200000,+ hooks: Any = None,+ ) -> None:+ self.app = app+ self._min_tokens = min_tokens+ self._model_limit = model_limit+ self._hooks = hooks++ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:+ if scope["type"] != "http":+ await self.app(scope, receive, send)+ return++ path = scope.get("path", "")+ method = scope.get("method", "GET")++ # Only intercept POST to LLM endpoints+ if method != "POST" or not any(path.endswith(p) or path == p for p in _LLM_PATHS):+ await self.app(scope, receive, send)+ return++ # Buffer the request body+ body_chunks: list[bytes] = []++ async def buffering_receive() -> dict[str, Any]:+ message: dict[str, Any] = await receive()+ if message["type"] == "http.request":+ chunk = message.get("body", b"")+ if chunk:+ body_chunks.append(chunk)+ return message++ # Read the full body+ while True:+ msg = await buffering_receive()+ if msg.get("type") == "http.request":+ if not msg.get("more_body", False):+ break++ full_body = b"".join(body_chunks)++ # Parse and compress+ tokens_saved = 0+ try:+ body_json = json.loads(full_body)+ messages = body_json.get("messages", [])+ model = body_json.get("model", "")++ if messages:+ from headroom.compress import compress++ result = compress(+ messages=messages,+ model=model or "claude-sonnet-4-5-20250929",+ model_limit=self._model_limit,+ hooks=self._hooks,+ )++ if result.tokens_saved > 0:+ body_json["messages"] = result.messages+ full_body = json.dumps(body_json).encode("utf-8")+ tokens_saved = result.tokens_saved++ logger.info(+ "Headroom: %d→%d tokens (saved %d, %.0f%%)",+ result.tokens_before,+ result.tokens_after,+ result.tokens_saved,+ result.compression_ratio * 100,+ )++ except (json.JSONDecodeError, TypeError, KeyError) as e:+ logger.debug("Headroom middleware: skipping non-JSON request: %s", e)++ # Create a new receive that returns the (possibly modified) body+ body_sent = False++ async def modified_receive() -> dict[str, Any]:+ nonlocal body_sent+ if not body_sent:+ body_sent = True+ return {"type": "http.request", "body": full_body, "more_body": False}+ result: dict[str, Any] = await receive()+ return result++ # Wrap send to inject compression headers+ async def metrics_send(message: dict[str, Any]) -> None:+ if message["type"] == "http.response.start" and tokens_saved > 0:+ headers = list(message.get("headers", []))+ headers.append((b"x-headroom-compressed", b"true"))+ headers.append((b"x-headroom-tokens-saved", str(tokens_saved).encode()))+ message = {**message, "headers": headers}+ await send(message)++ await self.app(scope, modified_receive, metrics_send)diff --git a/headroom/integrations/litellm_callback.py b/headroom/integrations/litellm_callback.pynew file mode 100644index 000000000..413fc973a--- /dev/null+++ b/headroom/integrations/litellm_callback.py@@ -0,0 +1,107 @@+"""LiteLLM callback — add Headroom compression to LiteLLM with one line.++ import litellm+ from headroom.integrations.litellm_callback import HeadroomCallback++ litellm.callbacks = [HeadroomCallback()]+ # All LiteLLM calls now get compressed automatically.++ # Or with custom config:+ litellm.callbacks = [HeadroomCallback(min_tokens=1000)]++Works with LiteLLM's completion(), acompletion(), and proxy modes.+"""++from __future__ import annotations++import logging+from typing import Any++logger = logging.getLogger(__name__)+++class HeadroomCallback:+ """LiteLLM callback that compresses messages before each API call.++ Implements LiteLLM's CustomLogger interface (async_pre_call_hook).+ Compresses messages using Headroom's full pipeline, reducing token+ usage across all providers LiteLLM supports.++ Usage:+ import litellm+ from headroom.integrations.litellm_callback import HeadroomCallback++ litellm.callbacks = [HeadroomCallback()]+ response = litellm.completion(model="gpt-4o", messages=[...])+ """++ def __init__(+ self,+ min_tokens: int = 500,+ model_limit: int = 200000,+ hooks: Any = None,+ ) -> None:+ self._min_tokens = min_tokens+ self._model_limit = model_limit+ self._hooks = hooks+ self._total_saved = 0++ @property+ def total_tokens_saved(self) -> int:+ """Total tokens saved across all calls."""+ return self._total_saved++ async def async_pre_call_hook(+ self,+ user_api_key: str,+ data: dict[str, Any],+ call_type: str,+ ) -> dict[str, Any]:+ """Called by LiteLLM before each API call. Compresses messages."""+ if call_type not in ("completion", "acompletion"):+ return data++ messages = data.get("messages", [])+ model = data.get("model", "")++ if not messages:+ return data++ try:+ from headroom.compress import compress++ result = compress(+ messages=messages,+ model=model or "claude-sonnet-4-5-20250929",+ model_limit=self._model_limit,+ hooks=self._hooks,+ )++ if result.tokens_saved > 0:+ data["messages"] = result.messages+ self._total_saved += result.tokens_saved+ logger.info(+ "Headroom: %d→%d tokens (saved %d, %.0f%%) [total saved: %d]",+ result.tokens_before,+ result.tokens_after,+ result.tokens_saved,+ result.compression_ratio * 100,+ self._total_saved,+ )++ except Exception as e:+ logger.warning("Headroom compression failed, using original messages: %s", e)++ return data++ async def async_success_handler(+ self, kwargs: dict, response: Any, start_time: Any, end_time: Any+ ) -> None:+ """Called after successful completion. No-op for now."""+ pass++ async def async_failure_handler(+ self, kwargs: dict, response: Any, start_time: Any, end_time: Any+ ) -> None:+ """Called after failed completion. No-op for now."""+ passdiff --git a/headroom/transforms/pipeline.py b/headroom/transforms/pipeline.pyindex 1258f326b..480a98382 100644--- a/headroom/transforms/pipeline.py+++ b/headroom/transforms/pipeline.py@@ -123,14 +123,25 @@ class TransformPipeline:return transformsdef _get_tokenizer(self, model: str) -> Tokenizer:- """Get tokenizer for model using provider."""- if self._provider is None:- raise ValueError(- "Provider is required for token counting. "- "Pass a provider to TransformPipeline or HeadroomClient."- )- token_counter = self._provider.get_token_counter(model)- return Tokenizer(token_counter, model)+ """Get tokenizer for model.++ Uses provider's tokenizer if available, otherwise falls back to+ the tokenizer registry which auto-detects the best backend per model:+ - OpenAI models: tiktoken (exact)+ - Anthropic models: calibrated estimation (~3.5 chars/token)+ - Open models: HuggingFace tokenizer (if installed)+ - Unknown models: character-based estimation+ """+ if self._provider is not None:+ token_counter = self._provider.get_token_counter(model)+ return Tokenizer(token_counter, model)++ # No provider — use the tokenizer registry (auto-detects per model)+ # TokenCounter from tokenizers and providers have the same interface+ # (count_text, count_messages) but are different Protocol types.+ from headroom.tokenizers import get_tokenizer++ return Tokenizer(get_tokenizer(model), model) # type: ignore[arg-type]def apply(self,diff --git a/tests/test_compress_api.py b/tests/test_compress_api.pynew file mode 100644index 000000000..33cadb288--- /dev/null+++ b/tests/test_compress_api.py@@ -0,0 +1,244 @@+"""Tests for the one-function compress() API and integrations."""++import json++from starlette.applications import Starlette+from starlette.requests import Request+from starlette.responses import JSONResponse+from starlette.routing import Route+from starlette.testclient import TestClient++from headroom.compress import CompressResult, compress+from headroom.hooks import CompressionHooks+from headroom.integrations.asgi import CompressionMiddleware++# =============================================================================+# Tests: compress() function+# =============================================================================+++class TestCompressFunction:+ def test_empty_messages(self):+ result = compress([], model="test")+ assert result.messages == []+ assert result.tokens_saved == 0++ def test_small_messages_passthrough(self):+ """Small messages below compression threshold pass through unchanged."""+ messages = [{"role": "user", "content": "hello"}]+ result = compress(messages, model="gpt-4o")+ assert result.messages[0]["content"] == "hello"+ assert result.tokens_saved == 0++ def test_returns_compress_result(self):+ result = compress([{"role": "user", "content": "hi"}])+ assert isinstance(result, CompressResult)+ assert hasattr(result, "messages")+ assert hasattr(result, "tokens_saved")+ assert hasattr(result, "compression_ratio")+ assert hasattr(result, "transforms_applied")++ def test_large_tool_output_compressed(self):+ """Large JSON tool output should be compressed."""+ big_data = json.dumps(+ [+ {"id": i, "status": "active", "name": f"item_{i}", "value": i * 17}+ for i in range(200)+ ]+ )+ messages = [+ {"role": "user", "content": "What are the top items?"},+ {"role": "tool", "content": big_data, "tool_call_id": "call_1"},+ ]+ result = compress(messages, model="gpt-4o")+ # Should have compressed the tool output+ assert result.tokens_after <= result.tokens_before+ assert len(result.messages) == 2++ def test_optimize_false_passthrough(self):+ """optimize=False returns messages unchanged."""+ messages = [{"role": "user", "content": "hello world " * 100}]+ result = compress(messages, optimize=False)+ assert result.messages is messages+ assert result.tokens_saved == 0++ def test_with_custom_hooks(self):+ """Hooks are called when provided."""+ calls = []++ class TrackingHooks(CompressionHooks):+ def pre_compress(self, messages, ctx):+ calls.append(("pre", len(messages)))+ return messages++ def compute_biases(self, messages, ctx):+ calls.append(("biases", len(messages)))+ return {}++ def post_compress(self, event):+ calls.append(("post", event.tokens_saved))++ big_data = json.dumps([{"id": i, "status": "active"} for i in range(100)])+ messages = [+ {"role": "user", "content": "analyze"},+ {"role": "tool", "content": big_data, "tool_call_id": "c1"},+ ]+ compress(messages, hooks=TrackingHooks())++ assert any(c[0] == "pre" for c in calls)+ assert any(c[0] == "biases" for c in calls)+++class TestCompressResultFields:+ def test_fields_populated(self):+ big_data = json.dumps([{"id": i, "type": "log"} for i in range(100)])+ messages = [+ {"role": "user", "content": "summarize"},+ {"role": "tool", "content": big_data, "tool_call_id": "c1"},+ ]+ result = compress(messages, model="claude-sonnet-4-5-20250929")+ assert result.tokens_before > 0+ assert result.tokens_after >= 0+ assert result.tokens_saved >= 0+ assert 0.0 <= result.compression_ratio <= 1.0+++# =============================================================================+# Tests: ASGI CompressionMiddleware+# =============================================================================+++def _make_asgi_app(middleware_kwargs=None):+ """Create a test ASGI app with CompressionMiddleware."""++ async def chat_endpoint(request: Request) -> JSONResponse:+ body = await request.json()+ return JSONResponse(+ {+ "model": "gpt-4o",+ "choices": [{"message": {"content": "response"}}],+ "usage": {"prompt_tokens": 10, "completion_tokens": 5},+ "_message_count": len(body.get("messages", [])),+ }+ )++ async def health(request: Request) -> JSONResponse:+ return JSONResponse({"status": "ok"})++ app = Starlette(+ routes=[+ Route("/health", health),+ Route("/v1/chat/completions", chat_endpoint, methods=["POST"]),+ Route("/v1/messages", chat_endpoint, methods=["POST"]),+ ]+ )+ app.add_middleware(CompressionMiddleware, **(middleware_kwargs or {}))+ return app+++class TestASGIMiddleware:+ def test_non_llm_paths_passthrough(self):+ app = _make_asgi_app()+ client = TestClient(app)+ resp = client.get("/health")+ assert resp.status_code == 200+ assert resp.json()["status"] == "ok"++ def test_small_messages_passthrough(self):+ app = _make_asgi_app()+ client = TestClient(app)+ resp = client.post(+ "/v1/chat/completions",+ json={"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]},+ )+ assert resp.status_code == 200++ def test_large_messages_compressed(self):+ """Large tool output should be compressed by middleware."""+ app = _make_asgi_app()+ client = TestClient(app)++ big_data = json.dumps([{"id": i, "status": "active"} for i in range(200)])+ resp = client.post(+ "/v1/chat/completions",+ json={+ "model": "gpt-4o",+ "messages": [+ {"role": "user", "content": "analyze"},+ {"role": "tool", "content": big_data, "tool_call_id": "c1"},+ ],+ },+ )+ assert resp.status_code == 200++ def test_anthropic_path(self):+ """Works with Anthropic /v1/messages path."""+ app = _make_asgi_app()+ client = TestClient(app)+ resp = client.post(+ "/v1/messages",+ json={+ "model": "claude-sonnet-4-5-20250929",+ "messages": [{"role": "user", "content": "hello"}],+ },+ )+ assert resp.status_code == 200++ def test_get_requests_passthrough(self):+ """GET requests to LLM paths pass through (no body to compress)."""+ app = _make_asgi_app()+ client = TestClient(app)+ resp = client.get("/v1/chat/completions")+ # Will 405 because route only accepts POST, but middleware shouldn't crash+ assert resp.status_code in (200, 405)+++# =============================================================================+# Tests: LiteLLM Callback+# =============================================================================+++class TestLiteLLMCallback:+ def test_callback_imports(self):+ """Verify the callback can be imported."""+ from headroom.integrations.litellm_callback import HeadroomCallback++ callback = HeadroomCallback()+ assert callback.total_tokens_saved == 0++ def test_callback_compresses_messages(self):+ """Callback compresses messages in pre_call_hook."""+ import asyncio++ from headroom.integrations.litellm_callback import HeadroomCallback++ callback = HeadroomCallback()++ big_data = json.dumps([{"id": i, "status": "active"} for i in range(200)])+ data = {+ "model": "gpt-4o",+ "messages": [+ {"role": "user", "content": "analyze"},+ {"role": "tool", "content": big_data, "tool_call_id": "c1"},+ ],+ }++ result = asyncio.get_event_loop().run_until_complete(+ callback.async_pre_call_hook("key", data, "completion")+ )+ # Data should be modified in place+ assert result is data++ def test_callback_ignores_non_completion(self):+ """Non-completion calls are passed through."""+ import asyncio++ from headroom.integrations.litellm_callback import HeadroomCallback++ callback = HeadroomCallback()+ data = {"messages": [{"role": "user", "content": "hi"}]}++ result = asyncio.get_event_loop().run_until_complete(+ callback.async_pre_call_hook("key", data, "embedding")+ )+ assert result is data # Unchanged