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
feat: net-cost cache mutation formula on CompressionPolicy (#856 P1) (#857)
Focused Instabilityd5f58026e2a8
diff --git a/crates/headroom-core/src/compression_policy.rs b/crates/headroom-core/src/compression_policy.rsindex b2f1f8395..278d98cbc 100644--- a/crates/headroom-core/src/compression_policy.rs+++ b/crates/headroom-core/src/compression_policy.rs@@ -130,6 +130,16 @@ pub(crate) const MAX_LOSSY_RATIO_PAYG: f32 = 0.45;/// Subscription: conservative cap at 25%. Cache stability over savings.pub(crate) const MAX_LOSSY_RATIO_SUBSCRIPTION: f32 = 0.25;+/// Anthropic prompt-cache write multiplier: a `cache_creation` token+/// costs 1.25× a plain input token (5-minute TTL tier). Input to the+/// net-cost mutation formula (#856).+pub const CACHE_WRITE_MULTIPLIER: f32 = 1.25;++/// Anthropic prompt-cache read multiplier: a `cache_read` token costs+/// 0.1× a plain input token. Input to the net-cost mutation formula+/// (#856).+pub const CACHE_READ_MULTIPLIER: f32 = 0.1;+/// Per-auth-mode policy that downstream compression stages consult.////// `Copy` because the struct is small POD (two `bool`s + a `u32` + an@@ -224,6 +234,79 @@ impl CompressionPolicy {pub fn live_zone_compression_enabled(&self) -> bool {true}++ /// Net gain (in plain-input-token cost units) of a mutation that+ /// removes `delta_t` tokens from a message whose cached suffix is+ /// `suffix_tokens` long (#856).+ ///+ /// Mutating message K invalidates every cached token after it: the+ /// suffix is re-written once at the write multiplier instead of+ /// being read at the read multiplier, costing+ /// `P_alive · (w − r) · S`. In exchange, `delta_t` tokens are gone+ /// from the current write and every one of the `expected_reads`+ /// remaining reads of the chain, saving `ΔT · (w + r·(R − 1))`.+ ///+ /// gain = ΔT · (w + r·(R − 1)) − P_alive · (w − r) · S+ ///+ /// Sanity anchors (Anthropic w=1.25, r=0.1), matching the unit+ /// tests below: a 2K shave under a 50K warm suffix needs ~276+ /// remaining reads to pay off (rarely profitable); a 50K shave+ /// under a 10K suffix is profitable from the first write (its+ /// break-even read count is negative); a live-zone edit (S = 0)+ /// is always profitable.+ ///+ /// Takes `&self` so a follow-up can apply per-mode margins; today+ /// the arithmetic is mode-independent. Inputs are clamped:+ /// `expected_reads` to `>= 0` (NaN → 0), `p_alive` to `[0, 1]`+ /// (NaN → 1, the conservative full-penalty assumption).+ pub fn net_mutation_gain(+ &self,+ delta_t: u32,+ suffix_tokens: u32,+ expected_reads: f32,+ p_alive: f32,+ ) -> f32 {+ let w = CACHE_WRITE_MULTIPLIER;+ let r = CACHE_READ_MULTIPLIER;+ // f32::max ignores NaN (returns the other operand), so NaN reads+ // land on 0.0; clamp would propagate NaN, so guard alive explicitly.+ let reads = expected_reads.max(0.0);+ let alive = if p_alive.is_nan() {+ 1.0+ } else {+ p_alive.clamp(0.0, 1.0)+ };+ (delta_t as f32) * (w + r * (reads - 1.0)) - alive * (w - r) * (suffix_tokens as f32)+ }++ /// Decision form of [`Self::net_mutation_gain`]: mutate iff the+ /// gain is strictly positive.+ pub fn should_mutate_deep(+ &self,+ delta_t: u32,+ suffix_tokens: u32,+ expected_reads: f32,+ p_alive: f32,+ ) -> bool {+ self.net_mutation_gain(delta_t, suffix_tokens, expected_reads, p_alive) > 0.0+ }++ /// Remaining-read count at which a warm-cache (P_alive = 1)+ /// mutation breaks even:+ ///+ /// R = ((w − r) / r) · (S/ΔT − 1) ≈ 11.5 · S/ΔT for S ≫ ΔT+ ///+ /// Useful for decision telemetry ("this edit pays off if the+ /// session lasts N more turns"). Returns 0 when `delta_t` is 0+ /// (no savings — callers gate on `delta_t > 0`).+ pub fn break_even_reads(&self, delta_t: u32, suffix_tokens: u32) -> f32 {+ if delta_t == 0 {+ return 0.0;+ }+ let w = CACHE_WRITE_MULTIPLIER;+ let r = CACHE_READ_MULTIPLIER;+ ((w - r) / r) * ((suffix_tokens as f32) / (delta_t as f32) - 1.0)+ }}#[cfg(test)]@@ -322,4 +405,80 @@ mod tests {);}}++ // --- Net-cost mutation formula (#856). Scenario values are golden:+ // tests/test_compression_policy.py asserts the identical numbers+ // against the Python hand-mirror, so a drift in either side trips+ // the parity pair loudly.++ #[test]+ fn net_gain_small_shave_deep_suffix_is_loss() {+ // Shave 2K under a 50K warm suffix at R=10 remaining reads:+ // 2000·(1.25 + 0.1·9) − 1.0·1.15·50000 = 4300 − 57500 = −53200.+ let p = CompressionPolicy::for_mode(AuthMode::Payg);+ let gain = p.net_mutation_gain(2_000, 50_000, 10.0, 1.0);+ assert!((gain - (-53_200.0)).abs() < 1.0, "gain = {gain}");+ assert!(!p.should_mutate_deep(2_000, 50_000, 10.0, 1.0));+ }++ #[test]+ fn net_gain_big_shave_shallow_suffix_is_win() {+ // Shave 50K under a 10K warm suffix at R=3:+ // 50000·(1.25 + 0.1·2) − 1.0·1.15·10000 = 72500 − 11500 = 61000.+ let p = CompressionPolicy::for_mode(AuthMode::Payg);+ let gain = p.net_mutation_gain(50_000, 10_000, 3.0, 1.0);+ assert!((gain - 61_000.0).abs() < 1.0, "gain = {gain}");+ assert!(p.should_mutate_deep(50_000, 10_000, 3.0, 1.0));+ }++ #[test]+ fn net_gain_live_zone_edit_always_profitable() {+ // S = 0 derives the existing Subscription live-zone policy as a+ // special case: nothing cached is invalidated, so any positive+ // shave wins even at R=0 (gain = ΔT·(w − r) > 0).+ let p = CompressionPolicy::for_mode(AuthMode::Subscription);+ assert!(p.should_mutate_deep(1, 0, 0.0, 1.0));+ assert!(p.should_mutate_deep(2_000, 0, 0.0, 1.0));+ }++ #[test]+ fn net_gain_cold_cache_ignores_suffix() {+ // P_alive = 0 (TTL lapsed): no warm suffix to lose, so even the+ // worst shave/suffix ratio is profitable. This is the idle-timer+ // compaction window.+ let p = CompressionPolicy::for_mode(AuthMode::Payg);+ assert!(p.should_mutate_deep(2_000, 50_000, 0.0, 0.0));+ }++ #[test]+ fn net_gain_clamps_out_of_range_inputs() {+ let p = CompressionPolicy::for_mode(AuthMode::Payg);+ // Negative reads clamp to 0; p_alive > 1 clamps to 1.+ let clamped = p.net_mutation_gain(2_000, 50_000, -5.0, 7.0);+ let reference = p.net_mutation_gain(2_000, 50_000, 0.0, 1.0);+ assert!((clamped - reference).abs() < f32::EPSILON);+ }++ #[test]+ fn net_gain_guards_nan_inputs() {+ // NaN reads → 0, NaN p_alive → 1: gain stays finite and matches+ // the conservative reference instead of poisoning the decision.+ let p = CompressionPolicy::for_mode(AuthMode::Payg);+ let guarded = p.net_mutation_gain(2_000, 50_000, f32::NAN, f32::NAN);+ assert!(guarded.is_finite());+ let reference = p.net_mutation_gain(2_000, 50_000, 0.0, 1.0);+ assert!((guarded - reference).abs() < f32::EPSILON);+ }++ #[test]+ fn break_even_reads_matches_research_anchor() {+ // R = 11.5·(S/ΔT − 1): 2K shave / 50K suffix → 11.5·24 = 276+ // (rarely profitable); 50K shave / 10K suffix →+ // 11.5·(0.2 − 1) < 0 → profitable from the first read.+ let p = CompressionPolicy::for_mode(AuthMode::Payg);+ let r = p.break_even_reads(2_000, 50_000);+ assert!((r - 276.0).abs() < 0.5, "break-even = {r}");+ assert!(p.break_even_reads(50_000, 10_000) < 0.0);+ assert_eq!(p.break_even_reads(0, 10_000), 0.0);+ }}diff --git a/headroom/transforms/compression_policy.py b/headroom/transforms/compression_policy.pyindex 5057a8812..717cc56b8 100644--- a/headroom/transforms/compression_policy.py+++ b/headroom/transforms/compression_policy.py@@ -18,6 +18,7 @@ docstring (per-mode rationale, why-a-struct, etc.).from __future__ import annotations+import mathimport osfrom dataclasses import dataclass@@ -54,6 +55,16 @@ _MAX_LOSSY_RATIO_PAYG: float = 0.45#: Subscription: conservative cap at 25%. Cache stability over savings._MAX_LOSSY_RATIO_SUBSCRIPTION: float = 0.25+#: Anthropic prompt-cache write multiplier: a ``cache_creation`` token+#: costs 1.25x a plain input token (5-minute TTL tier). Input to the+#: net-cost mutation formula (#856). Mirrors the Rust ``pub const``.+CACHE_WRITE_MULTIPLIER: float = 1.25++#: Anthropic prompt-cache read multiplier: a ``cache_read`` token costs+#: 0.1x a plain input token. Input to the net-cost mutation formula+#: (#856). Mirrors the Rust ``pub const``.+CACHE_READ_MULTIPLIER: float = 0.1+@dataclass(frozen=True, slots=True)class CompressionPolicy:@@ -112,6 +123,64 @@ class CompressionPolicy:``smart_crusher.py`` and ``content_router.py`` at the``record_compression`` call sites."""+ def net_mutation_gain(+ self,+ delta_t: int,+ suffix_tokens: int,+ expected_reads: float,+ p_alive: float,+ ) -> float:+ """Net gain (in plain-input-token cost units) of a mutation that+ removes ``delta_t`` tokens from a message whose cached suffix is+ ``suffix_tokens`` long (#856).++ Mirrors ``CompressionPolicy::net_mutation_gain`` in the Rust+ crate (source of truth — see its docstring for the derivation)::++ gain = dT * (w + r*(R - 1)) - P_alive * (w - r) * S++ Inputs are clamped: ``delta_t``/``suffix_tokens`` to ``>= 0``+ (the Rust signature takes ``u32``), ``expected_reads`` to+ ``>= 0`` (NaN → 0), ``p_alive`` to ``[0, 1]`` (NaN → 1, the+ conservative full-penalty assumption — same as Rust).+ """+ w = CACHE_WRITE_MULTIPLIER+ r = CACHE_READ_MULTIPLIER+ dt = max(0, delta_t)+ suffix = max(0, suffix_tokens)+ # Python max()/min() propagate NaN from the first argument, unlike+ # f32::max in the Rust source of truth — guard explicitly.+ reads = 0.0 if math.isnan(expected_reads) else max(expected_reads, 0.0)+ alive = 1.0 if math.isnan(p_alive) else min(max(p_alive, 0.0), 1.0)+ return float(dt) * (w + r * (reads - 1.0)) - alive * (w - r) * float(suffix)++ def should_mutate_deep(+ self,+ delta_t: int,+ suffix_tokens: int,+ expected_reads: float,+ p_alive: float,+ ) -> bool:+ """Decision form of :meth:`net_mutation_gain`: mutate iff the+ gain is strictly positive."""+ return self.net_mutation_gain(delta_t, suffix_tokens, expected_reads, p_alive) > 0.0++ def break_even_reads(self, delta_t: int, suffix_tokens: int) -> float:+ """Remaining-read count at which a warm-cache (``p_alive=1``)+ mutation breaks even::++ R = ((w - r) / r) * (S/dT - 1) ~= 11.5 * S/dT for S >> dT++ Returns 0 when ``delta_t`` is ``<= 0`` (no savings — callers+ gate on ``delta_t > 0``; the Rust signature takes ``u32``).+ Mirrors the Rust method.+ """+ if delta_t <= 0:+ return 0.0+ w = CACHE_WRITE_MULTIPLIER+ r = CACHE_READ_MULTIPLIER+ return ((w - r) / r) * (float(max(0, suffix_tokens)) / float(delta_t) - 1.0)+def policy_for_mode(mode: AuthMode) -> CompressionPolicy:"""Resolve the F2.1+F2.2 policy for an auth mode.diff --git a/tests/test_compression_policy.py b/tests/test_compression_policy.pyindex c517b0868..da6a5284a 100644--- a/tests/test_compression_policy.py+++ b/tests/test_compression_policy.py@@ -157,3 +157,81 @@ class TestRustParityFieldMap:f"and `crates/headroom-core/src/compression_policy.rs` in "f"the same commit.")+++class TestNetCostFormula:+ """Net-cost mutation formula (#856) — Rust parity.++ Scenario values are golden: the Rust unit tests in+ ``crates/headroom-core/src/compression_policy.rs`` assert the+ identical numbers, so a drift in either side trips the parity pair+ loudly.+ """++ def test_small_shave_deep_suffix_is_loss(self):+ # 2000*(1.25 + 0.1*9) - 1.0*1.15*50000 = 4300 - 57500 = -53200.+ p = policy_for_mode(AuthMode.PAYG)+ gain = p.net_mutation_gain(2_000, 50_000, 10.0, 1.0)+ assert abs(gain - (-53_200.0)) < 1.0+ assert not p.should_mutate_deep(2_000, 50_000, 10.0, 1.0)++ def test_big_shave_shallow_suffix_is_win(self):+ # 50000*(1.25 + 0.1*2) - 1.0*1.15*10000 = 72500 - 11500 = 61000.+ p = policy_for_mode(AuthMode.PAYG)+ gain = p.net_mutation_gain(50_000, 10_000, 3.0, 1.0)+ assert abs(gain - 61_000.0) < 1.0+ assert p.should_mutate_deep(50_000, 10_000, 3.0, 1.0)++ def test_live_zone_edit_always_profitable(self):+ # S = 0 derives the existing Subscription live-zone policy as a+ # special case of the formula.+ p = policy_for_mode(AuthMode.SUBSCRIPTION)+ assert p.should_mutate_deep(1, 0, 0.0, 1.0)+ assert p.should_mutate_deep(2_000, 0, 0.0, 1.0)++ def test_cold_cache_ignores_suffix(self):+ # P_alive = 0 (TTL lapsed): the idle-timer compaction window.+ p = policy_for_mode(AuthMode.PAYG)+ assert p.should_mutate_deep(2_000, 50_000, 0.0, 0.0)++ def test_clamps_out_of_range_inputs(self):+ p = policy_for_mode(AuthMode.PAYG)+ clamped = p.net_mutation_gain(2_000, 50_000, -5.0, 7.0)+ reference = p.net_mutation_gain(2_000, 50_000, 0.0, 1.0)+ assert abs(clamped - reference) < 1e-6++ def test_nan_inputs_guarded(self):+ # NaN reads -> 0, NaN p_alive -> 1 (same as Rust): the gain stays+ # finite instead of poisoning the mutate decision.+ import math++ p = policy_for_mode(AuthMode.PAYG)+ guarded = p.net_mutation_gain(2_000, 50_000, float("nan"), float("nan"))+ assert math.isfinite(guarded)+ reference = p.net_mutation_gain(2_000, 50_000, 0.0, 1.0)+ assert abs(guarded - reference) < 1e-6++ def test_negative_int_inputs_clamped(self):+ # Rust takes u32 — negative Python ints must not flip the sign of+ # the result; they clamp to 0.+ p = policy_for_mode(AuthMode.PAYG)+ assert p.net_mutation_gain(-2_000, -50_000, 5.0, 1.0) == p.net_mutation_gain(0, 0, 5.0, 1.0)+ assert p.break_even_reads(-5, 10_000) == 0.0+ assert p.net_mutation_gain(2_000, -1, 5.0, 1.0) == p.net_mutation_gain(2_000, 0, 5.0, 1.0)++ def test_break_even_reads_matches_research_anchor(self):+ # R = 11.5*(S/dT - 1): 2K/50K -> 276; 50K/10K -> negative+ # (profitable from the first read); dT=0 -> 0.+ p = policy_for_mode(AuthMode.PAYG)+ assert abs(p.break_even_reads(2_000, 50_000) - 276.0) < 0.5+ assert p.break_even_reads(50_000, 10_000) < 0.0+ assert p.break_even_reads(0, 10_000) == 0.0++ def test_constants_match_rust(self):+ from headroom.transforms.compression_policy import (+ CACHE_READ_MULTIPLIER,+ CACHE_WRITE_MULTIPLIER,+ )++ assert CACHE_WRITE_MULTIPLIER == 1.25+ assert CACHE_READ_MULTIPLIER == 0.1