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
Fix proxy crash when torch not installed (kompress lazy imports)
chopratejasfb4ab0885635
diff --git a/headroom/__init__.py b/headroom/__init__.pyindex c5a983bb3..84c1f0abd 100644--- a/headroom/__init__.py+++ b/headroom/__init__.py@@ -153,7 +153,7 @@ from .transforms import (TransformPipeline,)-__version__ = "0.4.4"+__version__ = "0.4.5"__all__ = [# Main clientdiff --git a/headroom/transforms/kompress_compressor.py b/headroom/transforms/kompress_compressor.pyindex 49280c2e4..8e700566b 100644--- a/headroom/transforms/kompress_compressor.py+++ b/headroom/transforms/kompress_compressor.py@@ -3,8 +3,7 @@Drop-in replacement for LLMLingua-2. Auto-downloads the model fromHuggingFace (chopratejas/kompress-base) on first use.-No extra pip install needed — uses transformers + safetensors-which are already Headroom dependencies.+Requires the [ml] extra: pip install headroom-ai[ml]Usage:>>> from headroom.transforms.kompress_compressor import KompressCompressor@@ -20,10 +19,6 @@ import threadingfrom dataclasses import dataclassfrom typing import Any-import torch-import torch.nn as nn-from transformers import AutoModel, AutoTokenizer-from ..config import TransformResultfrom ..tokenizer import Tokenizerfrom .base import Transform@@ -39,64 +34,95 @@ _kompress_tokenizer = None_kompress_lock = threading.Lock()-# ── Model Architecture (must match training) ──────────────────────────-+def is_kompress_available() -> bool:+ """Check if Kompress dependencies are available (requires [ml] extra)."""+ try:+ import huggingface_hub # noqa: F401+ import safetensors # noqa: F401+ import torch # noqa: F401+ import transformers # noqa: F401-class HeadroomCompressorModel(nn.Module):- """Dual-head ModernBERT: token classification + span importance CNN."""+ return True+ except ImportError:+ return False- def __init__(self, model_name: str = "answerdotai/ModernBERT-base"):- super().__init__()- self.encoder = AutoModel.from_pretrained(model_name, attn_implementation="eager")- hidden_size = self.encoder.config.hidden_size # 768- # Head 1: Token keep/discard- self.token_dropout = nn.Dropout(0.1)- self.token_head = nn.Linear(hidden_size, 2)+# ── Model Architecture (must match training) ──────────────────────────+# torch/transformers are imported lazily — only when actually needed.+# This allows `from kompress_compressor import is_kompress_available`+# to work without torch installed.+++def _get_model_class() -> type:+ """Return the HeadroomCompressorModel class, importing torch on demand."""+ import torch+ import torch.nn as nn+ from transformers import AutoModel++ class HeadroomCompressorModel(nn.Module):+ """Dual-head ModernBERT: token classification + span importance CNN."""++ def __init__(self, model_name: str = "answerdotai/ModernBERT-base"):+ super().__init__()+ self.encoder = AutoModel.from_pretrained(model_name, attn_implementation="eager")+ hidden_size = self.encoder.config.hidden_size # 768++ # Head 1: Token keep/discard+ self.token_dropout = nn.Dropout(0.1)+ self.token_head = nn.Linear(hidden_size, 2)++ # Head 2: Span importance (1D CNN)+ self.span_conv = nn.Sequential(+ nn.Conv1d(hidden_size, 256, kernel_size=5, padding=2),+ nn.GELU(),+ nn.Conv1d(256, 1, kernel_size=3, padding=1),+ nn.Sigmoid(),+ )- # Head 2: Span importance (1D CNN)- self.span_conv = nn.Sequential(- nn.Conv1d(hidden_size, 256, kernel_size=5, padding=2),- nn.GELU(),- nn.Conv1d(256, 1, kernel_size=3, padding=1),- nn.Sigmoid(),- )+ def get_keep_mask(+ self, input_ids: torch.Tensor, attention_mask: torch.Tensor+ ) -> torch.Tensor:+ """Get per-token keep/discard decision. True = keep."""+ with torch.no_grad():+ hidden = self.encoder(input_ids, attention_mask=attention_mask).last_hidden_state- def get_keep_mask(self, input_ids: torch.Tensor, attention_mask: torch.Tensor) -> torch.Tensor:- """Get per-token keep/discard decision. True = keep."""- with torch.no_grad():- hidden = self.encoder(input_ids, attention_mask=attention_mask).last_hidden_state+ # Token head: binary classifier — argmax decides keep/discard+ token_logits = self.token_head(hidden) # [B, L, 2]+ token_keep = (+ token_logits[:, :, 1] > token_logits[:, :, 0]+ ) # True if class 1 > class 0- # Token head: binary classifier — argmax decides keep/discard- token_logits = self.token_head(hidden) # [B, L, 2]- token_keep = token_logits[:, :, 1] > token_logits[:, :, 0] # True if class 1 > class 0+ # Span head: boost tokens in important spans+ # If a token is borderline but its span is important, keep it+ span_scores = self.span_conv(hidden.transpose(1, 2)).squeeze(1)+ span_boost = span_scores > 0.5 # span says this region matters- # Span head: boost tokens in important spans- # If a token is borderline but its span is important, keep it- span_scores = self.span_conv(hidden.transpose(1, 2)).squeeze(1)- span_boost = span_scores > 0.5 # span says this region matters+ # Keep if: token head says keep, OR token is borderline and span says keep+ token_probs = torch.softmax(token_logits, dim=-1)[:, :, 1]+ borderline = (token_probs > 0.3) & (token_probs <= 0.5)+ keep = token_keep | (borderline & span_boost)- # Keep if: token head says keep, OR token is borderline and span says keep- token_probs = torch.softmax(token_logits, dim=-1)[:, :, 1]- borderline = (token_probs > 0.3) & (token_probs <= 0.5)- keep = token_keep | (borderline & span_boost)+ return keep # type: ignore[no-any-return]- return keep # type: ignore[no-any-return]+ def get_scores(self, input_ids: torch.Tensor, attention_mask: torch.Tensor) -> torch.Tensor:+ """Get per-token importance scores (for ranking when target_ratio is set)."""+ with torch.no_grad():+ hidden = self.encoder(input_ids, attention_mask=attention_mask).last_hidden_state+ token_probs = torch.softmax(self.token_head(hidden), dim=-1)[:, :, 1]+ span_scores = self.span_conv(hidden.transpose(1, 2)).squeeze(1)+ return token_probs * (0.5 + 0.5 * span_scores) # type: ignore[no-any-return]- def get_scores(self, input_ids: torch.Tensor, attention_mask: torch.Tensor) -> torch.Tensor:- """Get per-token importance scores (for ranking when target_ratio is set)."""- with torch.no_grad():- hidden = self.encoder(input_ids, attention_mask=attention_mask).last_hidden_state- token_probs = torch.softmax(self.token_head(hidden), dim=-1)[:, :, 1]- span_scores = self.span_conv(hidden.transpose(1, 2)).squeeze(1)- return token_probs * (0.5 + 0.5 * span_scores) # type: ignore[no-any-return]+ return HeadroomCompressorModel# ── Model Loading ─────────────────────────────────────────────────────-def _load_kompress(device: str = "auto") -> tuple[HeadroomCompressorModel, Any]:+def _load_kompress(device: str = "auto") -> tuple[Any, Any]:"""Download from HuggingFace and load the Kompress model."""+ import torch+ from transformers import AutoTokenizer+global _kompress_model, _kompress_tokenizerwith _kompress_lock:@@ -111,6 +137,7 @@ def _load_kompress(device: str = "auto") -> tuple[HeadroomCompressorModel, Any]:weights_path = hf_hub_download(HF_MODEL_ID, "model.safetensors")# Load architecture+ HeadroomCompressorModel = _get_model_class()model = HeadroomCompressorModel()# Load trained weights@@ -139,19 +166,6 @@ def _load_kompress(device: str = "auto") -> tuple[HeadroomCompressorModel, Any]:return model, tokenizer-def is_kompress_available() -> bool:- """Check if Kompress dependencies are available (requires [ml] extra)."""- try:- import huggingface_hub # noqa: F401- import safetensors # noqa: F401- import torch # noqa: F401- import transformers # noqa: F401-- return True- except ImportError:- return False--def unload_kompress_model() -> bool:"""Unload the Kompress model to free memory."""global _kompress_model, _kompress_tokenizer@@ -159,8 +173,13 @@ def unload_kompress_model() -> bool:if _kompress_model is not None:_kompress_model = None_kompress_tokenizer = None- if torch.cuda.is_available():- torch.cuda.empty_cache()+ try:+ import torch++ if torch.cuda.is_available():+ torch.cuda.empty_cache()+ except ImportError:+ passreturn Truereturn Falsediff --git a/pyproject.toml b/pyproject.tomlindex 8d12a33e3..0175b9aff 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "headroom-ai"-version = "0.4.4"+version = "0.4.5"description = "The Context Optimization Layer for LLM Applications - Cut costs by 50-90%"readme = "README.md"license = "Apache-2.0"diff --git a/tests/test_transforms/test_kompress_compressor.py b/tests/test_transforms/test_kompress_compressor.pynew file mode 100644index 000000000..3989421ee--- /dev/null+++ b/tests/test_transforms/test_kompress_compressor.py@@ -0,0 +1,204 @@+"""Tests for Kompress compressor.++Covers:+- Lazy imports: module importable without torch installed+- is_kompress_available(): correct detection of [ml] extra+- KompressConfig / KompressResult: dataclass defaults+- KompressCompressor: passthrough for short content, fallback on error+- Transform interface: apply() method+"""++from unittest.mock import MagicMock, patch++# ── Import safety (the whole point of the fix) ─────────────────────────+++class TestLazyImports:+ """The module must be importable without torch/transformers."""++ def test_is_kompress_available_importable(self) -> None:+ """is_kompress_available can be imported even without torch."""+ from headroom.transforms.kompress_compressor import is_kompress_available++ # Should return bool (True or False depending on environment)+ result = is_kompress_available()+ assert isinstance(result, bool)++ def test_module_import_without_torch(self) -> None:+ """Importing the module with torch blocked should not raise."""+ import sys++ # Block torch imports+ with patch.dict(sys.modules, {"torch": None, "torch.nn": None}):+ # Force re-evaluation of is_kompress_available+ from headroom.transforms.kompress_compressor import is_kompress_available++ # Should gracefully return False, not crash+ assert is_kompress_available() is False++ def test_dataclasses_importable_without_torch(self) -> None:+ """KompressConfig, KompressResult, KompressCompressor are importable without torch."""+ from headroom.transforms.kompress_compressor import (+ KompressCompressor, # noqa: F401+ KompressConfig,+ KompressResult,+ )++ # These don't need torch to instantiate+ config = KompressConfig()+ assert config.device == "auto"+ assert config.enable_ccr is True++ result = KompressResult(+ compressed="hello",+ original="hello world",+ original_tokens=2,+ compressed_tokens=1,+ compression_ratio=0.5,+ )+ assert result.tokens_saved == 1+ assert result.savings_percentage == 50.0+++# ── KompressResult ──────────────────────────────────────────────────────+++class TestKompressResult:+ def test_tokens_saved(self) -> None:+ from headroom.transforms.kompress_compressor import KompressResult++ r = KompressResult(+ compressed="a b",+ original="a b c d",+ original_tokens=4,+ compressed_tokens=2,+ compression_ratio=0.5,+ )+ assert r.tokens_saved == 2++ def test_tokens_saved_no_negative(self) -> None:+ from headroom.transforms.kompress_compressor import KompressResult++ r = KompressResult(+ compressed="a b c d e",+ original="a b c",+ original_tokens=3,+ compressed_tokens=5,+ compression_ratio=1.67,+ )+ assert r.tokens_saved == 0++ def test_savings_percentage_zero_tokens(self) -> None:+ from headroom.transforms.kompress_compressor import KompressResult++ r = KompressResult(+ compressed="",+ original="",+ original_tokens=0,+ compressed_tokens=0,+ compression_ratio=1.0,+ )+ assert r.savings_percentage == 0.0++ def test_default_model(self) -> None:+ from headroom.transforms.kompress_compressor import HF_MODEL_ID, KompressResult++ r = KompressResult(+ compressed="x",+ original="x y",+ original_tokens=2,+ compressed_tokens=1,+ compression_ratio=0.5,+ )+ assert r.model_used == HF_MODEL_ID+++# ── KompressCompressor (without model) ──────────────────────────────────+++class TestKompressCompressorPassthrough:+ """Test compressor behavior that doesn't require the actual model."""++ def test_short_content_passthrough(self) -> None:+ """Content under 10 words should pass through unchanged."""+ from headroom.transforms.kompress_compressor import KompressCompressor++ compressor = KompressCompressor()+ result = compressor.compress("hello world")+ assert result.compressed == "hello world"+ assert result.compression_ratio == 1.0+ assert result.original_tokens == 2+ assert result.compressed_tokens == 2++ def test_empty_content_passthrough(self) -> None:+ from headroom.transforms.kompress_compressor import KompressCompressor++ compressor = KompressCompressor()+ result = compressor.compress("")+ assert result.compressed == ""+ assert result.compression_ratio == 1.0++ def test_fallback_on_model_error(self) -> None:+ """If _load_kompress fails, compress should return passthrough."""+ from headroom.transforms.kompress_compressor import KompressCompressor++ compressor = KompressCompressor()+ long_text = " ".join(f"word{i}" for i in range(20))++ with patch(+ "headroom.transforms.kompress_compressor._load_kompress",+ side_effect=RuntimeError("no model"),+ ):+ result = compressor.compress(long_text)+ assert result.compressed == long_text+ assert result.compression_ratio == 1.0+++# ── Transform interface ─────────────────────────────────────────────────+++class TestKompressTransformInterface:+ def test_apply_short_messages_unchanged(self) -> None:+ """Messages with <10 words should pass through apply() unchanged."""+ from headroom.transforms.kompress_compressor import KompressCompressor++ compressor = KompressCompressor()+ messages = [+ {"role": "user", "content": "hello"},+ {"role": "tool", "content": "short"},+ ]+ tokenizer = MagicMock()+ tokenizer.count_text = MagicMock(return_value=5)++ result = compressor.apply(messages, tokenizer)+ assert len(result.messages) == 2+ assert result.messages[0]["content"] == "hello"+ assert result.messages[1]["content"] == "short"++ def test_apply_preserves_user_messages(self) -> None:+ """User messages should never be compressed."""+ from headroom.transforms.kompress_compressor import KompressCompressor++ compressor = KompressCompressor()+ long_text = " ".join(f"word{i}" for i in range(50))+ messages = [{"role": "user", "content": long_text}]+ tokenizer = MagicMock()+ tokenizer.count_text = MagicMock(return_value=50)++ with patch(+ "headroom.transforms.kompress_compressor._load_kompress",+ side_effect=RuntimeError("should not be called"),+ ):+ result = compressor.apply(messages, tokenizer)+ assert result.messages[0]["content"] == long_text+++# ── unload_kompress_model ───────────────────────────────────────────────+++class TestUnloadKompressModel:+ def test_unload_when_no_model(self) -> None:+ from headroom.transforms.kompress_compressor import unload_kompress_model++ # Should return False when no model is loaded+ assert unload_kompress_model() is False