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
fix(proxy): fall back when forced Kompress is cold (#3381)
宇宙的山峰ca54c2aba180
diff --git a/headroom/cli/doctor.py b/headroom/cli/doctor.pyindex 7f17e8774..3be931148 100644--- a/headroom/cli/doctor.py+++ b/headroom/cli/doctor.py@@ -581,6 +581,48 @@ def check_savings(stats: dict[str, Any] | None, savings_file: Path) -> CheckResureturn CheckResult(name=name, status=PASS, summary=f"{summary} ({source})")+def check_kompress_health(health: dict[str, Any] | None) -> CheckResult:+ """Report whether the optional Kompress model can actually run.++ ``/livez`` only proves that the proxy process is alive, and ``/stats``+ cannot distinguish a healthy zero-savings workload from a cold Kompress+ model. The health payload has the component-level readiness state needed+ to explain the "ML extras installed, but every request passes through"+ failure mode.+ """+ name = "kompress"+ if health is None:+ return CheckResult(name=name, status=SKIP, summary="proxy health endpoint not reachable")++ checks = health.get("checks")+ component = checks.get(name) if isinstance(checks, dict) else None+ if not isinstance(component, dict):+ return CheckResult(+ name=name,+ status=WARN,+ summary="proxy does not report Kompress readiness (older version?)",+ hint="restart the proxy on the current version",+ )++ if not bool(component.get("enabled", True)):+ return CheckResult(name=name, status=PASS, summary="disabled")++ backend = component.get("backend")+ backend_text = f" ({backend})" if backend else ""+ if bool(component.get("ready")):+ return CheckResult(name=name, status=PASS, summary=f"ready{backend_text}")++ return CheckResult(+ name=name,+ status=WARN,+ summary=f"not ready{backend_text} — content compression is passing through",+ hint=(+ "pre-download the Kompress model and retry; inspect /debug/warmup "+ "for the resolved load state"+ ),+ )++def check_budget(stats: dict[str, Any] | None) -> CheckResult:"""Is a spend budget configured on the proxy?"""name = "budget"@@ -720,6 +762,7 @@ def doctor(port: int, emit_json: bool) -> None:"""base_url = f"http://127.0.0.1:{port}"livez = probe_json(f"{base_url}/livez")+ health = probe_json(f"{base_url}/health", timeout=5.0) if livez else Nonestats = probe_json(f"{base_url}/stats", timeout=5.0) if livez else Noneinstalled = get_version()@@ -736,6 +779,7 @@ def doctor(port: int, emit_json: bool) -> None:check_wrap_marker_staleness(project_local_claude_settings),check_codex_routing(codex_config_path(), port),check_shell_env(os.environ, port),+ check_kompress_health(health),check_savings(stats, savings_path()),check_budget(stats),]diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex e00900eb7..2a9c0f8a3 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -2390,6 +2390,36 @@ class ContentRouter(Transform):"on",}+ def _force_kompress_ready(self) -> bool:+ """Return whether forced Kompress routing can actually run.++ ``force_kompress`` is an opt-in routing preference, not a reason to+ disable every other compressor. A cold or unavailable ML model used to+ turn otherwise compressible logs/JSON into a silent passthrough because+ the forced KOMPRESS strategy returned its input and the normal+ structural fallback was never considered. Keep the background warmup,+ but let the regular detector choose a safe structural compressor until+ the model is ready.+ """+ if not self.config.enable_kompress:+ return False+ try:+ compressor = self._get_kompress()+ except Exception:+ return False+ if compressor is None:+ return False+ try:+ ready = bool(compressor.is_ready())+ except Exception:+ return False+ if not ready:+ try:+ compressor.ensure_background_load()+ except Exception:+ logger.debug("Kompress background warmup failed", exc_info=True)+ return ready+def _kompress_model_ready(self) -> bool:"""Whether the ML compressor is ready (or deliberately disabled).@@ -2580,6 +2610,11 @@ class ContentRouter(Transform):# force Kompress, skip the full router detection path so large# proxy payloads do not pay for an unused strategy decision.force_kompress = bool(getattr(self, "_runtime_force_kompress", False))+ # Forced routing is only meaningful while the ML compressor is+ # ready. On a cold cache, preserve the normal content detector so+ # structured compressors can still make progress instead of the+ # forced passthrough masking them.+ force_kompress = force_kompress and self._force_kompress_ready()if force_kompress:mixed = Falsedetection = DetectionResult(ContentType.PLAIN_TEXT, 1.0, {})diff --git a/tests/test_agent_savings.py b/tests/test_agent_savings.pyindex aa7dcf6a7..c594afa82 100644--- a/tests/test_agent_savings.py+++ b/tests/test_agent_savings.py@@ -4,6 +4,7 @@ import jsonimport loggingfrom importlib import import_modulefrom types import SimpleNamespace+from unittest.mock import MagicMockimport pytestfrom click.testing import CliRunner@@ -288,6 +289,35 @@ def test_compress_savings_profile_does_not_mutate_supplied_config(monkeypatch) -assert config.min_tokens_to_compress == 999+def test_force_kompress_falls_back_to_structural_compression_when_cold(monkeypatch):+ """A cold forced-ML profile must not hide safe content routing."""+ import headroom.transforms.content_router as router_mod++ router = ContentRouter(ContentRouterConfig())+ compressor = SimpleNamespace(is_ready=lambda: False, ensure_background_load=MagicMock())+ log_compressor = SimpleNamespace(+ compress=lambda content, bias=1.0: SimpleNamespace(compressed="ERROR: compacted")+ )+ router._get_kompress = lambda: compressor+ router._get_log_compressor = lambda: log_compressor+ router._runtime_force_kompress = True+ router._runtime_skip_kompress = False+ router._runtime_target_ratio = None+ router.config.enable_log_compressor = True+ monkeypatch.setattr(+ router_mod,+ "_detect_content",+ lambda content: router_mod.DetectionResult(router_mod.ContentType.BUILD_OUTPUT, 1.0, {}),+ )+ monkeypatch.setattr(router_mod, "is_mixed_content", lambda content: False)++ result = router.compress("ERROR: repeated output\\n" * 40)++ assert result.compressed == "ERROR: compacted"+ assert result.strategy_used == CompressionStrategy.LOG+ compressor.ensure_background_load.assert_called_once()++def test_wrap_agent_savings_profile_is_opt_in(monkeypatch) -> None:monkeypatch.delenv("HEADROOM_SAVINGS_PROFILE", raising=False)diff --git a/tests/test_cli_doctor.py b/tests/test_cli_doctor.pyindex 862009a8d..7b6ff021c 100644--- a/tests/test_cli_doctor.py+++ b/tests/test_cli_doctor.py@@ -20,6 +20,7 @@ from headroom.cli.doctor import (check_claude_routing,check_codex_routing,check_deployments,+ check_kompress_health,check_proxy_liveness,check_savings,check_shell_env,@@ -45,6 +46,38 @@ STATS_OK = {}+class TestKompressHealth:+ def test_missing_health_endpoint_skips(self):+ result = check_kompress_health(None)+ assert result.status == SKIP+ assert "health endpoint" in result.summary++ def test_older_proxy_without_component_warns(self):+ result = check_kompress_health({"checks": {}})+ assert result.status == WARN+ assert "readiness" in result.summary++ def test_disabled_passes(self):+ result = check_kompress_health({"checks": {"kompress": {"enabled": False}}})+ assert result.status == PASS+ assert result.summary == "disabled"++ def test_ready_reports_backend(self):+ result = check_kompress_health(+ {"checks": {"kompress": {"enabled": True, "ready": True, "backend": "onnx"}}}+ )+ assert result.status == PASS+ assert result.summary == "ready (onnx)"++ def test_cold_model_warns_with_action(self):+ result = check_kompress_health(+ {"checks": {"kompress": {"enabled": True, "ready": False, "status": "degraded"}}}+ )+ assert result.status == WARN+ assert "passing through" in result.summary+ assert "/debug/warmup" in (result.hint or "")++class TestProxyLiveness:def test_down_is_fail_with_hint(self):result = check_proxy_liveness(None, "http://127.0.0.1:8787")diff --git a/tests/test_transforms_content_router.py b/tests/test_transforms_content_router.pyindex 973cb843d..7ff3619b6 100644--- a/tests/test_transforms_content_router.py+++ b/tests/test_transforms_content_router.py@@ -368,6 +368,7 @@ def test_content_router_strategy_and_compress_paths(monkeypatch: pytest.MonkeyPadef test_force_kompress_bypasses_content_detection(monkeypatch: pytest.MonkeyPatch) -> None:router = ContentRouter()router._runtime_force_kompress = True+ monkeypatch.setattr(router, "_force_kompress_ready", lambda: True)pure_result = RouterCompressionResult(compressed="pure",original="pure",