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): F2.2 c2/3 — wire toin_read_only gate + extend policy_selected log
chopratejas5b38cbf8a79d
diff --git a/crates/headroom-proxy/src/proxy.rs b/crates/headroom-proxy/src/proxy.rsindex 72c53ab47..9f801aa03 100644--- a/crates/headroom-proxy/src/proxy.rs+++ b/crates/headroom-proxy/src/proxy.rs@@ -431,6 +431,13 @@ pub(crate) async fn forward_http(// c3/6 adds `enforcement` so the dashboard can split "policy// resolved as PAYG because mode is PAYG" from "policy resolved as// PAYG because the enforcement flag is off."+ //+ // F2.2 c2/3: extend the structured fields with the three new+ // tuning fields so the bake dashboard has per-mode observability+ // for the F2.2-followup tune. ``volatile_token_threshold`` /+ // ``max_lossy_ratio`` are plumbed-but-unconsumed today, so the+ // log lines are the only signal that the values are flowing+ // correctly through the proxy → handlers → transforms path.tracing::debug!(event = "policy_selected",request_id = %request_id,@@ -438,6 +445,9 @@ pub(crate) async fn forward_http(enforcement = state.config.auth_mode_policy_enforcement.as_str(),live_zone_only = policy.live_zone_only,cache_aligner_enabled = policy.cache_aligner_enabled,+ volatile_token_threshold = policy.volatile_token_threshold,+ max_lossy_ratio = policy.max_lossy_ratio,+ toin_read_only = policy.toin_read_only,"compression policy resolved");diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex add7b9402..ad218d46c 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -652,6 +652,17 @@ class ContentRouter(Transform):# TOIN integration for cross-strategy learningself._toin: Any = None+ # F2.2: per-request CompressionPolicy, set from+ # ``kwargs["compression_policy"]`` at the start of ``apply()``+ # and read by ``_record_to_toin`` to gate TOIN writes when+ # ``policy.toin_read_only`` is true (Subscription mode).+ # Defaults to ``None`` so direct ``compress()`` callers (e.g.+ # tests, hand-written pipelines that don't go through the+ # proxy) keep pre-F2.2 behaviour: TOIN writes are not gated.+ # Same pattern the existing ``_runtime_target_ratio`` /+ # ``_runtime_kompress_model`` fields below use.+ self._runtime_compression_policy: Any = None+self._cache = CompressionCache()def _record_to_toin(@@ -687,6 +698,22 @@ class ContentRouter(Transform):if original_tokens <= compressed_tokens:return+ # F2.2 gate: when the active CompressionPolicy says+ # ``toin_read_only=True`` (Subscription auth mode), don't+ # mutate the TOIN learning pool from this request. Direct+ # ``compress()`` callers don't go through ``apply()`` and+ # have ``self._runtime_compression_policy is None`` — those+ # keep their pre-F2.2 write-enabled behaviour.+ policy = self._runtime_compression_policy+ if policy is not None and policy.toin_read_only:+ logger.debug(+ "ContentRouter: skipping TOIN record_compression for %s "+ "— policy.toin_read_only=True (auth_mode resolved as "+ "Subscription, F2.2 gate)",+ strategy.value,+ )+ return+try:# Lazy load TOINif self._toin is None:@@ -1509,6 +1536,12 @@ class ContentRouter(Transform):# Store runtime options on self for access by _route_and_compress_blockself._runtime_target_ratio: float | None = kwargs.get("target_ratio")self._runtime_kompress_model: str | None = kwargs.get("kompress_model")+ # F2.2: capture the per-request CompressionPolicy so+ # ``_record_to_toin`` can gate TOIN writes on+ # ``policy.toin_read_only``. ``None`` when the caller didn't+ # pass a policy — ``_record_to_toin`` treats that as "no gate"+ # to preserve pre-F2.2 behaviour for non-proxy callers.+ self._runtime_compression_policy = kwargs.get("compression_policy")tokens_before = sum(tokenizer.count_text(str(m.get("content", ""))) for m in messages)context = kwargs.get("context", "")diff --git a/headroom/transforms/smart_crusher.py b/headroom/transforms/smart_crusher.pyindex 1cdbd1df0..b0af28839 100644--- a/headroom/transforms/smart_crusher.py+++ b/headroom/transforms/smart_crusher.py@@ -230,6 +230,18 @@ class SmartCrusher(Transform):self._toin: Any = Noneself._toin_load_failed = False+ # F2.2: per-request CompressionPolicy, set from+ # ``kwargs["compression_policy"]`` at the start of ``apply()``+ # and read by ``_record_to_toin`` to gate TOIN writes when+ # ``policy.toin_read_only`` is true (Subscription mode).+ # Defaults to ``None`` so the direct ``crush()`` / ``crush_array_json()``+ # / ``compact_document_json()`` entry points (which don't go+ # through ``apply()``) keep their pre-F2.2 behaviour: TOIN+ # writes are not gated. Same pattern as the existing+ # ``_runtime_target_ratio`` / ``_runtime_kompress_model``+ # fields in ContentRouter.+ self._runtime_compression_policy: Any = None+# Build the Rust crusher with every field from the Python# config, plus the relevance_threshold default (0.3) — the# Python dataclass doesn't carry that field; it lives on@@ -457,9 +469,29 @@ class SmartCrusher(Transform):implementation used. The router doesn't pass a tokenizer downthis far, and re-tokenizing here would dominate the recordingcost. Rough estimates are fine for learning aggregates.++ F2.2: when the active ``CompressionPolicy`` (set by+ ``apply()`` from ``kwargs["compression_policy"]``) has+ ``toin_read_only=True``, the write is skipped — Subscription+ users keep prompt-cache stability AND don't mutate the global+ TOIN learning pool from cache-sensitive traffic. Direct+ ``crush()`` / ``crush_array_json()`` callers don't set the+ policy, so they keep their pre-F2.2 write-enabled behaviour."""if self._toin_load_failed:return+ # F2.2 gate. Read the per-request policy set by ``apply()``;+ # ``None`` means we are not running under the Transform+ # protocol (direct caller via ``crush()``) and the legacy+ # write-enabled behaviour applies.+ policy = self._runtime_compression_policy+ if policy is not None and policy.toin_read_only:+ logger.debug(+ "SmartCrusher: skipping TOIN record_compression — "+ "policy.toin_read_only=True (auth_mode resolved as "+ "Subscription, F2.2 gate)"+ )+ returntry:try:items = json.loads(original)@@ -782,6 +814,15 @@ class SmartCrusher(Transform):markers_inserted: list[str] = []warnings: list[str] = []+ # F2.2: capture the per-request CompressionPolicy so+ # ``_record_to_toin`` can gate TOIN writes on+ # ``policy.toin_read_only``. Same one-liner pattern the+ # ContentRouter uses for ``_runtime_target_ratio``. ``None``+ # when the caller didn't pass a policy (e.g. legacy direct-+ # apply callers in tests) — ``_record_to_toin`` treats that+ # as "no gate", matching pre-F2.2 behaviour.+ self._runtime_compression_policy = kwargs.get("compression_policy")+query_context = self._extract_context_from_messages(result_messages)crushed_count = 0frozen_message_count = kwargs.get("frozen_message_count", 0)diff --git a/tests/test_compression_policy_toin_gate.py b/tests/test_compression_policy_toin_gate.pynew file mode 100644index 000000000..6724fdc32--- /dev/null+++ b/tests/test_compression_policy_toin_gate.py@@ -0,0 +1,289 @@+"""F2.2: TOIN write-gate tests for the per-mode CompressionPolicy.++When ``CompressionPolicy.toin_read_only`` is ``True`` (Subscription+auth mode), TOIN must serve cached recommendations but NEVER write new+pattern observations from this request. PAYG / OAuth keep writing so+the network effect keeps growing. The gate is read at the+``record_compression`` call site in ``smart_crusher.py`` and+``content_router.py``.++These tests mirror the structure of+``tests/test_smart_crusher_toin_attachment.py`` (the F2.1-era TOIN+re-attachment regression suite) so a future contributor can locate the+expected behaviour by name.++Behaviour matrix:++| Mode | toin_read_only | record_compression called? |+|--------------|----------------|----------------------------|+| Payg | False | yes |+| OAuth | False | yes |+| Subscription | True | NO |++Direct callers (those that call ``crush()`` / ``crush_array_json()``+without going through ``apply()``) don't set+``self._runtime_compression_policy``, so they keep their pre-F2.2+write-enabled behaviour. That's a deliberate compatibility decision —+non-proxy callers have no auth context.+"""++from __future__ import annotations++import json+import tempfile+from pathlib import Path++import pytest++from headroom.proxy.auth_mode import AuthMode+from headroom.telemetry.toin import TOINConfig, get_toin, reset_toin+from headroom.tokenizer import Tokenizer+from headroom.tokenizers import EstimatingTokenCounter+from headroom.transforms.compression_policy import policy_for_mode+++def _has_core() -> bool:+ """Match the pattern in ``test_smart_crusher_rust_parity.py``.++ SmartCrusher's __init__ hard-imports ``headroom._core`` (the Rust+ PyO3 wheel). On dev machines or CI lanes that haven't run+ ``scripts/build_rust_extension.sh``, the wheel is absent. Skip the+ SmartCrusher-touching tests rather than fail loudly — the+ ContentRouter tests don't need the wheel and exercise the same+ F2.2 gate code path.+ """+ try:+ from headroom._core import SmartCrusher # noqa: F401++ return True+ except ImportError:+ return False+++_skip_no_core = pytest.mark.skipif(+ not _has_core(),+ reason="headroom._core wheel not installed (run `scripts/build_rust_extension.sh`)",+)+++def fresh_toin():+ """Per-test TOIN instance backed by a tempdir to avoid global drift."""+ reset_toin()+ with tempfile.TemporaryDirectory() as tmpdir:+ storage = str(Path(tmpdir) / "toin.json")+ toin = get_toin(+ TOINConfig(+ storage_path=storage,+ auto_save_interval=0,+ )+ )+ yield toin+ reset_toin()+++def _bigger_array(n: int = 60) -> str:+ """JSON array of `n` dicts, sized to trigger crushing.++ Mirrors the helper in ``test_smart_crusher_toin_attachment.py`` so+ these tests use the same shape and any "didn't trigger compression"+ skip lines up with the existing suite.+ """+ items = [{"status": "ok", "tag": "x", "n": i} for i in range(n)]+ return json.dumps(items)+++def _wrap_in_tool_message(payload: str) -> list[dict]:+ """Build the OpenAI-style ``role=tool`` message ``apply()`` walks."""+ return [{"role": "tool", "content": payload, "tool_call_id": "t1"}]+++def _tokenizer() -> Tokenizer:+ return Tokenizer(EstimatingTokenCounter()) # type: ignore[arg-type]+++# ─── SmartCrusher: apply() with policy ──────────────────────────────────+++@_skip_no_core+def test_smart_crusher_payg_policy_writes_to_toin(fresh_toin):+ """PAYG: ``toin_read_only=False`` → record_compression IS called."""+ from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig++ crusher = SmartCrusher(SmartCrusherConfig())+ messages = _wrap_in_tool_message(_bigger_array(60))+ pre = sum(p.total_compressions for p in fresh_toin._patterns.values())++ policy = policy_for_mode(AuthMode.PAYG)+ assert policy.toin_read_only is False # baseline sanity+ result = crusher.apply(messages, _tokenizer(), compression_policy=policy)++ if not result.transforms_applied:+ pytest.skip("payload didn't trigger compression — bump the size")+ post = sum(p.total_compressions for p in fresh_toin._patterns.values())+ assert post > pre, "PAYG should write to TOIN (network effect)"+++@_skip_no_core+def test_smart_crusher_oauth_policy_writes_to_toin(fresh_toin):+ """OAuth: identical to PAYG in F2.2 — writes enabled."""+ from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig++ crusher = SmartCrusher(SmartCrusherConfig())+ messages = _wrap_in_tool_message(_bigger_array(60))+ pre = sum(p.total_compressions for p in fresh_toin._patterns.values())++ policy = policy_for_mode(AuthMode.OAUTH)+ assert policy.toin_read_only is False+ result = crusher.apply(messages, _tokenizer(), compression_policy=policy)++ if not result.transforms_applied:+ pytest.skip("payload didn't trigger compression — bump the size")+ post = sum(p.total_compressions for p in fresh_toin._patterns.values())+ assert post > pre, "OAuth (matches PAYG today) should write to TOIN"+++@_skip_no_core+def test_smart_crusher_subscription_policy_skips_toin_write(fresh_toin):+ """Subscription: ``toin_read_only=True`` → record_compression is NOT called.++ This is THE behaviour change of F2.2 — keep the learning pool+ consistent for cache-stability-sensitive traffic.+ """+ from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig++ crusher = SmartCrusher(SmartCrusherConfig())+ messages = _wrap_in_tool_message(_bigger_array(60))+ pre = sum(p.total_compressions for p in fresh_toin._patterns.values())++ policy = policy_for_mode(AuthMode.SUBSCRIPTION)+ assert policy.toin_read_only is True # baseline sanity+ result = crusher.apply(messages, _tokenizer(), compression_policy=policy)++ # Compression itself should still complete — this gate is on the+ # learning side only, not the compression path.+ if not result.transforms_applied:+ pytest.skip("payload didn't trigger compression — bump the size")+ post = sum(p.total_compressions for p in fresh_toin._patterns.values())+ assert post == pre, (+ "Subscription MUST NOT write to TOIN — load-bearing for keeping "+ "the learning pool consistent across cache-sensitive traffic"+ )+++@_skip_no_core+def test_smart_crusher_no_policy_keeps_legacy_write_behaviour(fresh_toin):+ """Direct ``apply()`` call without ``compression_policy`` keeps+ pre-F2.2 behaviour: TOIN writes are not gated.++ Many test fixtures and non-proxy callers don't pass a policy; they+ must continue to feed the learning pool exactly as they did+ before F2.2.+ """+ from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig++ crusher = SmartCrusher(SmartCrusherConfig())+ messages = _wrap_in_tool_message(_bigger_array(60))+ pre = sum(p.total_compressions for p in fresh_toin._patterns.values())++ # No `compression_policy` kwarg.+ result = crusher.apply(messages, _tokenizer())++ if not result.transforms_applied:+ pytest.skip("payload didn't trigger compression — bump the size")+ post = sum(p.total_compressions for p in fresh_toin._patterns.values())+ assert post > pre, "no policy → legacy write-enabled behaviour"+++# ─── ContentRouter: apply() captures the policy ─────────────────────────+++def test_content_router_apply_stores_runtime_policy():+ """``ContentRouter.apply()`` must populate+ ``self._runtime_compression_policy`` from kwargs so+ ``_record_to_toin`` can read it.++ We don't assert TOIN behaviour here (the router routes most JSON+ arrays to SmartCrusher, which has its own gate already covered+ above); the load-bearing thing for the parity guard is that the+ field is wired through.+ """+ from headroom.transforms.content_router import ContentRouter++ router = ContentRouter()+ # Sanity: the field exists on a fresh instance and starts None.+ assert router._runtime_compression_policy is None++ policy = policy_for_mode(AuthMode.SUBSCRIPTION)+ # Empty-message apply is fine — the field assignment happens+ # before the message walk, so we don't need a payload that+ # actually compresses.+ router.apply([], _tokenizer(), compression_policy=policy)+ assert router._runtime_compression_policy is policy, (+ "ContentRouter.apply() must capture the policy onto self so _record_to_toin can read it"+ )+++def test_content_router_subscription_skips_toin_record(fresh_toin):+ """ContentRouter._record_to_toin returns early when+ policy.toin_read_only is True.++ We exercise the gate directly rather than building a fixture that+ routes to a non-SmartCrusher compressor — both are equivalent+ coverage for the gate, and the direct call avoids the routing+ flake from ``test_smart_crusher_toin_attachment.py``'s comments.+ """+ from headroom.transforms.content_router import (+ CompressionStrategy,+ ContentRouter,+ )++ router = ContentRouter()+ router._runtime_compression_policy = policy_for_mode(AuthMode.SUBSCRIPTION)++ pre = sum(p.total_compressions for p in fresh_toin._patterns.values())+ # Pick TEXT strategy (not SMART_CRUSHER, which has its own+ # early-return). With Subscription policy, the F2.2 gate fires+ # and the call returns before ever loading TOIN.+ router._record_to_toin(+ strategy=CompressionStrategy.TEXT,+ content="some text content",+ compressed="compressed",+ original_tokens=100,+ compressed_tokens=50,+ )+ post = sum(p.total_compressions for p in fresh_toin._patterns.values())+ assert post == pre, "Subscription policy must skip ContentRouter TOIN write"+++def test_content_router_payg_records_to_toin(fresh_toin):+ """PAYG policy → ContentRouter._record_to_toin proceeds to the+ real TOIN call. Asserts the gate doesn't accidentally fire when+ ``toin_read_only=False``.+ """+ from headroom.transforms.content_router import (+ CompressionStrategy,+ ContentRouter,+ )++ router = ContentRouter()+ router._runtime_compression_policy = policy_for_mode(AuthMode.PAYG)++ pre = sum(p.total_compressions for p in fresh_toin._patterns.values())+ router._record_to_toin(+ strategy=CompressionStrategy.TEXT,+ content="some text content with structure that learns",+ compressed="compressed shorter",+ original_tokens=100,+ compressed_tokens=50,+ )+ post = sum(p.total_compressions for p in fresh_toin._patterns.values())+ # Real TOIN write should happen unless _create_content_signature+ # returns None (it can for malformed inputs). We accept either+ # "post > pre" (signature succeeded) OR "post == pre with a+ # signature-None path"; the load-bearing assertion is that the+ # F2.2 gate did NOT fire (which it would with toin_read_only=True+ # regardless of signature).+ assert post >= pre, (+ "PAYG must not be blocked by the F2.2 gate — write should happen or fall through naturally"+ )