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.

feat(proxy): per-provider Kompress enable/disable (#1119)

gglucassdee3500db6af
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index 804242f76..c9bf615dd 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -392,6 +392,26 @@ def _selected_context_tool() -> str:
"Env: HEADROOM_DISABLE_KOMPRESS=1."
),
)
+ "--disable-kompress-anthropic/--enable-kompress-anthropic",
+ "disable_kompress_anthropic",
+ default=None,
+ envvar="HEADROOM_DISABLE_KOMPRESS_ANTHROPIC",
+ help=(
+ "Disable (or --enable-) Kompress for the Anthropic pipeline only, overriding "
+ "--disable-kompress. Env: HEADROOM_DISABLE_KOMPRESS_ANTHROPIC=1."
+ ),
+)
+ "--disable-kompress-openai/--enable-kompress-openai",
+ "disable_kompress_openai",
+ default=None,
+ envvar="HEADROOM_DISABLE_KOMPRESS_OPENAI",
+ help=(
+ "Disable (or --enable-) Kompress for the OpenAI/Codex pipeline only, overriding "
+ "--disable-kompress. Env: HEADROOM_DISABLE_KOMPRESS_OPENAI=1."
+ ),
+)
# Code graph: indexes project + watches files for live reindex via codebase-memory-mcp.
# Only useful when the proxy is launched from a project root — it indexes the
# current working directory.
@@ -676,6 +696,8 @@ def proxy(
budget_period: str,
code_aware_flag: bool | None,
disable_kompress: bool,
+ disable_kompress_anthropic: bool | None,
+ disable_kompress_openai: bool | None,
code_graph: bool,
no_read_lifecycle: bool,
memory: bool,
@@ -901,6 +923,8 @@ def proxy(
in ("true", "1", "yes", "on")
),
disable_kompress=disable_kompress,
+ disable_kompress_anthropic=disable_kompress_anthropic,
+ disable_kompress_openai=disable_kompress_openai,
# Code graph: live file watcher for incremental reindexing
code_graph_watcher=code_graph,
# Read lifecycle: ON by default (use --no-read-lifecycle to disable)
diff --git a/headroom/proxy/models.py b/headroom/proxy/models.py
index bd32fbc83..735351948 100644
--- a/headroom/proxy/models.py
+++ b/headroom/proxy/models.py
@@ -154,6 +154,16 @@ class ProxyConfig:
# CLI: --disable-kompress; env: HEADROOM_DISABLE_KOMPRESS=1.
disable_kompress: bool = False
+ # Per-provider overrides for `disable_kompress`. None inherits the global
+ # value above; True/False force-disable/enable Kompress for that provider's
+ # pipeline only (other compressors and all routing/exclusion are unaffected).
+ # Lets e.g. Anthropic run without lossy text compression while OpenAI/Codex
+ # keeps it. CLI: --disable-kompress-anthropic / --enable-kompress-anthropic
+ # (and -openai); env: HEADROOM_DISABLE_KOMPRESS_ANTHROPIC / _OPENAI
+ # (1 = disable, 0 = enable).
+ disable_kompress_anthropic: bool | None = None
+ disable_kompress_openai: bool | None = None
+
# Code graph live watcher (triggers incremental reindex on file changes)
code_graph_watcher: bool = False
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 4a736f9c9..8625ceead 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -33,7 +33,7 @@ import os
import sys
import threading
import time
-from dataclasses import fields, is_dataclass
+from dataclasses import fields, is_dataclass, replace
from datetime import datetime, timezone
from pathlib import Path
from typing import TYPE_CHECKING, Any, Literal, cast
@@ -642,18 +642,47 @@ class HeadroomProxy(
# code/RAG context — see issue #454).
if profile_kwargs.get("compress_user_messages"):
router_config.skip_user_messages = False
- transforms = [
- CacheAligner(CacheAlignerConfig(enabled=False)),
- ContentRouter(router_config, observer=self.metrics),
- ]
+ # Kompress (lossy ML text compression) is resolved per provider. The
+ # global `disable_kompress` above is the baseline for both; a per-
+ # provider override (disable_kompress_{anthropic,openai}) wins when set.
+ # Only `enable_kompress` differs between providers — routing, tool
+ # exclusion, and read-protection are identical — so when both resolve
+ # the same we reuse ONE ContentRouter instance and the Kompress model
+ # still loads once (startup warmup dedupes transforms by id()).
+ base_kompress_disabled = not router_config.enable_kompress
+ anthropic_kompress_disabled = (
+ base_kompress_disabled
+ if config.disable_kompress_anthropic is None
+ else config.disable_kompress_anthropic
+ )
+ openai_kompress_disabled = (
+ base_kompress_disabled
+ if config.disable_kompress_openai is None
+ else config.disable_kompress_openai
+ )
+
+ def _router_config_for(kompress_disabled: bool) -> ContentRouterConfig:
+ if kompress_disabled == base_kompress_disabled:
+ return router_config
+ return replace(router_config, enable_kompress=not kompress_disabled)
+
+ cache_aligner = CacheAligner(CacheAlignerConfig(enabled=False))
+ anthropic_router = ContentRouter(
+ _router_config_for(anthropic_kompress_disabled), observer=self.metrics
+ )
+ openai_router = (
+ anthropic_router
+ if openai_kompress_disabled == anthropic_kompress_disabled
+ else ContentRouter(_router_config_for(openai_kompress_disabled), observer=self.metrics)
+ )
self._code_aware_status = "lazy" if config.code_aware_enabled else "disabled"
self.anthropic_pipeline = TransformPipeline(
- transforms=transforms,
+ transforms=[cache_aligner, anthropic_router],
provider=self.anthropic_provider,
)
self.openai_pipeline = TransformPipeline(
- transforms=transforms,
+ transforms=[cache_aligner, openai_router],
provider=self.openai_provider,
)
@@ -2038,6 +2067,8 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
"cache": config.cache_enabled,
"rate_limit": config.rate_limit_enabled,
"disable_kompress": config.disable_kompress,
+ "disable_kompress_anthropic": config.disable_kompress_anthropic,
+ "disable_kompress_openai": config.disable_kompress_openai,
"memory": config.memory_enabled,
"learn": config.traffic_learning_enabled,
"code_graph": config.code_graph_watcher,
@@ -3738,6 +3769,8 @@ def _proxy_config_from_env() -> ProxyConfig:
bedrock_api_url=os.environ.get("BEDROCK_TARGET_API_URL"),
anyllm_provider=_get_env_str("HEADROOM_ANYLLM_PROVIDER", "openai"),
disable_kompress=_get_env_bool("HEADROOM_DISABLE_KOMPRESS", False),
+ disable_kompress_anthropic=_get_env_optional_bool("HEADROOM_DISABLE_KOMPRESS_ANTHROPIC"),
+ disable_kompress_openai=_get_env_optional_bool("HEADROOM_DISABLE_KOMPRESS_OPENAI"),
max_connections=_get_env_int("HEADROOM_MAX_CONNECTIONS", 500),
max_keepalive_connections=_get_env_int("HEADROOM_MAX_KEEPALIVE", 100),
http2=_get_env_bool("HEADROOM_HTTP2", True),
@@ -3917,6 +3950,14 @@ def _get_env_bool(name: str, default: bool) -> bool:
return val.lower() in ("true", "1", "yes", "on")
+def _get_env_optional_bool(name: str) -> bool | None:
+ """Tristate boolean env var: unset/empty -> None, truthy -> True, falsy -> False."""
+ val = os.environ.get(name)
+ if val is None or val == "":
+ return None
+ return val.lower() in ("true", "1", "yes", "on")
+
+
def _get_env_int(name: str, default: int) -> int:
"""Get integer from environment variable."""
val = os.environ.get(name)
@@ -4115,6 +4156,42 @@ if __name__ == "__main__":
"Also settable via HEADROOM_DISABLE_KOMPRESS=1."
),
)
+ parser.add_argument(
+ "--disable-kompress-anthropic",
+ dest="disable_kompress_anthropic",
+ action="store_const",
+ const=True,
+ default=None,
+ help=(
+ "Disable Kompress for the Anthropic pipeline only, overriding --disable-kompress. "
+ "Also settable via HEADROOM_DISABLE_KOMPRESS_ANTHROPIC=1."
+ ),
+ )
+ parser.add_argument(
+ "--enable-kompress-anthropic",
+ dest="disable_kompress_anthropic",
+ action="store_const",
+ const=False,
+ help="Force-enable Kompress for the Anthropic pipeline, overriding --disable-kompress.",
+ )
+ parser.add_argument(
+ "--disable-kompress-openai",
+ dest="disable_kompress_openai",
+ action="store_const",
+ const=True,
+ default=None,
+ help=(
+ "Disable Kompress for the OpenAI/Codex pipeline only, overriding --disable-kompress. "
+ "Also settable via HEADROOM_DISABLE_KOMPRESS_OPENAI=1."
+ ),
+ )
+ parser.add_argument(
+ "--enable-kompress-openai",
+ dest="disable_kompress_openai",
+ action="store_const",
+ const=False,
+ help="Force-enable Kompress for the OpenAI/Codex pipeline, overriding --disable-kompress.",
+ )
parser.add_argument(
"--exclude-tools",
default=None,
@@ -4172,6 +4249,16 @@ if __name__ == "__main__":
cache_enabled = env_cache if not args.no_cache else False
rate_limit_enabled = env_rate_limit if not args.no_rate_limit else False
disable_kompress = args.disable_kompress or _get_env_bool("HEADROOM_DISABLE_KOMPRESS", False)
+ disable_kompress_anthropic = (
+ args.disable_kompress_anthropic
+ if args.disable_kompress_anthropic is not None
+ else _get_env_optional_bool("HEADROOM_DISABLE_KOMPRESS_ANTHROPIC")
+ )
+ disable_kompress_openai = (
+ args.disable_kompress_openai
+ if args.disable_kompress_openai is not None
+ else _get_env_optional_bool("HEADROOM_DISABLE_KOMPRESS_OPENAI")
+ )
# Set OpenRouter API key from CLI if provided
if hasattr(args, "openrouter_api_key") and args.openrouter_api_key:
@@ -4215,6 +4302,8 @@ if __name__ == "__main__":
log_full_messages=args.log_messages or _get_env_bool("HEADROOM_LOG_MESSAGES", False),
code_aware_enabled=code_aware_enabled,
disable_kompress=disable_kompress,
+ disable_kompress_anthropic=disable_kompress_anthropic,
+ disable_kompress_openai=disable_kompress_openai,
# Connection pool settings
max_connections=_get_env_int("HEADROOM_MAX_CONNECTIONS", args.max_connections),
max_keepalive_connections=_get_env_int("HEADROOM_MAX_KEEPALIVE", args.max_keepalive),
diff --git a/tests/test_proxy_per_provider_kompress.py b/tests/test_proxy_per_provider_kompress.py
new file mode 100644
index 000000000..239304381
--- /dev/null
+++ b/tests/test_proxy_per_provider_kompress.py
@@ -0,0 +1,139 @@
+"""Per-provider Kompress enable/disable (disable_kompress_{anthropic,openai}).
+
+The global ``disable_kompress`` is the baseline for both providers; a per-provider
+override wins when set. Only ``enable_kompress`` differs between the two pipelines,
+so when both resolve identically they reuse ONE ContentRouter instance (keeping the
+single Kompress model load).
+"""
+
+from __future__ import annotations
+
+import os
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+from headroom.cli.main import main
+from headroom.proxy.server import (
+ HeadroomProxy,
+ ProxyConfig,
+ _get_env_optional_bool,
+ _proxy_config_from_env,
+)
+
+
+def _build(**overrides: object) -> HeadroomProxy:
+ config = ProxyConfig(
+ optimize=False,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ code_aware_enabled=False,
+ **overrides,
+ )
+ return HeadroomProxy(config)
+
+
+def _routers(proxy: HeadroomProxy):
+ # ContentRouter is the last transform in each pipeline.
+ return (
+ proxy.anthropic_pipeline.transforms[-1],
+ proxy.openai_pipeline.transforms[-1],
+ )
+
+
+def test_default_enables_kompress_and_shares_one_router() -> None:
+ anthropic, openai = _routers(_build())
+ assert anthropic.config.enable_kompress is True
+ assert openai.config.enable_kompress is True
+ # Identical resolution -> one shared instance (Kompress model loads once).
+ assert anthropic is openai
+
+
+def test_global_disable_respected_by_both() -> None:
+ anthropic, openai = _routers(_build(disable_kompress=True))
+ assert anthropic.config.enable_kompress is False
+ assert openai.config.enable_kompress is False
+ assert anthropic is openai
+
+
+def test_disable_for_anthropic_only() -> None:
+ anthropic, openai = _routers(_build(disable_kompress_anthropic=True))
+ assert anthropic.config.enable_kompress is False
+ assert openai.config.enable_kompress is True
+ assert anthropic is not openai
+
+
+def test_disable_for_openai_only() -> None:
+ anthropic, openai = _routers(_build(disable_kompress_openai=True))
+ assert anthropic.config.enable_kompress is True
+ assert openai.config.enable_kompress is False
+ assert anthropic is not openai
+
+
+def test_per_provider_override_beats_global() -> None:
+ # Global disables Kompress; Anthropic override force-enables it, OpenAI inherits.
+ anthropic, openai = _routers(_build(disable_kompress=True, disable_kompress_anthropic=False))
+ assert anthropic.config.enable_kompress is True
+ assert openai.config.enable_kompress is False
+ assert anthropic is not openai
+
+
+def test_get_env_optional_bool_tristate() -> None:
+ os.environ.pop("HRD_KOMPRESS_TEST", None)
+ assert _get_env_optional_bool("HRD_KOMPRESS_TEST") is None # unset
+ with patch.dict(os.environ, {"HRD_KOMPRESS_TEST": ""}):
+ assert _get_env_optional_bool("HRD_KOMPRESS_TEST") is None # empty
+ for truthy in ("1", "true", "yes", "on"):
+ with patch.dict(os.environ, {"HRD_KOMPRESS_TEST": truthy}):
+ assert _get_env_optional_bool("HRD_KOMPRESS_TEST") is True
+ for falsy in ("0", "false", "no", "off"):
+ with patch.dict(os.environ, {"HRD_KOMPRESS_TEST": falsy}):
+ assert _get_env_optional_bool("HRD_KOMPRESS_TEST") is False
+
+
+def test_proxy_config_from_env_reads_per_provider_kompress() -> None:
+ with patch.dict(
+ os.environ,
+ {
+ "HEADROOM_DISABLE_KOMPRESS_ANTHROPIC": "1",
+ "HEADROOM_DISABLE_KOMPRESS_OPENAI": "0",
+ },
+ ):
+ config = _proxy_config_from_env()
+ assert config.disable_kompress_anthropic is True
+ assert config.disable_kompress_openai is False
+
+
+def test_cli_disable_kompress_anthropic_only() -> None:
+ captured: dict = {}
+
+ def mock_run_server(config, **kwargs):
+ captured["config"] = config
+
+ with patch("headroom.proxy.server.run_server", mock_run_server):
+ result = CliRunner().invoke(
+ main,
+ ["proxy", "--disable-kompress-anthropic"],
+ catch_exceptions=False,
+ )
+ assert result.exit_code == 0, result.output
+ assert captured["config"].disable_kompress_anthropic is True
+ assert captured["config"].disable_kompress_openai is None
+
+
+def test_cli_enable_kompress_openai_from_env() -> None:
+ captured: dict = {}
+
+ def mock_run_server(config, **kwargs):
+ captured["config"] = config
+
+ with patch("headroom.proxy.server.run_server", mock_run_server):
+ result = CliRunner().invoke(
+ main,
+ ["proxy"],
+ env={"HEADROOM_DISABLE_KOMPRESS_OPENAI": "0"},
+ catch_exceptions=False,
+ )
+ assert result.exit_code == 0, result.output
+ assert captured["config"].disable_kompress_openai is False