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 image compression policy (#1958)

JD Davis2b09ecea7634
diff --git a/headroom/proxy/image_compression_decision.py b/headroom/proxy/image_compression_decision.py
index 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 Sequence
from dataclasses import dataclass
from 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:
messages
Request 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 full
dashboard 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.py
new file mode 100644
index 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_reason
diff --git a/tests/test_image_compression_policy.py b/tests/test_image_compression_policy.py
new file mode 100644
index 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"}