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
Extract Python forwarder mode policy (#1987)
JD Davis70b98b64856b
diff --git a/headroom/proxy/body_forwarding.py b/headroom/proxy/body_forwarding.pyindex 81acdbaf2..2897d7d8f 100644--- a/headroom/proxy/body_forwarding.py+++ b/headroom/proxy/body_forwarding.py@@ -13,14 +13,16 @@ from __future__ import annotationsimport jsonimport osfrom 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.PythonForwarderModeOutboundBodySource = 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 anexplicit 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.pynew file mode 100644index 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.pynew file mode 100644index 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")