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:
Tejas Chopra
2026-10-10 09:03:03 -07:00
committed by GitHub
co-authored by Claude Opus 5.5
parent fc8ff5a761
commit e4a1ec19be
6 changed files with 57 additions and 4 deletions
+15 -2
View File
@@ -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]
+13
View File
@@ -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,
+11
View File
@@ -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]
+14
View File
@@ -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
+2 -1
View File
@@ -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)