mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
fix(proxy): fall back when forced Kompress is cold (#3381)
## Description Closes #3363 A savings profile can set `force_kompress=True`. When the Kompress model is installed but its weights are still cold or unavailable, the forced router selected `KOMPRESS`, which passed content through unchanged. That made structured payloads lose their normal SmartCrusher/log/search fallback and looked like a chat-completions compression outage. ## Type of Change - [x] Bug fix (non-breaking change) ## Changes Made - Check Kompress readiness before honoring forced routing. - Trigger the existing background model warmup when the model is cold. - Re-enter normal content detection while the model is unavailable, preserving structural compressors instead of silently forcing a no-op. - Extend `headroom doctor` to query `/health` and report the optional Kompress component as ready, disabled, or not ready with an actionable hint. ## Testing - [x] Focused doctor tests pass (`python -m pytest -q tests/test_cli_doctor.py`) - [x] Ruff check and format check pass on all changed files - [x] Python compile checks pass for all changed files - [x] Added a regression test for cold forced-Kompress routing with a structural fallback ### Test Output ```text python -m pytest -q tests/test_cli_doctor.py 96 passed in 31.66s python -m ruff check headroom/cli/doctor.py headroom/transforms/content_router.py tests/test_cli_doctor.py tests/test_agent_savings.py All checks passed! ``` ## Real Behavior Proof - Environment: Windows, Python 3.11.9; Headroom source checkout at the current `main` base. - Exact command / steps: The regression test supplies a cold Kompress implementation (`is_ready() == False`) and a structural log compressor, then runs `ContentRouter.compress()` with forced routing enabled. - Observed result: The router requests background warmup and chooses the structural `LOG` strategy, returning the compacted output rather than a forced-KOMPRESS passthrough. `headroom doctor` now surfaces a cold model as `not ready — content compression is passing through`. - Not tested: Full native Rust-backed proxy integration on this host. The repository's supported editable setup reached the Rust build but failed because the Windows MSVC linker is not installed (`link: extra operand`; the environment has no Visual Studio C++ build tools). ## Runtime Rollout Safety - Rollout-managed feature(s): None. - Minimum rollout channel: Default behavior is unchanged unless forced Kompress routing is enabled. - Stable/default behavior changed: Cold forced routing now uses the existing detector and safe structural compressor. - Kill switch / disable path: Existing Kompress disable settings remain unchanged. - Unsafe override required: No. - Qualification impact: None. - Rollback path: Revert this commit. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] One logical bug fix - [x] Added regression coverage - [x] Did not edit `CHANGELOG.md` --------- Signed-off-by: UniversePeak <UniversePeak@users.noreply.github.com> Co-authored-by: UniversePeak <UniversePeak@users.noreply.github.com>
This commit is contained in:
@@ -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),
|
||||
]
|
||||
|
||||
@@ -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, {})
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -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",
|
||||
|
||||
Reference in New Issue
Block a user