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(transforms): deprecate the unused Python AnchorSelector port (#4104)

Tejas Chopra9b1971dd82c9
diff --git a/headroom/transforms/__init__.py b/headroom/transforms/__init__.py
index 47932bc5c..3f3447e7f 100644
--- a/headroom/transforms/__init__.py
+++ b/headroom/transforms/__init__.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import importlib.util
+import warnings
from importlib import import_module
from typing import TYPE_CHECKING
@@ -209,6 +210,10 @@ _LAZY_EXPORTS: dict[str, tuple[str, str]] = {
}
+# Lazy exports that are deprecated: accessing them warns at the caller.
+_DEPRECATED_MODULES = frozenset({"headroom.transforms.anchor_selector"})
+
+
def __getattr__(name: str) -> object:
if name == "__path__":
raise AttributeError(name)
@@ -220,6 +225,23 @@ def __getattr__(name: str) -> object:
except KeyError as exc:
raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from exc
+ if module_name in _DEPRECATED_MODULES:
+ warnings.warn(
+ f"headroom.transforms.{name} is deprecated and will be removed in a future "
+ "release; it has no replacement (SmartCrusher's anchor selection runs in Rust).",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ # Warn once, here, rather than again from the module's own 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.transforms import X` (which looks the
+ # name up twice) warns once, and later accesses stay quiet.
+ globals()[name] = value
+ return value
+
module = import_module(module_name)
value = getattr(module, attr_name)
globals()[name] = value
diff --git a/headroom/transforms/anchor_selector.py b/headroom/transforms/anchor_selector.py
index d6bb60f9c..9c966aafc 100644
--- a/headroom/transforms/anchor_selector.py
+++ b/headroom/transforms/anchor_selector.py
@@ -1,5 +1,10 @@
"""Dynamic anchor selection for SmartCrusher.
+.. deprecated::
+ This Python implementation is unused: SmartCrusher's anchor selection
+ runs in Rust (``crates/headroom-core/src/transforms/anchor_selector.rs``).
+ It will be removed in a future release and has no replacement.
+
This module provides intelligent position-based anchor selection for array
compression. Instead of using fixed first-K/last-K rules, it dynamically
allocates anchor positions based on:
@@ -35,8 +40,12 @@ Example usage:
from __future__ import annotations
import hashlib
+import importlib
import json
import logging
+import os
+import sys
+import warnings
from collections import Counter
from dataclasses import dataclass
from enum import Enum
@@ -46,6 +55,22 @@ from ..config import AnchorConfig
logger = logging.getLogger(__name__)
+_DEPRECATION_MESSAGE = (
+ "headroom.transforms.anchor_selector is deprecated and will be removed in a "
+ "future release; it has no replacement (SmartCrusher's anchor selection runs in Rust)."
+)
+
+if sys.version_info >= (3, 12):
+ # Skip importlib's own frames too, so `importlib.import_module(...)` is
+ # attributed to its caller, like a plain `import` statement.
+ warnings.warn(
+ _DEPRECATION_MESSAGE,
+ DeprecationWarning,
+ skip_file_prefixes=(os.path.dirname(importlib.__file__) + os.sep,),
+ )
+else: # pragma: no cover - Python 3.10/3.11 lack skip_file_prefixes
+ warnings.warn(_DEPRECATION_MESSAGE, DeprecationWarning, stacklevel=2)
+
class DataPattern(Enum):
"""Data patterns detected in tool outputs.
diff --git a/tests/test_transforms_package.py b/tests/test_transforms_package.py
index 97eb1b6ca..c39fdbd8d 100644
--- a/tests/test_transforms_package.py
+++ b/tests/test_transforms_package.py
@@ -1,5 +1,9 @@
from __future__ import annotations
+import importlib
+import sys
+import warnings
+
import pytest
import headroom.transforms as transforms
@@ -24,3 +28,64 @@ def test_transforms_getattr_and_dir(monkeypatch: pytest.MonkeyPatch) -> None:
with pytest.raises(AttributeError, match="MissingExport"):
transforms.__getattr__("MissingExport")
+
+
+_ANCHOR_EXPORTS = (
+ "AnchorSelector",
+ "AnchorStrategy",
+ "AnchorWeights",
+ "DataPattern",
+ "calculate_information_score",
+ "compute_item_hash",
+)
+
+
+def fresh_anchor_selector(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Drop cached exports and the module; monkeypatch restores both afterwards."""
+ for name in _ANCHOR_EXPORTS:
+ monkeypatch.delitem(transforms.__dict__, name, raising=False)
+ monkeypatch.delitem(sys.modules, "headroom.transforms.anchor_selector", raising=False)
+ monkeypatch.delattr(transforms, "anchor_selector", raising=False)
+
+
[email protected]("fresh_anchor_selector")
+def test_anchor_selector_attribute_access_warns_once() -> None:
+ # A live export stays quiet.
+ with warnings.catch_warnings():
+ warnings.simplefilter("error", DeprecationWarning)
+ assert transforms.ContentRouter is not None
+
+ with pytest.warns(DeprecationWarning, match="AnchorSelector is deprecated") as record:
+ selector_cls = transforms.AnchorSelector
+ assert transforms.AnchorSelector is selector_cls # cached: no second warning
+ assert selector_cls.__name__ == "AnchorSelector"
+ # One warning, attributed to this file rather than to importlib.
+ assert len(record) == 1
+ assert record[0].filename == __file__
+
+
[email protected]("fresh_anchor_selector")
+def test_anchor_selector_from_import_warns_once() -> None:
+ with warnings.catch_warnings(record=True) as record:
+ warnings.simplefilter("always")
+ from headroom.transforms import AnchorSelector # noqa: F401
+ deprecations = [w for w in record if issubclass(w.category, DeprecationWarning)]
+ assert len(deprecations) == 1
+ assert deprecations[0].filename == __file__
+
+
[email protected]("fresh_anchor_selector")
+def test_anchor_selector_import_statement_is_deprecated() -> None:
+ with pytest.warns(DeprecationWarning, match="anchor_selector is deprecated") as record:
+ import headroom.transforms.anchor_selector # noqa: F401
+ assert record[0].filename == __file__
+
+
[email protected]("fresh_anchor_selector")
+def test_anchor_selector_dynamic_import_is_deprecated() -> None:
+ with pytest.warns(DeprecationWarning, match="anchor_selector is deprecated") as record:
+ importlib.import_module("headroom.transforms.anchor_selector")
+ if sys.version_info >= (3, 12):
+ # Older Pythons cannot skip importlib's frame, so the warning names importlib.
+ assert record[0].filename == __file__