mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
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:
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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__
|
||||
|
||||
Reference in New Issue
Block a user