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(kompress): surface model-not-ready state via logs and health endpoint (#2034)

GUOHAO LIU12aa2cbf6cc8
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index dc375b5ac..d173e43bb 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -2306,6 +2306,11 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
url=_upstream_check_cache["url"],
error=_upstream_check_cache["error"],
),
+ "kompress": _component_health(
+ enabled=not config.disable_kompress,
+ ready=proxy.warmup.kompress.status == "loaded",
+ backend=proxy.warmup.kompress.info.get("backend", None),
+ ),
}
def _runtime_payload() -> dict[str, Any]:
@@ -2404,7 +2409,9 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
def _health_payload(*, include_config: bool) -> dict[str, Any]:
checks = _health_checks()
- ready = all(check["ready"] for check in checks.values())
+ # Kompress is an optional soft component: model downloads lazily on
+ # first use, so "not ready" (cold cache) must not degrade overall health.
+ ready = all(check["ready"] for name, check in checks.items() if name != "kompress")
payload: dict[str, Any] = {
"service": "headroom-proxy",
"status": "healthy" if ready else "unhealthy",
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.py
index 4d6cd9889..c9cddeeee 100644
--- a/headroom/transforms/content_router.py
+++ b/headroom/transforms/content_router.py
@@ -2362,6 +2362,16 @@ class ContentRouter(Transform):
if compressor:
if not compressor.is_ready():
compressor.ensure_background_load()
+ # Surface: warn once per ContentRouter instance so operators
+ # know compression is degraded — model not cached, or
+ # HuggingFace unreachable (corporate firewall, SSL, etc.).
+ if not getattr(self, "_kompress_warned", False):
+ logger.warning(
+ "Kompress model not ready; requests will not be "
+ "compressed. Check HuggingFace connectivity or "
+ "pre-download: headroom-ai[ml] + first-run warmup."
+ )
+ self._kompress_warned = True
else:
try:
result = compressor.compress(
@@ -2713,9 +2723,10 @@ class ContentRouter(Transform):
try:
backend = compressor.preload(allow_download=False)
except KompressModelNotCached:
- logger.info(
- "Kompress model not cached; deferring download to "
- "first use to keep startup non-blocking"
+ logger.warning(
+ "Kompress model not cached; compression disabled "
+ "until model is downloaded. Ensure HuggingFace is "
+ "accessible or pre-download with headroom-ai[ml]."
)
status["kompress"] = "deferred"
else: