Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(transforms): Python parity port of CompressionPolicy + cache_aligner gate (F2.1 c4/5)
chopratejasde8e24599039
diff --git a/headroom/transforms/cache_aligner.py b/headroom/transforms/cache_aligner.pyindex f6aba3ef0..2faa9efe7 100644--- a/headroom/transforms/cache_aligner.py+++ b/headroom/transforms/cache_aligner.py@@ -239,9 +239,23 @@ class CacheAligner(Transform):Detection is cheap; we run it whenever ``enabled`` is set so thewarning log line is emitted on every relevant turn.++ Phase F PR-F2.1 c4/5: when the request's+ :class:`~headroom.transforms.compression_policy.CompressionPolicy`+ is passed via ``kwargs["compression_policy"]`` and has+ ``cache_aligner_enabled=False`` (Subscription auth mode under+ the enforcement flag), this method returns ``False`` so the+ detector is skipped for that request. The hidden state+ ``self._previous_prefix_hash`` is NOT cleared on skip — the+ field is per-pipeline-instance, not per-request, so clearing+ it would race with concurrent PAYG requests on the same+ pipeline (which is the production shape)."""if not self.config.enabled:return False+ policy = kwargs.get("compression_policy")+ if policy is not None and not policy.cache_aligner_enabled:+ return Falsefor msg in messages:if msg.get("role") == "system":content = msg.get("content", "")diff --git a/headroom/transforms/compression_policy.py b/headroom/transforms/compression_policy.pynew file mode 100644index 000000000..a52e19f1d--- /dev/null+++ b/headroom/transforms/compression_policy.py@@ -0,0 +1,80 @@+"""Per-auth-mode compression policy — Phase F PR-F2.1, Python parity.++Hand-mirrored port of `headroom_core::compression_policy::CompressionPolicy`+(Rust). The Rust crate is the source of truth; this module exists so+the Python proxy's `TransformPipeline` (which still runs `CacheAligner`+and other detector-only transforms) can read the same per-mode flags+the Rust dispatcher does.++A parity test (`tests/test_compression_policy.py`) instantiates one of+each variant and asserts the field map matches what the Rust unit+tests assert. F2.2 should consider exposing the Rust struct via PyO3+to retire this hand-mirror — that's deliberately out of scope here so+F2.1 can ship.++See `crates/headroom-core/src/compression_policy.rs` for the canonical+docstring.+"""++from __future__ import annotations++from dataclasses import dataclass++from headroom.proxy.auth_mode import AuthMode+++@dataclass(frozen=True, slots=True)+class CompressionPolicy:+ """Per-auth-mode policy that downstream compression stages consult.++ Two fields in F2.1 — `live_zone_only` and `cache_aligner_enabled`.+ F2.2 will add tuning fields (per-mode volatile threshold,+ max-lossy-ratio cap, per-mode TOIN read-only flag) once telemetry+ from F2.1's bake on `main` shows what each mode actually costs/saves.+ """++ live_zone_only: bool+ """When True, transforms MUST NOT modify bytes outside the post-+ cache-marker live zone. The Rust live-zone dispatcher is already+ live-zone-only by construction, so this flag is effectively a+ no-op on the Rust path; it exists for the Python TransformPipeline+ where transforms like CacheAligner inspect the cached prefix."""++ cache_aligner_enabled: bool+ """When False, the CacheAligner transform's `should_apply` MUST+ return False — that's the load-bearing F2.1 gate for the cache-+ instability complaints in #327 / #388."""+++def policy_for_mode(mode: AuthMode) -> CompressionPolicy:+ """Resolve the F2.1 policy for an auth mode.++ PAYG and OAuth are identical in F2.1 (aggressive: live-zone-not-+ only, cache-aligner on). Subscription is the user-visible win:+ live-zone-only with cache aligner disabled.++ F2.2 may diverge OAuth from PAYG once telemetry is collected.+ """+ if mode == AuthMode.PAYG:+ return CompressionPolicy(live_zone_only=False, cache_aligner_enabled=True)+ if mode == AuthMode.OAUTH:+ # Identical to PAYG in F2.1. The parity test in+ # `tests/test_compression_policy.py` is the canary that+ # catches a future divergence and forces a deliberate+ # update there + in the Rust crate.+ return CompressionPolicy(live_zone_only=False, cache_aligner_enabled=True)+ if mode == AuthMode.SUBSCRIPTION:+ return CompressionPolicy(live_zone_only=True, cache_aligner_enabled=False)+ raise ValueError(f"Unhandled AuthMode variant: {mode!r}")+++def policy_default_payg() -> CompressionPolicy:+ """The PAYG-equivalent policy used when the+ ``HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT`` flag is disabled+ (default in F2.1 c1-c4; flips to enabled in c5/5).++ Centralised so the proxy handlers do not duplicate the constant,+ and so a future change to PAYG semantics propagates to both the+ enforcement-on and enforcement-off paths.+ """+ return policy_for_mode(AuthMode.PAYG)diff --git a/tests/test_cache_aligner_detector_only.py b/tests/test_cache_aligner_detector_only.pyindex 5001a5b46..8579797fd 100644--- a/tests/test_cache_aligner_detector_only.py+++ b/tests/test_cache_aligner_detector_only.py@@ -194,6 +194,40 @@ def test_should_apply_false_without_system_message(tokenizer: Tokenizer) -> Noneassert not aligner.should_apply(messages, tokenizer)+def test_should_apply_false_when_policy_disables_aligner(tokenizer: Tokenizer) -> None:+ """F2.1 c4/5: ``compression_policy.cache_aligner_enabled=False``+ must disable the detector even when content + config would+ otherwise opt in.++ This is the canary that the per-auth-mode plumbing actually+ reaches CacheAligner. A regression here means subscription+ requests would silently keep updating+ ``self._previous_prefix_hash`` and emitting volatility warnings,+ which are the exact log lines #327/#388 reporters complained+ about.+ """+ from headroom.transforms.compression_policy import CompressionPolicy++ messages = _system_user_messages("Session: 550e8400-e29b-41d4-a716-446655440000")+ aligner = CacheAligner(CacheAlignerConfig(enabled=True))+ # Sanity: without a policy, the detector opts in.+ assert aligner.should_apply(messages, tokenizer)+ # F2.1 gate: with the subscription policy, the detector opts out.+ sub_policy = CompressionPolicy(live_zone_only=True, cache_aligner_enabled=False)+ assert not aligner.should_apply(messages, tokenizer, compression_policy=sub_policy)+++def test_should_apply_true_when_policy_enables_aligner(tokenizer: Tokenizer) -> None:+ """F2.1 c4/5: ``compression_policy.cache_aligner_enabled=True``+ must NOT short-circuit. PAYG/OAuth keep current behaviour."""+ from headroom.transforms.compression_policy import CompressionPolicy++ messages = _system_user_messages("Session: 550e8400-e29b-41d4-a716-446655440000")+ aligner = CacheAligner(CacheAlignerConfig(enabled=True))+ payg_policy = CompressionPolicy(live_zone_only=False, cache_aligner_enabled=True)+ assert aligner.should_apply(messages, tokenizer, compression_policy=payg_policy)++# ---------------------------------------------------------------------------# Pure-function detection tests# ---------------------------------------------------------------------------diff --git a/tests/test_compression_policy.py b/tests/test_compression_policy.pynew file mode 100644index 000000000..b2a1d15e3--- /dev/null+++ b/tests/test_compression_policy.py@@ -0,0 +1,92 @@+"""Tests for the Python ``CompressionPolicy`` and its parity with Rust.++The Python module is a hand-mirror of+``headroom_core::compression_policy::CompressionPolicy``. These tests+pin both halves: that the per-mode values are right, and that the+Python and Rust sides agree on the field map. F2.2 will likely retire+the hand-mirror via PyO3 — until then, this file is the canary.+"""++from __future__ import annotations++import pytest++from headroom.proxy.auth_mode import AuthMode+from headroom.transforms.compression_policy import (+ CompressionPolicy,+ policy_default_payg,+ policy_for_mode,+)+++class TestCompressionPolicyForMode:+ """Per-mode field assertions. Mirrors the three Rust unit tests in+ `crates/headroom-core/src/compression_policy.rs`.+ """++ def test_payg_is_aggressive(self):+ p = policy_for_mode(AuthMode.PAYG)+ assert p.live_zone_only is False, "PAYG can touch outside live zone"+ assert p.cache_aligner_enabled is True, "PAYG runs cache aligner"++ def test_oauth_matches_payg_today(self):+ # Canary: when F2.2 diverges OAuth from PAYG, this test fails+ # and forces a deliberate update on BOTH sides (Rust + Python).+ oauth = policy_for_mode(AuthMode.OAUTH)+ payg = policy_for_mode(AuthMode.PAYG)+ assert oauth == payg, (+ "F2.1 ships OAuth=PAYG; F2.2 will diverge based on telemetry. "+ "If you are reading this assertion failure: also update "+ "crates/headroom-core/src/compression_policy.rs "+ "::oauth_matches_payg_today, otherwise the Rust + Python "+ "parities silently drift apart."+ )++ def test_subscription_disables_cache_aligner(self):+ p = policy_for_mode(AuthMode.SUBSCRIPTION)+ assert p.live_zone_only is True, "Subscription is live-zone-only"+ assert p.cache_aligner_enabled is False, (+ "Subscription MUST skip cache aligner — load-bearing for issues #327 / #388"+ )+++class TestPolicyDefaultPayg:+ """The constant used when the enforcement flag is disabled."""++ def test_default_payg_equals_for_mode_payg(self):+ assert policy_default_payg() == policy_for_mode(AuthMode.PAYG)+++class TestImmutability:+ """The struct is `frozen=True`; mutation must raise."""++ def test_policy_is_frozen(self):+ p = policy_for_mode(AuthMode.PAYG)+ with pytest.raises((AttributeError, Exception)):+ # Attempting to mutate a frozen dataclass raises+ # FrozenInstanceError (subclass of AttributeError on+ # CPython 3.10+). Catch both for compatibility.+ p.live_zone_only = True # type: ignore[misc]+++class TestRustParityFieldMap:+ """The Python policy must have the same fields as the Rust struct.++ The canonical Rust struct lives at+ ``crates/headroom-core/src/compression_policy.rs``. When you add a+ field there for F2.2, add it here AND update this test. Otherwise+ the parity silently drifts.+ """++ def test_field_set_matches_rust(self):+ # Hard-coded set — when Rust grows fields, this test fails until+ # Python catches up.+ expected_fields = {"live_zone_only", "cache_aligner_enabled"}+ actual_fields = {f.name for f in CompressionPolicy.__dataclass_fields__.values()}+ assert actual_fields == expected_fields, (+ f"Python CompressionPolicy fields drifted from Rust. "+ f"Expected exactly {expected_fields}, got {actual_fields}. "+ f"Update both `headroom/transforms/compression_policy.py` "+ f"and `crates/headroom-core/src/compression_policy.rs` in "+ f"the same commit."+ )