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.

Extract Python forwarder mode policy (#1987)

JD Davis70b98b64856b
diff --git a/headroom/proxy/body_forwarding.py b/headroom/proxy/body_forwarding.py
index 81acdbaf2..2897d7d8f 100644
--- a/headroom/proxy/body_forwarding.py
+++ b/headroom/proxy/body_forwarding.py
@@ -13,14 +13,16 @@ from __future__ import annotations
import json
import os
from dataclasses import dataclass
-from typing import Any, Literal, cast
+from typing import Any, Literal
-_PYTHON_FORWARDER_MODE_ENV = "HEADROOM_PROXY_PYTHON_FORWARDER_MODE"
+from headroom.proxy import python_forwarder_mode_policy
-PythonForwarderMode = Literal["byte_faithful", "legacy_json_kwarg"]
+_PYTHON_FORWARDER_MODE_ENV = python_forwarder_mode_policy.PYTHON_FORWARDER_MODE_ENV
+
+PythonForwarderMode = python_forwarder_mode_policy.PythonForwarderMode
OutboundBodySource = Literal["passthrough", "canonical", "legacy"]
-_PYTHON_FORWARDER_MODE_DEFAULT: PythonForwarderMode = "byte_faithful"
+_PYTHON_FORWARDER_MODE_DEFAULT = python_forwarder_mode_policy.PYTHON_FORWARDER_MODE_DEFAULT
@dataclass(frozen=True, slots=True)
@@ -38,14 +40,8 @@ def get_python_forwarder_mode() -> PythonForwarderMode:
fallback build constraint. The ``legacy_json_kwarg`` value is an
explicit operator opt-in for emergency rollback, not a fallback.
"""
- raw = os.environ.get(_PYTHON_FORWARDER_MODE_ENV, "").strip().lower()
- if not raw:
- return _PYTHON_FORWARDER_MODE_DEFAULT
- if raw in ("byte_faithful", "legacy_json_kwarg"):
- return cast(PythonForwarderMode, raw)
- raise ValueError(
- f"Invalid {_PYTHON_FORWARDER_MODE_ENV}={raw!r}; "
- "expected 'byte_faithful' or 'legacy_json_kwarg'"
+ return python_forwarder_mode_policy.resolve_python_forwarder_mode(
+ os.environ.get(_PYTHON_FORWARDER_MODE_ENV)
)
diff --git a/headroom/proxy/python_forwarder_mode_policy.py b/headroom/proxy/python_forwarder_mode_policy.py
new file mode 100644
index 000000000..f92480565
--- /dev/null
+++ b/headroom/proxy/python_forwarder_mode_policy.py
@@ -0,0 +1,22 @@
+"""Python forwarder mode resolution policy."""
+
+from __future__ import annotations
+
+from typing import Literal, cast
+
+PYTHON_FORWARDER_MODE_ENV = "HEADROOM_PROXY_PYTHON_FORWARDER_MODE"
+PythonForwarderMode = Literal["byte_faithful", "legacy_json_kwarg"]
+PYTHON_FORWARDER_MODE_DEFAULT: PythonForwarderMode = "byte_faithful"
+
+
+def resolve_python_forwarder_mode(raw: str | None) -> PythonForwarderMode:
+ """Resolve the active Python-forwarder mode from an optional value."""
+ normalized = (raw or "").strip().lower()
+ if not normalized:
+ return PYTHON_FORWARDER_MODE_DEFAULT
+ if normalized in ("byte_faithful", "legacy_json_kwarg"):
+ return cast(PythonForwarderMode, normalized)
+ raise ValueError(
+ f"Invalid {PYTHON_FORWARDER_MODE_ENV}={normalized!r}; "
+ "expected 'byte_faithful' or 'legacy_json_kwarg'"
+ )
diff --git a/tests/test_python_forwarder_mode_policy.py b/tests/test_python_forwarder_mode_policy.py
new file mode 100644
index 000000000..dd18a38f8
--- /dev/null
+++ b/tests/test_python_forwarder_mode_policy.py
@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import pytest
+
+from headroom.proxy.python_forwarder_mode_policy import (
+ PYTHON_FORWARDER_MODE_DEFAULT,
+ resolve_python_forwarder_mode,
+)
+
+
+def test_resolve_python_forwarder_mode_defaults_for_missing_value() -> None:
+ assert resolve_python_forwarder_mode(None) == PYTHON_FORWARDER_MODE_DEFAULT
+ assert resolve_python_forwarder_mode("") == PYTHON_FORWARDER_MODE_DEFAULT
+ assert resolve_python_forwarder_mode(" ") == PYTHON_FORWARDER_MODE_DEFAULT
+
+
+def test_resolve_python_forwarder_mode_accepts_known_values_case_insensitively() -> None:
+ assert resolve_python_forwarder_mode("byte_faithful") == "byte_faithful"
+ assert resolve_python_forwarder_mode(" LEGACY_JSON_KWARG ") == "legacy_json_kwarg"
+
+
+def test_resolve_python_forwarder_mode_rejects_unknown_values() -> None:
+ with pytest.raises(ValueError, match="HEADROOM_PROXY_PYTHON_FORWARDER_MODE"):
+ resolve_python_forwarder_mode("json")