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.

fix(proxy): fall back when forced Kompress is cold (#3381)

宇宙的山峰ca54c2aba180
diff --git a/headroom/cli/doctor.py b/headroom/cli/doctor.py
index 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) -> CheckResu
return 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 None
stats = probe_json(f"{base_url}/stats", timeout=5.0) if livez else None
installed = 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.py
index 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 = False
detection = DetectionResult(ContentType.PLAIN_TEXT, 1.0, {})
diff --git a/tests/test_agent_savings.py b/tests/test_agent_savings.py
index aa7dcf6a7..c594afa82 100644
--- a/tests/test_agent_savings.py
+++ b/tests/test_agent_savings.py
@@ -4,6 +4,7 @@ import json
import logging
from importlib import import_module
from types import SimpleNamespace
+from unittest.mock import MagicMock
import pytest
from 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.py
index 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.py
index 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.MonkeyPa
def 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",