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(proxy): isolate proxy mode policy (#1965)
JD Davis82af5cdfe256
diff --git a/headroom/proxy/modes.py b/headroom/proxy/modes.pyindex 0dab93a33..1b0e61bbd 100644--- a/headroom/proxy/modes.py+++ b/headroom/proxy/modes.py@@ -9,36 +9,23 @@ from __future__ import annotationsimport logging-logger = logging.getLogger("headroom.proxy")--PROXY_MODE_TOKEN = "token"-PROXY_MODE_CACHE = "cache"+from headroom.proxy.proxy_mode_policy import (+ PROXY_MODE_CACHE,+ PROXY_MODE_TOKEN,+ normalize_proxy_mode_decision,+)-_MODE_ALIASES = {- "token": PROXY_MODE_TOKEN,- "token_mode": PROXY_MODE_TOKEN,- "token_savings": PROXY_MODE_TOKEN,- "token_headroom": PROXY_MODE_TOKEN,- "cache": PROXY_MODE_CACHE,- "cache_mode": PROXY_MODE_CACHE,- "cost_savings": PROXY_MODE_CACHE,-}+logger = logging.getLogger("headroom.proxy")def normalize_proxy_mode(mode: str | None, *, default: str = PROXY_MODE_TOKEN) -> str:"""Normalize a user-provided proxy mode to canonical token/cache values."""- key = (mode or "").strip().lower()- if not key:- return default-- normalized = _MODE_ALIASES.get(key)- if normalized is None:+ decision = normalize_proxy_mode_decision(mode, default=default)+ if decision.unknown:logger.warning("Unknown HEADROOM_MODE '%s', falling back to '%s'", mode, default)- return default-- if key != normalized:- logger.info("HEADROOM_MODE alias '%s' normalized to '%s'", mode, normalized)- return normalized+ elif decision.alias_used:+ logger.info("HEADROOM_MODE alias '%s' normalized to '%s'", mode, decision.normalized)+ return decision.normalizeddef is_token_mode(mode: str | None) -> bool:diff --git a/headroom/proxy/proxy_mode_policy.py b/headroom/proxy/proxy_mode_policy.pynew file mode 100644index 000000000..bc93b145f--- /dev/null+++ b/headroom/proxy/proxy_mode_policy.py@@ -0,0 +1,67 @@+"""Pure proxy mode normalization policy."""++from __future__ import annotations++from dataclasses import dataclass++PROXY_MODE_TOKEN = "token"+PROXY_MODE_CACHE = "cache"++MODE_ALIASES = {+ "token": PROXY_MODE_TOKEN,+ "token_mode": PROXY_MODE_TOKEN,+ "token_savings": PROXY_MODE_TOKEN,+ "token_headroom": PROXY_MODE_TOKEN,+ "cache": PROXY_MODE_CACHE,+ "cache_mode": PROXY_MODE_CACHE,+ "cost_savings": PROXY_MODE_CACHE,+}+++@dataclass(frozen=True)+class ProxyModeDecision:+ """Result of normalizing a user-provided proxy mode."""++ raw: str | None+ key: str+ normalized: str+ used_default: bool = False+ unknown: bool = False+ alias_used: bool = False+++def normalize_proxy_mode_decision(+ mode: str | None,+ *,+ default: str = PROXY_MODE_TOKEN,+) -> ProxyModeDecision:+ """Normalize a user-provided proxy mode without side effects."""+ key = (mode or "").strip().lower()+ if not key:+ return ProxyModeDecision(raw=mode, key=key, normalized=default, used_default=True)++ normalized = MODE_ALIASES.get(key)+ if normalized is None:+ return ProxyModeDecision(+ raw=mode,+ key=key,+ normalized=default,+ used_default=True,+ unknown=True,+ )++ return ProxyModeDecision(+ raw=mode,+ key=key,+ normalized=normalized,+ alias_used=key != normalized,+ )+++def normalize_proxy_mode_value(+ mode: str | None,+ *,+ default: str = PROXY_MODE_TOKEN,+) -> str:+ """Return only the canonical proxy mode value."""+ return normalize_proxy_mode_decision(mode, default=default).normalizeddiff --git a/tests/test_proxy_mode_policy.py b/tests/test_proxy_mode_policy.pynew file mode 100644index 000000000..88f546069--- /dev/null+++ b/tests/test_proxy_mode_policy.py@@ -0,0 +1,52 @@+"""Tests for pure proxy mode normalization policy."""++from __future__ import annotations++from headroom.proxy.proxy_mode_policy import (+ PROXY_MODE_CACHE,+ PROXY_MODE_TOKEN,+ normalize_proxy_mode_decision,+ normalize_proxy_mode_value,+)+++def test_decision_normalizes_canonical_modes() -> None:+ token = normalize_proxy_mode_decision("token")+ assert token.normalized == PROXY_MODE_TOKEN+ assert token.alias_used is False+ assert token.unknown is False++ cache = normalize_proxy_mode_decision("cache")+ assert cache.normalized == PROXY_MODE_CACHE+ assert cache.alias_used is False+ assert cache.unknown is False+++def test_decision_normalizes_aliases_and_marks_alias_used() -> None:+ token = normalize_proxy_mode_decision(" token_headroom ")+ assert token.key == "token_headroom"+ assert token.normalized == PROXY_MODE_TOKEN+ assert token.alias_used is True++ cache = normalize_proxy_mode_decision("cost_savings")+ assert cache.normalized == PROXY_MODE_CACHE+ assert cache.alias_used is True+++def test_decision_uses_default_for_blank_mode() -> None:+ decision = normalize_proxy_mode_decision(" ", default=PROXY_MODE_CACHE)+ assert decision.normalized == PROXY_MODE_CACHE+ assert decision.used_default is True+ assert decision.unknown is False+++def test_decision_uses_default_and_marks_unknown_for_invalid_mode() -> None:+ decision = normalize_proxy_mode_decision("wat", default=PROXY_MODE_CACHE)+ assert decision.normalized == PROXY_MODE_CACHE+ assert decision.used_default is True+ assert decision.unknown is True+++def test_value_helper_returns_only_canonical_mode() -> None:+ assert normalize_proxy_mode_value("token_savings") == PROXY_MODE_TOKEN+ assert normalize_proxy_mode_value("cache_mode") == PROXY_MODE_CACHE