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.

Add option to disable Kompress fallback (#514)

kiyo-e6d30054f82f5
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index 8fe639f02..44085c1be 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -332,6 +332,15 @@ def _selected_context_tool() -> str:
"Default: disabled. Env: HEADROOM_CODE_AWARE_ENABLED=1 to enable."
),
)
+ "--disable-kompress",
+ is_flag=True,
+ envvar="HEADROOM_DISABLE_KOMPRESS",
+ help=(
+ "Disable Kompress ML compression while keeping structural compression enabled. "
+ "Env: HEADROOM_DISABLE_KOMPRESS=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.
@@ -597,6 +606,7 @@ def proxy(
codex_wire_debug_dir: str | None,
budget: float | None,
code_aware_flag: bool | None,
+ disable_kompress: bool,
code_graph: bool,
no_read_lifecycle: bool,
memory: bool,
@@ -795,6 +805,7 @@ def proxy(
else os.environ.get("HEADROOM_CODE_AWARE_ENABLED", "").strip().lower()
in ("true", "1", "yes", "on")
),
+ disable_kompress=disable_kompress,
# 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 125da55a0..98bfc1bad 100644
--- a/headroom/proxy/models.py
+++ b/headroom/proxy/models.py
@@ -135,6 +135,11 @@ class ProxyConfig:
# Code-aware compression (disabled by default — use code graph tools instead)
code_aware_enabled: bool = False
+ # Disable Kompress ML compression while keeping structural compressors
+ # such as SmartCrusher, log/search/diff, and schema compaction enabled.
+ # CLI: --disable-kompress; env: HEADROOM_DISABLE_KOMPRESS=1.
+ disable_kompress: bool = False
+
# 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 eda36ff6f..414828212 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -165,6 +165,7 @@ from headroom.transforms import (
CacheAligner,
CodeAwareCompressor,
CodeCompressorConfig,
+ CompressionStrategy,
ContentRouter,
ContentRouterConfig,
TransformPipeline,
@@ -366,6 +367,9 @@ class HeadroomProxy(
read_lifecycle=ReadLifecycleConfig(enabled=config.read_lifecycle),
ccr_inject_marker=config.ccr_inject_marker,
)
+ if config.disable_kompress:
+ router_config.enable_kompress = False
+ router_config.fallback_strategy = CompressionStrategy.PASSTHROUGH
# A non-None exclude_tools replaces DEFAULT_EXCLUDE_TOOLS in
# ContentRouter, so merge rather than assign.
if config.exclude_tools:
@@ -1687,6 +1691,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
"optimize": config.optimize,
"cache": config.cache_enabled,
"rate_limit": config.rate_limit_enabled,
+ "disable_kompress": config.disable_kompress,
"memory": config.memory_enabled,
"learn": config.traffic_learning_enabled,
"code_graph": config.code_graph_watcher,
@@ -2995,6 +3000,7 @@ def _proxy_config_from_env() -> ProxyConfig:
bedrock_region=_get_env_str("HEADROOM_BEDROCK_REGION", "us-west-2"),
bedrock_profile=os.environ.get("AWS_PROFILE"),
anyllm_provider=_get_env_str("HEADROOM_ANYLLM_PROVIDER", "openai"),
+ disable_kompress=_get_env_bool("HEADROOM_DISABLE_KOMPRESS", False),
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),
@@ -3343,6 +3349,14 @@ if __name__ == "__main__":
"Also settable via HEADROOM_COMPRESS_USER_MESSAGES=1."
),
)
+ parser.add_argument(
+ "--disable-kompress",
+ action="store_true",
+ help=(
+ "Disable Kompress ML compression while keeping structural compression enabled. "
+ "Also settable via HEADROOM_DISABLE_KOMPRESS=1."
+ ),
+ )
parser.add_argument(
"--exclude-tools",
default=None,
@@ -3399,6 +3413,7 @@ if __name__ == "__main__":
optimize = env_optimize if not args.no_optimize else False
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)
# Set OpenRouter API key from CLI if provided
if hasattr(args, "openrouter_api_key") and args.openrouter_api_key:
@@ -3435,6 +3450,7 @@ if __name__ == "__main__":
else os.environ.get("HEADROOM_LOG_FILE"),
log_full_messages=args.log_messages or _get_env_bool("HEADROOM_LOG_MESSAGES", False),
code_aware_enabled=code_aware_enabled,
+ disable_kompress=disable_kompress,
# 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_cli_proxy_env.py b/tests/test_cli_proxy_env.py
index 78ff22482..969dd8e81 100644
--- a/tests/test_cli_proxy_env.py
+++ b/tests/test_cli_proxy_env.py
@@ -227,6 +227,41 @@ class TestCLIProxyEnvVars:
assert result.exit_code == 0, result.output
assert captured_config["config"].code_aware_enabled is True
+ def test_disable_kompress_from_env(self, runner):
+ """HEADROOM_DISABLE_KOMPRESS should be passed to ProxyConfig."""
+ captured_config = {}
+
+ def mock_run_server(config, **kwargs):
+ captured_config["config"] = config
+
+ with patch("headroom.proxy.server.run_server", mock_run_server):
+ result = runner.invoke(
+ main,
+ ["proxy"],
+ env={"HEADROOM_DISABLE_KOMPRESS": "1"},
+ catch_exceptions=False,
+ )
+
+ assert result.exit_code == 0, result.output
+ assert captured_config["config"].disable_kompress is True
+
+ def test_disable_kompress_from_cli_flag(self, runner):
+ """--disable-kompress should disable Kompress ML compression."""
+ captured_config = {}
+
+ def mock_run_server(config, **kwargs):
+ captured_config["config"] = config
+
+ with patch("headroom.proxy.server.run_server", mock_run_server):
+ result = runner.invoke(
+ main,
+ ["proxy", "--disable-kompress"],
+ catch_exceptions=False,
+ )
+
+ assert result.exit_code == 0, result.output
+ assert captured_config["config"].disable_kompress is True
+
def test_code_aware_flag_overrides_env_var(self, runner):
"""--code-aware should win over HEADROOM_CODE_AWARE_ENABLED=false."""
captured_config = {}
@@ -693,3 +728,12 @@ class TestArgparseBackendValidation:
parser.add_argument("--backend", default="anthropic")
args = parser.parse_args(["--backend", "litellm-hosted_vllm"])
assert args.backend == "litellm-hosted_vllm"
+
+ def test_proxy_config_from_env_reads_disable_kompress(self):
+ """The direct server env path should honor HEADROOM_DISABLE_KOMPRESS."""
+ from headroom.proxy.server import _proxy_config_from_env
+
+ with patch.dict(os.environ, {"HEADROOM_DISABLE_KOMPRESS": "1"}):
+ config = _proxy_config_from_env()
+
+ assert config.disable_kompress is True
diff --git a/tests/test_proxy_disable_kompress.py b/tests/test_proxy_disable_kompress.py
new file mode 100644
index 000000000..a45b590f1
--- /dev/null
+++ b/tests/test_proxy_disable_kompress.py
@@ -0,0 +1,51 @@
+"""Proxy configuration for disabling Kompress while keeping optimization on."""
+
+from __future__ import annotations
+
+import pytest
+
+pytest.importorskip("fastapi")
+
+from headroom.proxy.server import ProxyConfig, create_app
+from headroom.transforms import CompressionStrategy, ContentRouter
+
+
+def _proxy_router(config: ProxyConfig):
+ app = create_app(config)
+ proxy = app.state.proxy
+ return next(
+ transform
+ for transform in proxy.anthropic_pipeline.transforms
+ if isinstance(transform, ContentRouter)
+ )
+
+
+def test_disable_kompress_config_keeps_optimization_but_disables_ml_fallback() -> None:
+ router = _proxy_router(
+ ProxyConfig(
+ optimize=True,
+ disable_kompress=True,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ log_requests=False,
+ )
+ )
+
+ assert router.config.enable_kompress is False
+ assert router.config.fallback_strategy == CompressionStrategy.PASSTHROUGH
+
+
+def test_disable_kompress_defaults_to_existing_kompress_behavior() -> None:
+ router = _proxy_router(
+ ProxyConfig(
+ optimize=True,
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ log_requests=False,
+ )
+ )
+
+ assert router.config.enable_kompress is True
+ assert router.config.fallback_strategy == CompressionStrategy.KOMPRESS