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.

refactor(compression): deprecate the test-only UniversalCompressor package (#4095)

Tejas Choprafc8ff5a76192
diff --git a/headroom/compression/__init__.py b/headroom/compression/__init__.py
index 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.py
index 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 annotations
import logging
+import warnings
from collections.abc import Callable
from dataclasses import dataclass, field
from 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,
+)
+
@dataclass
class UniversalCompressorConfig:
diff --git a/tests/test_compression/test_deprecation.py b/tests/test_compression/test_deprecation.py
new file mode 100644
index 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)
+
+
+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__
+
+
+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)
+
+
+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)
+
+
+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)
+
+
+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