refactor(transforms): deprecate the unused Python AnchorSelector port (#4104)

## Description

`headroom/transforms/anchor_selector.py` is the Python original of the
anchor selector that SmartCrusher now runs in Rust
(`crates/headroom-core/src/transforms/anchor_selector.rs`). Nothing in
Headroom calls it, it has no tests or docs, and no consumer repo imports
it. It is still exported from `headroom.transforms`, so this PR
deprecates it instead of deleting it. There is no replacement.

Refs #4136

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

## Changes Made

- Accessing `AnchorSelector`, `AnchorStrategy`, `AnchorWeights`,
`DataPattern`, `calculate_information_score` or `compute_item_hash`
through `headroom.transforms` emits one `DeprecationWarning`, attributed
to the caller.
- The resolved object is cached in the package globals, so a `from`
import (which looks the name up twice) warns once.
- Importing `headroom.transforms.anchor_selector` directly warns at
import.
- On Python 3.12+ the warning skips importlib's frames
(`skip_file_prefixes`), so `importlib.import_module()` is attributed to
its caller.
- Python 3.10 and 3.11 have no such option, so there the warning still
names importlib.
- `import headroom.transforms` and every other export stay quiet.
- The tests cover attribute, `from`, plain and dynamic imports. They
restore `sys.modules`, the parent-package attribute and the export cache
through monkeypatch.
- Evidence: `rg -n
'AnchorSelector|anchor_selector|compute_item_hash|calculate_information_score'
headroom plugins sdk examples benchmarks scripts docs tests`, plus the
consumer repos, finds only the module itself, its lazy exports, the Rust
port and an unpublished wiki design plan.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ pytest tests/test_transforms_package.py tests/test_package_init_lazy.py tests/test_smart_crusher*.py tests/test_transforms/test_smart_crusher*.py
110 passed in 6.09s
$ pytest tests/test_transforms_package.py   # with the previous commit's product code
3 failed, 2 passed (double warning on from-import; importlib-attributed dynamic import)
$ python3.10 -c "compile(anchor_selector.py)"   # 3.10 fallback branch parses
3.10.21 compiles
$ ruff check / format: All checks passed;  mypy: Success
```

## Real Behavior Proof

- Environment: macOS, Python 3.12, repo `.venv`, this branch's worktree
with the prebuilt `headroom._core`. Temp `HOME`,
`HEADROOM_WORKSPACE_DIR` and `CODEX_HOME`; nothing touched the real
home.
- Exact command / steps: (1) shared smoke harness: a real proxy from
this checkout against a local fake upstream, with one Anthropic and one
OpenAI request carrying a compressible tool result (`smoke.sh
<worktree>`); (2) `python -W always -c 'from headroom.transforms import
AnchorSelector'`, plus a script that calls
`importlib.import_module('headroom.transforms.anchor_selector')`.
- Observed result: The proxy serves both requests (200) with savings.
The from-import warns once at `<string>:2`, and the dynamic import is
attributed to `plugin_loader.py:2`, not to importlib. Output below.
- Not tested: The full test suite on Python 3.10/3.11 (only the fallback
branch was compile-checked there).

```text
branch: cleanup/transforms-deprecate-anchor-selector @ 8f2f5e37
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines ($SMOKE/ws/logs/proxy-50549.log):
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you configured, operator-configured local endpoints, loopback health probes.
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.
(smoke dir: $SMOKE)
```

```text
$ python -W always -c "from headroom.transforms import AnchorSelector"
<string>:2: DeprecationWarning: headroom.transforms.AnchorSelector is deprecated and will be removed in a future release; it has no replacement (SmartCrusher's anchor selection runs in Rust).
ok
$ python -W always plugin_loader.py   # importlib.import_module("headroom.transforms.anchor_selector")
plugin_loader.py:2: DeprecationWarning: 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).
  importlib.import_module("headroom.transforms.anchor_selector")
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: Not applicable; no rollout-managed behaviour
is touched.
- Stable/default behavior changed: Only a DeprecationWarning when the
deprecated names are used. Return values do not change.
- Kill switch / disable path: Not applicable; the warning is a standard
DeprecationWarning and can be filtered with `warnings`.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this single commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

Not applicable.

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

Documentation changes are not in this PR. They are recorded in the
cleanup docs ledger for the single follow-up docs PR.

Deprecated (not removed): `AnchorSelector`, `AnchorStrategy`,
`AnchorWeights`, `DataPattern`, `calculate_information_score`,
`compute_item_hash`, and the module
`headroom.transforms.anchor_selector`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
Tejas Chopra
2026-10-10 09:03:24 -07:00
committed by GitHub
parent 2e497cbec3
commit 9b1971dd82
3 changed files with 112 additions and 0 deletions
+22
View File
@@ -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
+25
View File
@@ -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.
+65
View File
@@ -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",
)
@pytest.fixture
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)
@pytest.mark.usefixtures("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__
@pytest.mark.usefixtures("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__
@pytest.mark.usefixtures("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__
@pytest.mark.usefixtures("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__