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
refactor(cache): isolate compression strategy outcomes (#1938)
JD Davisb5aa8a358e70
diff --git a/headroom/cache/compression_feedback.py b/headroom/cache/compression_feedback.pyindex 20413ade4..e4a320444 100644--- a/headroom/cache/compression_feedback.py+++ b/headroom/cache/compression_feedback.py@@ -33,6 +33,8 @@ import timefrom dataclasses import dataclass, fieldfrom typing import TYPE_CHECKING, Any+from .compression_strategy_outcomes import CompressionStrategyOutcomes+if TYPE_CHECKING:from .compression_store import CompressionStore, RetrievalEvent@@ -94,28 +96,33 @@ class LocalToolPattern:def strategy_retrieval_rate(self, strategy: str) -> float:"""Get retrieval rate for a specific compression strategy."""- compressions = self.strategy_compressions.get(strategy, 0)- if compressions == 0:- return 0.0- retrievals = self.strategy_retrievals.get(strategy, 0)- return retrievals / compressions+ return self.strategy_outcomes.retrieval_rate(strategy)def best_strategy(self) -> str | None:"""Find the strategy with lowest retrieval rate (most successful)."""- if not self.strategy_compressions:- return None+ return self.strategy_outcomes.best_strategy()- best = None- best_rate = 1.0+ @property+ def strategy_outcomes(self) -> CompressionStrategyOutcomes:+ """Strategy outcome view backed by this pattern's public counters."""+ return CompressionStrategyOutcomes(+ compressions=self.strategy_compressions,+ retrievals=self.strategy_retrievals,+ )- for strategy in self.strategy_compressions:- rate = self.strategy_retrieval_rate(strategy)- # Only consider strategies with enough samples- if self.strategy_compressions[strategy] >= 3 and rate < best_rate:- best_rate = rate- best = strategy+ def record_strategy_compression(self, strategy: str) -> None:+ """Record strategy compression outcome."""+ outcomes = self.strategy_outcomes+ outcomes.record_compression(strategy)+ self.strategy_compressions = outcomes.compressions+ self.strategy_retrievals = outcomes.retrievals- return best+ def record_strategy_retrieval(self, strategy: str) -> None:+ """Record strategy retrieval outcome."""+ outcomes = self.strategy_outcomes+ outcomes.record_retrieval(strategy)+ self.strategy_compressions = outcomes.compressions+ self.strategy_retrievals = outcomes.retrievals@dataclass@@ -235,15 +242,7 @@ class CompressionFeedback:# Track strategy usageif strategy:- pattern.strategy_compressions[strategy] = (- pattern.strategy_compressions.get(strategy, 0) + 1- )-- # CRITICAL FIX: When truncating strategy dicts, keep them in sync- # to prevent desync between compressions and retrievals.- # Both dicts must have the same keys for accurate retrieval rate calculation.- if len(pattern.strategy_compressions) > 50:- self._truncate_strategy_dicts(pattern)+ pattern.record_strategy_compression(strategy)# Track signature hash for TOIN correlationif tool_signature_hash:@@ -291,14 +290,7 @@ class CompressionFeedback:# Track strategy retrievals (for success rate calculation)if strategy:- pattern.strategy_retrievals[strategy] = (- pattern.strategy_retrievals.get(strategy, 0) + 1- )-- # CRITICAL FIX: When truncating strategy dicts, keep them in sync- # to prevent desync between compressions and retrievals.- if len(pattern.strategy_retrievals) > 50:- self._truncate_strategy_dicts(pattern)+ pattern.record_strategy_retrieval(strategy)# Track query patternsif event.query:@@ -318,40 +310,11 @@ class CompressionFeedback:self._extract_field_hints(pattern, event.query)def _truncate_strategy_dicts(self, pattern: LocalToolPattern) -> None:- """Truncate strategy_compressions and strategy_retrievals in sync.-- CRITICAL FIX: Both dicts must have the same keys for accurate retrieval- rate calculation. When truncating, we keep the union of top strategies- from both dicts, then truncate both to the same key set.- """- # Get top 40 strategies from each dict (using 40 to allow union to stay under 50)- top_compressions = {- k- for k, _ in sorted(- pattern.strategy_compressions.items(),- key=lambda x: x[1],- reverse=True,- )[:40]- }- top_retrievals = {- k- for k, _ in sorted(- pattern.strategy_retrievals.items(),- key=lambda x: x[1],- reverse=True,- )[:40]- }-- # Keep union of top strategies from both- keys_to_keep = top_compressions | top_retrievals-- # Truncate both dicts to same keys- pattern.strategy_compressions = {- k: v for k, v in pattern.strategy_compressions.items() if k in keys_to_keep- }- pattern.strategy_retrievals = {- k: v for k, v in pattern.strategy_retrievals.items() if k in keys_to_keep- }+ """Truncate strategy counters using the shared strategy outcome domain."""+ outcomes = pattern.strategy_outcomes+ outcomes.prune()+ pattern.strategy_compressions = outcomes.compressions+ pattern.strategy_retrievals = outcomes.retrievalsdef _extract_field_hints(self, pattern: LocalToolPattern, query: str) -> None:"""Extract potential field names from search queries.diff --git a/headroom/cache/compression_strategy_outcomes.py b/headroom/cache/compression_strategy_outcomes.pynew file mode 100644index 000000000..04cfdf578--- /dev/null+++ b/headroom/cache/compression_strategy_outcomes.py@@ -0,0 +1,99 @@+"""Strategy outcome accounting for local compression feedback."""++from __future__ import annotations++from dataclasses import dataclass, field+++@dataclass+class CompressionStrategyOutcomes:+ """Track compression and retrieval outcomes by compression strategy."""++ compressions: dict[str, int] = field(default_factory=dict)+ retrievals: dict[str, int] = field(default_factory=dict)+ max_strategies: int = 50+ top_strategies_per_counter: int = 40+ minimum_samples_for_recommendation: int = 3++ def record_compression(self, strategy: str) -> None:+ """Record one compression for a strategy."""+ self.compressions[strategy] = self.compressions.get(strategy, 0) + 1+ self.prune()++ def record_retrieval(self, strategy: str) -> None:+ """Record one retrieval for a strategy."""+ self.retrievals[strategy] = self.retrievals.get(strategy, 0) + 1+ self.prune()++ def retrieval_rate(self, strategy: str) -> float:+ """Return the retrievals-per-compression rate for one strategy."""+ compressions = self.compressions.get(strategy, 0)+ if compressions == 0:+ return 0.0+ return self.retrievals.get(strategy, 0) / compressions++ def best_strategy(self) -> str | None:+ """Return the sampled strategy with the lowest retrieval rate."""+ best = None+ best_rate = 1.0++ for strategy, compression_count in self.compressions.items():+ if compression_count < self.minimum_samples_for_recommendation:+ continue++ rate = self.retrieval_rate(strategy)+ if rate < best_rate:+ best = strategy+ best_rate = rate++ return best++ def prune(self) -> None:+ """Bound counters while preserving the highest-signal strategies."""+ if (+ len(self.compressions) <= self.max_strategies+ and len(self.retrievals) <= self.max_strategies+ ):+ return++ keys_to_keep = self._keys_to_keep()+ self.compressions = {+ strategy: count+ for strategy, count in self.compressions.items()+ if strategy in keys_to_keep+ }+ self.retrievals = {+ strategy: count+ for strategy, count in self.retrievals.items()+ if strategy in keys_to_keep+ }++ def _keys_to_keep(self) -> set[str]:+ top_compressions = self._top_keys(self.compressions)+ top_retrievals = self._top_keys(self.retrievals)+ candidate_keys = top_compressions | top_retrievals++ if len(candidate_keys) <= self.max_strategies:+ return candidate_keys++ ranked_keys = sorted(+ candidate_keys,+ key=lambda strategy: (+ self.compressions.get(strategy, 0) + self.retrievals.get(strategy, 0),+ self.compressions.get(strategy, 0),+ self.retrievals.get(strategy, 0),+ strategy,+ ),+ reverse=True,+ )+ return set(ranked_keys[: self.max_strategies])++ def _top_keys(self, counts: dict[str, int]) -> set[str]:+ return {+ strategy+ for strategy, _ in sorted(+ counts.items(),+ key=lambda item: (item[1], item[0]),+ reverse=True,+ )[: self.top_strategies_per_counter]+ }diff --git a/tests/test_compression_strategy_outcomes.py b/tests/test_compression_strategy_outcomes.pynew file mode 100644index 000000000..d872bde5a--- /dev/null+++ b/tests/test_compression_strategy_outcomes.py@@ -0,0 +1,45 @@+from headroom.cache.compression_strategy_outcomes import CompressionStrategyOutcomes+++def test_retrieval_rate_is_zero_without_strategy_compressions():+ outcomes = CompressionStrategyOutcomes(retrievals={"sample": 2})++ assert outcomes.retrieval_rate("sample") == 0.0+++def test_best_strategy_requires_minimum_samples():+ outcomes = CompressionStrategyOutcomes(+ compressions={"under_sampled": 2, "sampled": 3},+ retrievals={"under_sampled": 0, "sampled": 1},+ )++ assert outcomes.best_strategy() == "sampled"+++def test_best_strategy_uses_lowest_retrieval_rate():+ outcomes = CompressionStrategyOutcomes(+ compressions={"top_n": 10, "smart_sample": 10},+ retrievals={"top_n": 7, "smart_sample": 2},+ )++ assert outcomes.retrieval_rate("smart_sample") == 0.2+ assert outcomes.best_strategy() == "smart_sample"+++def test_recording_prunes_strategy_counters_to_bounded_high_signal_set():+ outcomes = CompressionStrategyOutcomes(max_strategies=10, top_strategies_per_counter=8)++ for index in range(30):+ strategy = f"strategy_{index:02d}"+ for _ in range(index + 1):+ outcomes.record_compression(strategy)++ for index in range(30):+ strategy = f"strategy_{index:02d}"+ for _ in range(30 - index):+ outcomes.record_retrieval(strategy)++ assert len(outcomes.compressions) <= 10+ assert len(outcomes.retrievals) <= 10+ assert "strategy_29" in outcomes.compressions+ assert "strategy_00" in outcomes.retrievals