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(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.pyindex 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.pyindex 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 = Trueelse: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: