refactor(transforms): deprecate align_for_cache

Its docstring called it a stable public API, so it is deprecated rather than deleted. Nothing
in Headroom calls it. The warning points to CacheAligner.apply and the stable_prefix_hash:
marker. Adds a test that it warns and still returns the messages and hash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Assisted-by: claude-code:claude-opus-5-5
Headline-Session: 6e77a807-8dd4-4a77-a2fa-ddce6dc2515e
Headline-AI-Share: 41% strict / 41% weighted
This commit is contained in:
Tejas Chopra
2026-10-09 18:39:12 -07:00
co-authored by Claude Opus 5.5
parent 33eaabf95b
commit a3e573034f
2 changed files with 29 additions and 2 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]
+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)