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 image compression policy (#1958)
JD Davis2b09ecea7634
diff --git a/headroom/proxy/image_compression_decision.py b/headroom/proxy/image_compression_decision.pyindex b558a0cd1..5a403524b 100644--- a/headroom/proxy/image_compression_decision.py+++ b/headroom/proxy/image_compression_decision.py@@ -31,7 +31,10 @@ from collections.abc import Sequencefrom dataclasses import dataclassfrom typing import Any-from headroom.proxy.helpers import _headroom_bypass_enabled+from headroom.proxy.image_compression_policy import (+ apply_image_skip_reason,+ decide_image_compression,+)@dataclass(frozen=True)@@ -84,29 +87,18 @@ class ImageCompressionDecision:messagesRequest messages. ``None`` and ``[]`` are equivalent."""- bypass = _headroom_bypass_enabled(headers)- image_ok = bool(getattr(config, "image_optimize", False))- has_msgs = bool(messages)-- if bypass:- reason: str | None = "bypass_header"- should = False- elif not image_ok:- reason = "image_optimize_disabled"- should = False- elif not has_msgs:- reason = "no_messages"- should = False- else:- reason = None- should = True+ decision = decide_image_compression(+ headers=headers,+ image_optimize_enabled=bool(getattr(config, "image_optimize", False)),+ has_messages=bool(messages),+ )return cls(- should_compress=should,- passthrough_reason=reason,- bypass_header_set=bypass,- image_optimize_enabled=image_ok,- has_messages=has_msgs,+ should_compress=decision.should_compress,+ passthrough_reason=decision.passthrough_reason,+ bypass_header_set=decision.bypass_header_set,+ image_optimize_enabled=decision.image_optimize_enabled,+ has_messages=decision.has_messages,)def apply_to_tags(self, tags: dict[str, str]) -> None:@@ -121,5 +113,4 @@ class ImageCompressionDecision:``memory_skip_reason``, ``image_skip_reason``) for fulldashboard slicing."""- if self.passthrough_reason is not None:- tags["image_skip_reason"] = self.passthrough_reason+ apply_image_skip_reason(tags, self.passthrough_reason)diff --git a/headroom/proxy/image_compression_policy.py b/headroom/proxy/image_compression_policy.pynew file mode 100644index 000000000..e336c6438--- /dev/null+++ b/headroom/proxy/image_compression_policy.py@@ -0,0 +1,56 @@+"""Pure image-compression decision policy helpers."""++from __future__ import annotations++from dataclasses import dataclass+from typing import Any++from headroom.proxy.helpers import _headroom_bypass_enabled+++@dataclass(frozen=True)+class ImageCompressionPolicyResult:+ """Raw image-compression gate result before wrapping in public value types."""++ should_compress: bool+ passthrough_reason: str | None+ bypass_header_set: bool+ image_optimize_enabled: bool+ has_messages: bool+++def decide_image_compression(+ *,+ headers: Any,+ image_optimize_enabled: bool,+ has_messages: bool,+) -> ImageCompressionPolicyResult:+ """Compute the canonical image-compression gate."""+ bypass = _headroom_bypass_enabled(headers)++ if bypass:+ reason: str | None = "bypass_header"+ should = False+ elif not image_optimize_enabled:+ reason = "image_optimize_disabled"+ should = False+ elif not has_messages:+ reason = "no_messages"+ should = False+ else:+ reason = None+ should = True++ return ImageCompressionPolicyResult(+ should_compress=should,+ passthrough_reason=reason,+ bypass_header_set=bypass,+ image_optimize_enabled=image_optimize_enabled,+ has_messages=has_messages,+ )+++def apply_image_skip_reason(tags: dict[str, str], passthrough_reason: str | None) -> None:+ """Stamp image skip reason into tags when present."""+ if passthrough_reason is not None:+ tags["image_skip_reason"] = passthrough_reasondiff --git a/tests/test_image_compression_policy.py b/tests/test_image_compression_policy.pynew file mode 100644index 000000000..870a92012--- /dev/null+++ b/tests/test_image_compression_policy.py@@ -0,0 +1,58 @@+"""Tests for pure image-compression decision policy helpers."""++from __future__ import annotations++from headroom.proxy.image_compression_policy import (+ apply_image_skip_reason,+ decide_image_compression,+)+++def test_decide_image_compression_allows_happy_path() -> None:+ decision = decide_image_compression(+ headers={},+ image_optimize_enabled=True,+ has_messages=True,+ )++ assert decision.should_compress is True+ assert decision.passthrough_reason is None+++def test_decide_image_compression_uses_canonical_precedence() -> None:+ decision = decide_image_compression(+ headers={"x-headroom-bypass": "true"},+ image_optimize_enabled=False,+ has_messages=False,+ )++ assert decision.should_compress is False+ assert decision.passthrough_reason == "bypass_header"+ assert decision.bypass_header_set is True+ assert decision.image_optimize_enabled is False+ assert decision.has_messages is False+++def test_decide_image_compression_reports_config_and_message_reasons() -> None:+ disabled = decide_image_compression(+ headers={},+ image_optimize_enabled=False,+ has_messages=True,+ )+ empty = decide_image_compression(+ headers={},+ image_optimize_enabled=True,+ has_messages=False,+ )++ assert disabled.passthrough_reason == "image_optimize_disabled"+ assert empty.passthrough_reason == "no_messages"+++def test_apply_image_skip_reason_stamps_only_when_skipping() -> None:+ tags: dict[str, str] = {}+ apply_image_skip_reason(tags, None)+ assert tags == {}++ apply_image_skip_reason(tags, "no_messages")+ assert tags == {"image_skip_reason": "no_messages"}