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:
宇宙的山峰
2026-09-24 16:58:40 -05:00
committed by GitHub
co-authored by UniversePeak
parent f12e3fbeed
commit ca54c2aba1
5 changed files with 143 additions and 0 deletions
+44
View File
@@ -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),
]
+35
View File
@@ -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, {})
+30
View File
@@ -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)
+33
View File
@@ -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")
+1
View File
@@ -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",