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
refactor(compression): deprecate the test-only UniversalCompressor package (#4095)
Tejas Choprafc8ff5a76192
diff --git a/headroom/compression/__init__.py b/headroom/compression/__init__.pyindex dd4a9ad2a..58fa63840 100644--- a/headroom/compression/__init__.py+++ b/headroom/compression/__init__.py@@ -1,32 +1,31 @@"""Universal compression with ML-based content detection.-This module provides intelligent, automatic compression that:-1. Detects content type using ML (Magika)-2. Preserves structure (keys, signatures, templates)-3. Compresses content with Kompress-4. Enables retrieval via CCR--Quick Start:- # One-liner for simple use- from headroom.compression import compress- result = compress(content)-- # Or with configuration- from headroom.compression import UniversalCompressor, UniversalCompressorConfig-- config = UniversalCompressorConfig(compression_ratio_target=0.5)- compressor = UniversalCompressor(config=config)- result = compressor.compress(content)+.. deprecated::+ The package API (``compress``, ``UniversalCompressor``,+ ``UniversalCompressorConfig``, ``CompressionResult``, ``MagikaDetector``,+ ``ContentType``, ``StructureMask``) is unused inside Headroom and will be+ removed in a future release. Use ``headroom.compress()`` for one-call+ compression, or ``ContentRouter`` from ``headroom.transforms``.++``headroom.compression.detector`` is still used by the proxy (Magika preload+at startup) and importing it does not warn."""-from headroom.compression.detector import ContentType, MagikaDetector-from headroom.compression.masks import StructureMask-from headroom.compression.universal import (- CompressionResult,- UniversalCompressor,- UniversalCompressorConfig,- compress,-)+from __future__ import annotations++import warnings+from importlib import import_module+from typing import TYPE_CHECKING++if TYPE_CHECKING:+ from headroom.compression.detector import ContentType, MagikaDetector+ from headroom.compression.masks import StructureMask+ from headroom.compression.universal import (+ CompressionResult,+ UniversalCompressor,+ UniversalCompressorConfig,+ compress,+ )__all__ = [# Simple API@@ -40,3 +39,45 @@ __all__ = ["ContentType","StructureMask",]++_DEPRECATED_EXPORTS: dict[str, tuple[str, str]] = {+ "compress": ("headroom.compression.universal", "compress"),+ "UniversalCompressor": ("headroom.compression.universal", "UniversalCompressor"),+ "UniversalCompressorConfig": ("headroom.compression.universal", "UniversalCompressorConfig"),+ "CompressionResult": ("headroom.compression.universal", "CompressionResult"),+ "MagikaDetector": ("headroom.compression.detector", "MagikaDetector"),+ "ContentType": ("headroom.compression.detector", "ContentType"),+ "StructureMask": ("headroom.compression.masks", "StructureMask"),+}++# On importlib.reload() the module dict is reused; drop cached exports so the+# next access resolves (and warns) against the current submodules.+for _name in _DEPRECATED_EXPORTS:+ globals().pop(_name, None)+del _name+++def __getattr__(name: str) -> object:+ try:+ module_name, attr_name = _DEPRECATED_EXPORTS[name]+ except KeyError as exc:+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from exc+ warnings.warn(+ f"headroom.compression.{name} is deprecated and will be removed in a future release; "+ "use headroom.compress() for one-call compression, or ContentRouter from headroom.transforms.",+ DeprecationWarning,+ stacklevel=2,+ )+ # Warn once, here, rather than again from universal.py's import-time warning.+ with warnings.catch_warnings():+ warnings.simplefilter("ignore", DeprecationWarning)+ module = import_module(module_name)+ value = getattr(module, attr_name)+ # Cache it, so `from headroom.compression import X` (which looks the name+ # up twice) warns once, and later accesses stay quiet.+ globals()[name] = value+ return value+++def __dir__() -> list[str]:+ return sorted(set(globals()) | set(__all__))diff --git a/headroom/compression/universal.py b/headroom/compression/universal.pyindex e384826ea..a32de261a 100644--- a/headroom/compression/universal.py+++ b/headroom/compression/universal.py@@ -1,5 +1,10 @@"""Universal compressor with ML-based detection and structure preservation.+.. deprecated::+ Nothing in Headroom uses this module. It will be removed in a future+ release. Use ``headroom.compress()`` for one-call compression, or+ ``ContentRouter`` from ``headroom.transforms``.+This is the main entry point for compression. It:1. Detects content type using Magika (ML)2. Extracts structure using appropriate handler@@ -20,6 +25,7 @@ Usage:from __future__ import annotationsimport logging+import warningsfrom collections.abc import Callablefrom dataclasses import dataclass, fieldfrom typing import Any@@ -44,6 +50,13 @@ from headroom.compression.masks import (logger = logging.getLogger(__name__)+warnings.warn(+ "headroom.compression.universal is deprecated and will be removed in a future release; "+ "use headroom.compress() for one-call compression, or ContentRouter from headroom.transforms.",+ DeprecationWarning,+ stacklevel=2,+)+@dataclassclass UniversalCompressorConfig:diff --git a/tests/test_compression/test_deprecation.py b/tests/test_compression/test_deprecation.pynew file mode 100644index 000000000..a2394abbb--- /dev/null+++ b/tests/test_compression/test_deprecation.py@@ -0,0 +1,96 @@+"""The headroom.compression package API is deprecated; detector stays quiet."""++from __future__ import annotations++import importlib+import sys+import warnings+from collections.abc import Iterator++import pytest++import headroom.compression as compression+++def fresh(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]:+ """Drop cached exports and the universal module for the test.++ Exports cached during the test are dropped again afterwards; monkeypatch+ then restores whatever was cached before.+ """+ for name in compression.__all__:+ monkeypatch.delitem(compression.__dict__, name, raising=False)+ monkeypatch.delitem(sys.modules, "headroom.compression.universal", raising=False)+ monkeypatch.delattr(compression, "universal", raising=False)+ yield+ for name in compression.__all__:+ compression.__dict__.pop(name, None)++[email protected]("fresh")+def test_attribute_access_warns_once() -> None:+ with pytest.warns(+ DeprecationWarning, match="compression.UniversalCompressor is deprecated"+ ) as record:+ compressor_cls = compression.UniversalCompressor+ assert compression.UniversalCompressor is compressor_cls # cached: no second warning+ assert compressor_cls.__name__ == "UniversalCompressor"+ # One warning, attributed to this file rather than to importlib.+ assert len(record) == 1+ assert record[0].filename == __file__++[email protected]("fresh")+def test_from_import_warns_once() -> None:+ with warnings.catch_warnings(record=True) as record:+ warnings.simplefilter("always")+ from headroom.compression import ContentType # noqa: F401+ deprecations = [w for w in record if issubclass(w.category, DeprecationWarning)]+ assert len(deprecations) == 1+ assert "use headroom.compress" in str(deprecations[0].message)++[email protected]("fresh")+def test_wildcard_import_warns_once_per_name() -> None:+ namespace: dict[str, object] = {}+ with warnings.catch_warnings(record=True) as record:+ warnings.simplefilter("always")+ exec("from headroom.compression import *", namespace)+ messages = [str(w.message) for w in record if issubclass(w.category, DeprecationWarning)]+ assert len(messages) == len(compression.__all__)+ assert set(compression.__all__) <= set(namespace)++[email protected]("fresh")+def test_universal_module_import_warns() -> None:+ with pytest.warns(DeprecationWarning, match="compression.universal is deprecated"):+ importlib.import_module("headroom.compression.universal")+++def test_detector_import_stays_quiet(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delitem(sys.modules, "headroom.compression.detector", raising=False)+ monkeypatch.delattr(compression, "detector", raising=False)+ with warnings.catch_warnings():+ warnings.simplefilter("error", DeprecationWarning)+ detector = importlib.import_module("headroom.compression.detector")+ assert callable(detector._magika_available)++[email protected]("fresh")+def test_reload_drops_cached_exports() -> None:+ import headroom.compression.detector as detector++ real = detector.ContentType+ with pytest.warns(DeprecationWarning):+ assert compression.ContentType is real+ stand_in = type("ReloadedContentType", (), {})+ with pytest.MonkeyPatch.context() as patch:+ patch.setattr(detector, "ContentType", stand_in)+ importlib.reload(compression)+ with pytest.warns(DeprecationWarning):+ assert compression.ContentType is stand_in+ # Back on the real class: a second reload must drop the cached stand-in.+ importlib.reload(compression)+ with pytest.warns(DeprecationWarning):+ assert compression.ContentType is real