mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
refactor(transforms): deprecate unused compress_with_stats, extract_batch and align_for_cache (#4098)
## Description
`DiffCompressor.compress_with_stats`, `HTMLExtractor.extract_batch` and
`cache_aligner.align_for_cache` are public. The first two are methods on
classes exported from `headroom.transforms`, and the third's docstring
called it a stable public API. None is called anywhere in Headroom, the
plugins or the consumer repos; only tests call them. Each now emits a
`DeprecationWarning` that names the 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
- `DiffCompressor.compress_with_stats` warns and points to
`DiffCompressor.compress`. Unlike `compress()`, it never wrote its CCR
entry to the compression store, so a retrieval marker in its output
could dangle. The docstring now says so.
- `HTMLExtractor.extract_batch` warns and points to calling
`HTMLExtractor.extract` per page.
- `align_for_cache` warns and points to
`CacheAligner(config).apply(messages, tokenizer)` and the
`stable_prefix_hash:` marker.
- The existing tests now assert the warnings. A new test checks that
`align_for_cache` warns at the caller and still returns the messages and
the hash.
## 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_cache_aligner_detector_only.py tests/test_cache_aligner_prefix_stability.py tests/test_transforms/test_html_extractor.py tests/test_transforms/test_diff_compressor_rust_parity.py tests/test_transforms/test_diff_compressor.py
118 passed in 3.87s
$ 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 'align_for_cache(...);
DiffCompressor().compress_with_stats(...)'`.
- Observed result: The proxy serves both requests (200) with the same
savings as main. Each deprecated call emits one DeprecationWarning
attributed to the caller and still returns its result. Output below.
- Not tested: Third-party callers; none is known.
```text
branch: cleanup/transforms-deprecate-unused-methods @ a3e57303
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-51205.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 "align_for_cache([...]); DiffCompressor().compress_with_stats(...)"
<string>:4: DeprecationWarning: align_for_cache is deprecated and will be removed in a future release; use CacheAligner(config).apply(messages, tokenizer) and read the stable_prefix_hash: marker from markers_inserted.
<string>:5: DeprecationWarning: DiffCompressor.compress_with_stats is deprecated and will be removed in a future release; use DiffCompressor.compress instead.
ok
```
## 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 methods are called.
- 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): `DiffCompressor.compress_with_stats`,
`HTMLExtractor.extract_batch`, `cache_aligner.align_for_cache`. The
warnings fire on every call, which is standard. Python's default warning
filters show each one once per call site.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
fc8ff5a761
commit
e4a1ec19be
@@ -30,6 +30,7 @@ import binascii
|
||||
import json
|
||||
import logging
|
||||
import uuid as _uuid
|
||||
import warnings
|
||||
from dataclasses import dataclass
|
||||
from datetime import datetime
|
||||
from typing import Any
|
||||
@@ -395,9 +396,21 @@ def align_for_cache(
|
||||
) -> tuple[list[dict[str, Any]], str]:
|
||||
"""Convenience wrapper that runs detection and returns the unchanged messages.
|
||||
|
||||
Kept as a stable public API; the second tuple element is the stable
|
||||
prefix hash for callers that want to track cache prefix drift.
|
||||
The second tuple element is the stable prefix hash for callers that want
|
||||
to track cache prefix drift.
|
||||
|
||||
.. deprecated::
|
||||
Unused inside Headroom; will be removed in a future release. Use
|
||||
``CacheAligner(config).apply(messages, tokenizer)`` and read the
|
||||
``stable_prefix_hash:`` marker from ``markers_inserted``.
|
||||
"""
|
||||
warnings.warn(
|
||||
"align_for_cache is deprecated and will be removed in a future release; use "
|
||||
"CacheAligner(config).apply(messages, tokenizer) and read the stable_prefix_hash: "
|
||||
"marker from markers_inserted.",
|
||||
DeprecationWarning,
|
||||
stacklevel=2,
|
||||
)
|
||||
cfg = config or CacheAlignerConfig()
|
||||
aligner = CacheAligner(cfg)
|
||||
tokenizer = Tokenizer(EstimatingTokenCounter()) # type: ignore[arg-type]
|
||||
|
||||
@@ -21,6 +21,7 @@ fallback. Build it locally with `scripts/build_rust_extension.sh`
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import warnings
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
@@ -159,7 +160,19 @@ class DiffCompressor:
|
||||
etc.) alongside the result. Stats is the raw PyO3 wrapper — no
|
||||
Python equivalent to mirror to. Typed as `Any` because the PyO3
|
||||
class has no Python type stub.
|
||||
|
||||
.. deprecated::
|
||||
Unused inside Headroom; will be removed in a future release. Use
|
||||
:meth:`compress`. Unlike ``compress()``, this method does not write
|
||||
the CCR entry to the compression store, so a retrieval marker in
|
||||
its output may not resolve.
|
||||
"""
|
||||
warnings.warn(
|
||||
"DiffCompressor.compress_with_stats is deprecated and will be removed in a future "
|
||||
"release; use DiffCompressor.compress instead.",
|
||||
DeprecationWarning,
|
||||
stacklevel=2,
|
||||
)
|
||||
r, stats = self._rust.compress_with_stats(content, context)
|
||||
result = DiffCompressionResult(
|
||||
compressed=r.compressed,
|
||||
|
||||
@@ -17,6 +17,7 @@ Uses trafilatura for robust extraction - it handles:
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import warnings
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
@@ -187,12 +188,22 @@ class HTMLExtractor:
|
||||
) -> list[HTMLExtractionResult]:
|
||||
"""Extract content from multiple HTML pages.
|
||||
|
||||
.. deprecated::
|
||||
Unused inside Headroom; will be removed in a future release.
|
||||
Call :meth:`extract` for each page instead.
|
||||
|
||||
Args:
|
||||
html_contents: List of (html, url) tuples.
|
||||
|
||||
Returns:
|
||||
List of HTMLExtractionResult in same order as input.
|
||||
"""
|
||||
warnings.warn(
|
||||
"HTMLExtractor.extract_batch is deprecated and will be removed in a future release; "
|
||||
"call HTMLExtractor.extract for each page instead.",
|
||||
DeprecationWarning,
|
||||
stacklevel=2,
|
||||
)
|
||||
return [self.extract(html, url) for html, url in html_contents]
|
||||
|
||||
|
||||
|
||||
@@ -335,3 +335,17 @@ def test_no_regex_imported() -> None:
|
||||
assert "re" not in mod.__dict__, (
|
||||
"headroom.transforms.cache_aligner must not depend on the regex module"
|
||||
)
|
||||
|
||||
|
||||
def test_align_for_cache_is_deprecated_and_still_works() -> None:
|
||||
from headroom.transforms.cache_aligner import align_for_cache
|
||||
|
||||
messages = [
|
||||
{"role": "system", "content": "You are a helpful assistant."},
|
||||
{"role": "user", "content": "hi"},
|
||||
]
|
||||
with pytest.warns(DeprecationWarning, match="align_for_cache is deprecated") as record:
|
||||
out, stable_hash = align_for_cache(messages)
|
||||
assert record[0].filename == __file__
|
||||
assert out == messages
|
||||
assert isinstance(stable_hash, str)
|
||||
|
||||
@@ -94,7 +94,8 @@ def test_compress_with_stats_returns_python_dataclass_and_pyo3_stats():
|
||||
diff = (
|
||||
"diff --git a/a.py b/a.py\n--- a/a.py\n+++ b/a.py\n@@ -1 +1 @@\n-old\n+new\n"
|
||||
) + "# pad\n" * 60
|
||||
result, stats = DiffCompressor(DiffCompressorConfig()).compress_with_stats(diff)
|
||||
with pytest.warns(DeprecationWarning, match="compress_with_stats is deprecated"):
|
||||
result, stats = DiffCompressor(DiffCompressorConfig()).compress_with_stats(diff)
|
||||
|
||||
assert isinstance(result, DiffCompressionResult)
|
||||
assert stats.input_lines >= 60
|
||||
|
||||
@@ -538,7 +538,8 @@ class TestBatchExtraction:
|
||||
),
|
||||
]
|
||||
|
||||
results = extractor.extract_batch(pages)
|
||||
with pytest.warns(DeprecationWarning, match="extract_batch is deprecated"):
|
||||
results = extractor.extract_batch(pages)
|
||||
|
||||
assert len(results) == 3
|
||||
assert all(isinstance(r, HTMLExtractionResult) for r in results)
|
||||
|
||||
Reference in New Issue
Block a user