Skip to content

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.

refactor(proxy): isolate proxy mode policy (#1965)

JD Davis82af5cdfe256
diff --git a/headroom/proxy/modes.py b/headroom/proxy/modes.py
index 0dab93a33..1b0e61bbd 100644
--- a/headroom/proxy/modes.py
+++ b/headroom/proxy/modes.py
@@ -9,36 +9,23 @@ from __future__ import annotations
import 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.normalized
def is_token_mode(mode: str | None) -> bool:
diff --git a/headroom/proxy/proxy_mode_policy.py b/headroom/proxy/proxy_mode_policy.py
new file mode 100644
index 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).normalized
diff --git a/tests/test_proxy_mode_policy.py b/tests/test_proxy_mode_policy.py
new file mode 100644
index 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