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(cli): proxy/perf/wrap UX cleanup + perf --hours correctness
chopratejas265554d4adee
diff --git a/headroom/cli/mcp.py b/headroom/cli/mcp.pyindex 44d466e17..260ea82d9 100644--- a/headroom/cli/mcp.py+++ b/headroom/cli/mcp.py@@ -76,6 +76,15 @@ def mcp() -> None:3. Claude sees compressed summaries with hash markers4. When Claude needs full details, it calls headroom_retrieve5. The MCP server fetches original content from the proxy++ \b+ Note on tool naming: MCP clients display tools as+ `mcp__<server>__<tool>`. Our server is named "headroom" and our+ tools are named headroom_retrieve / headroom_compress / etc., so+ Claude Code shows them as `mcp__headroom__headroom_retrieve`. The+ "headroom" doubling is normal MCP namespacing — not a bug. The+ proxy's compression markers (and any docs/prompts) reference the+ bare tool name `headroom_retrieve`."""passdiff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.pyindex 47333ec35..93ee7d1e8 100644--- a/headroom/cli/proxy.py+++ b/headroom/cli/proxy.py@@ -62,7 +62,11 @@ from .main import main@click.option("--mode",default=None,+ metavar="[token|cache]",type=click.Choice(+ # Canonical modes first; legacy aliases follow for backward compatibility.+ # `metavar` above hides the alias clutter from --help; users see "[token|cache]"+ # while internal callers passing "token_mode"/"cost_savings"/etc. still validate.["token","cache",@@ -71,12 +75,15 @@ from .main import main"token_savings","cost_savings","token_headroom",- ]+ ],+ case_sensitive=False,),help=(- "Optimization mode: token (prioritize compression) or cache "- "(freeze prior turns for prefix-cache stability). "- "Legacy aliases are accepted. Default: token. Env: HEADROOM_MODE"+ "Optimization mode (default: token).\n"+ " token — prioritize compression; prior turns may be rewritten for max savings.\n"+ " cache — freeze prior turns to maximise provider prefix-cache hit rate.\n"+ "Legacy aliases (token_mode, token_savings, token_headroom, cache_mode, "+ "cost_savings) are still accepted. Env: HEADROOM_MODE."),)@click.option(@@ -184,11 +191,32 @@ from .main import mainenvvar="HEADROOM_BUDGET",help="Daily budget limit in USD (env: HEADROOM_BUDGET)",)-# Code graph: indexes project + watches files for live reindex via codebase-memory-mcp+# Code-aware compression (AST-based, requires `pip install headroom-ai[code]`).+# Pair of flags so users can override the env-var default in either direction.+# We resolve HEADROOM_CODE_AWARE_ENABLED in the body (not via Click's envvar=),+# because Click's envvar handling for paired bool flags is brittle in older+# Click versions.+ "--code-aware/--no-code-aware",+ "code_aware_flag",+ default=None,+ help=(+ "Enable/disable AST-based code compression. Requires the optional "+ "tree-sitter dependency: pip install headroom-ai[code]. "+ "Default: disabled. Env: HEADROOM_CODE_AWARE_ENABLED=1 to enable."+ ),+)+# Code graph: indexes project + watches files for live reindex via codebase-memory-mcp.+# Only useful when the proxy is launched from a project root — it indexes the+# current working directory.@click.option("--code-graph",is_flag=True,- help="Enable code graph intelligence (indexes project, watches files for live reindex via codebase-memory-mcp)",+ help=(+ "Enable code graph intelligence: indexes the current working directory "+ "and watches files for live reindex via codebase-memory-mcp. Only useful "+ "when the proxy is launched from a project root."+ ),)# Read lifecycle (ON by default: compresses stale/superseded Read outputs)@click.option(@@ -359,6 +387,7 @@ def proxy(log_file: str | None,log_messages: bool,budget: float | None,+ code_aware_flag: bool | None,code_graph: bool,no_read_lifecycle: bool,memory: bool,@@ -514,6 +543,17 @@ def proxy(log_full_messages=log_messagesor os.environ.get("HEADROOM_LOG_MESSAGES", "").lower() in ("true", "1", "yes", "on"),budget_limit_usd=budget,+ # Code-aware compression resolution:+ # 1. Explicit --code-aware / --no-code-aware always wins.+ # 2. Otherwise read HEADROOM_CODE_AWARE_ENABLED (truthy = on).+ # 3. Otherwise default off — matches the prior cli/proxy.py behavior so+ # existing users see no change unless they opt in.+ code_aware_enabled=(+ bool(code_aware_flag)+ if code_aware_flag is not None+ else os.environ.get("HEADROOM_CODE_AWARE_ENABLED", "").strip().lower()+ in ("true", "1", "yes", "on")+ ),# Code graph: live file watcher for incremental reindexingcode_graph_watcher=code_graph,# Read lifecycle: ON by default (use --no-read-lifecycle to disable)@@ -660,6 +700,13 @@ Memory (Multi-Provider):f"(available: {','.join(_ext_available)})")+ # Code-aware status line — same logic the inner banner uses, surfaced here+ # so the click-CLI banner is a complete picture (avoids the dual-banner+ # confusion this branch retired).+ from headroom.proxy.server import _get_code_aware_banner_status++ code_aware_line = f" Code-Aware: {_get_code_aware_banner_status(config)}"+click.echo(f"""╔═══════════════════════════════════════════════════════════════════════╗║ HEADROOM PROXY ║@@ -675,6 +722,7 @@ Starting proxy server...Rate Limit: {"ENABLED" if config.rate_limit_enabled else "DISABLED"}Memory: {memory_status}License: {license_status}+{code_aware_line}{extensions_line}{stateless_line}{telemetry_line}{backend_section}@@ -700,11 +748,15 @@ Press Ctrl+C to stop.""")try:- run_kwargs: dict[str, int] = {}+ run_kwargs: dict[str, Any] = {}if workers != 1:run_kwargs["workers"] = workersif limit_concurrency != 1000:run_kwargs["limit_concurrency"] = limit_concurrency+ # Suppress run_server's legacy banner — the click CLI already printed+ # a richer one above. Direct `python -m headroom.proxy.server` keeps+ # the legacy banner via run_server's default.+ run_kwargs["print_banner"] = Falserun_server(config, **run_kwargs)except KeyboardInterrupt:click.echo("\nShutting down...")diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex af0112c74..4d22eeda6 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -1298,13 +1298,28 @@ def wrap() -> None:the target tool so all API calls route through Headroom automatically.\b- Supported tools:+ Supported tools (one Click subcommand per tool):headroom wrap claude # Claude Code (Anthropic)- headroom wrap copilot -- --model claude-sonnet-4-20250514headroom wrap codex # OpenAI Codex CLI+ headroom wrap copilot -- --model claude-sonnet-4-20250514headroom wrap aider # Aiderheadroom wrap cursor # Cursor (prints config instructions)headroom wrap openclaw # OpenClaw plugin bootstrap++ \b+ `wrap` vs `proxy`:+ - `headroom wrap <tool>` — convenience: starts the proxy for you,+ sets the right env vars, and launches the wrapped CLI.+ - `headroom proxy` — just the proxy. Use this with any+ OpenAI/Anthropic-compatible client by setting+ ANTHROPIC_BASE_URL / OPENAI_BASE_URL yourself. Required for+ tools without a dedicated `wrap` subcommand+ (e.g. opencode, Cline, Continue).++ \b+ Note: `headroom wrap opencode` does NOT exist. For opencode, run+ `headroom proxy` and point opencode at it via OPENAI_BASE_URL.+ `openclaw` is a separate tool — different from opencode."""diff --git a/headroom/perf/analyzer.py b/headroom/perf/analyzer.pyindex e89851c80..b52e76ddf 100644--- a/headroom/perf/analyzer.py+++ b/headroom/perf/analyzer.py@@ -13,6 +13,7 @@ from __future__ import annotationsimport loggingimport refrom dataclasses import dataclass, field+from datetime import datetime, timedeltafrom headroom import paths as _paths@@ -213,6 +214,31 @@ class PerfReport:toin_records: list[ToinRecord] = field(default_factory=list)log_files_read: int = 0total_lines_parsed: int = 0+ # Window covered by the report. `requested_hours` is what the caller+ # asked for; `oldest_kept_ts` / `newest_kept_ts` are the actual+ # timestamps of the oldest and newest records that survived the+ # filter (may be narrower if the log doesn't go back that far).+ # All optional so existing callers keep working.+ requested_hours: float | None = None+ oldest_kept_ts: str | None = None+ newest_kept_ts: str | None = None+ records_filtered_out: int = 0+++# Log timestamps are emitted by Python's `logging` formatter as+# `YYYY-MM-DD HH:MM:SS,fff`. We keep the parser permissive so the perf+# CLI never throws on a stray malformed line — unparsable records are+# just kept (better to over-report than to silently drop data).+_LOG_TS_FMT = "%Y-%m-%d %H:%M:%S,%f"+++def _parse_log_ts(ts: str | None) -> datetime | None:+ if not ts:+ return None+ try:+ return datetime.strptime(ts, _LOG_TS_FMT)+ except ValueError:+ return Nonedef parse_log_files(last_n_hours: float = 168.0) -> PerfReport:@@ -220,15 +246,40 @@ def parse_log_files(last_n_hours: float = 168.0) -> PerfReport:Args:last_n_hours: Only include records from the last N hours (default 7 days).+ Records with un-parseable timestamps are kept (fail-open) — the+ window in the report header reflects the actual timestamps that+ survived the filter, so the user can see whether the log went+ back far enough.Returns:PerfReport with all parsed records."""report = PerfReport()+ report.requested_hours = last_n_hoursif not LOG_DIR.exists():return report+ cutoff = datetime.now() - timedelta(hours=last_n_hours) if last_n_hours > 0 else None++ def _within_window(ts_str: str | None) -> bool:+ # Fail-open: records without a parseable timestamp are kept. The+ # alternative (silent drop) makes `headroom perf` lie about coverage.+ if cutoff is None:+ return True+ ts = _parse_log_ts(ts_str)+ if ts is None:+ return True+ return ts >= cutoff++ def _track_window(ts_str: str | None) -> None:+ if not ts_str:+ return+ if report.oldest_kept_ts is None or ts_str < report.oldest_kept_ts:+ report.oldest_kept_ts = ts_str+ if report.newest_kept_ts is None or ts_str > report.newest_kept_ts:+ report.newest_kept_ts = ts_str+# Collect log files: proxy.log, proxy.log.1, proxy.log.2, ...log_files = sorted(LOG_DIR.glob("proxy.log*"), key=lambda p: p.stat().st_mtime)@@ -260,9 +311,14 @@ def parse_log_files(last_n_hours: float = 168.0) -> PerfReport:else:# Old comma-separated formattransforms = transforms_str.split(",")+ ts = m.group("ts")+ if not _within_window(ts):+ report.records_filtered_out += 1+ continue+ _track_window(ts)report.perf_records.append(PerfRecord(- timestamp=m.group("ts"),+ timestamp=ts,request_id=m.group("rid"),model=kv.get("model", ""),num_messages=int(kv.get("msgs", 0)),@@ -283,6 +339,10 @@ def parse_log_files(last_n_hours: float = 168.0) -> PerfReport:m2 = _ROUTER_RE.search(line)if m2:ts = line[:23]+ if not _within_window(ts):+ report.records_filtered_out += 1+ continue+ _track_window(ts)detail = m2.group("detail")rec = RouterRecord(timestamp=ts,@@ -312,6 +372,10 @@ def parse_log_files(last_n_hours: float = 168.0) -> PerfReport:m3 = _TRANSFORM_RE.search(line)if m3:ts = line[:23]+ if not _within_window(ts):+ report.records_filtered_out += 1+ continue+ _track_window(ts)report.transform_records.append(TransformRecord(timestamp=ts,@@ -327,6 +391,10 @@ def parse_log_files(last_n_hours: float = 168.0) -> PerfReport:m4 = _TOIN_RE.search(line)if m4:ts = line[:23]+ if not _within_window(ts):+ report.records_filtered_out += 1+ continue+ _track_window(ts)report.toin_records.append(ToinRecord(timestamp=ts,@@ -357,6 +425,21 @@ def format_report(report: PerfReport) -> str:# Headerlines.append("Headroom Performance Report")lines.append("=" * 60)+ if report.requested_hours is not None:+ if report.oldest_kept_ts and report.newest_kept_ts:+ window_str = (+ f"Window: last {report.requested_hours:g}h "+ f"(actual data: {report.oldest_kept_ts[:19]} → "+ f"{report.newest_kept_ts[:19]})"+ )+ else:+ window_str = f"Window: last {report.requested_hours:g}h (no records found in window)"+ lines.append(window_str)+ if report.records_filtered_out > 0:+ lines.append(+ f"Records outside window: {report.records_filtered_out:,} "+ "(filtered out — increase --hours to include them)"+ )lines.append("")records = report.perf_records@@ -501,7 +584,7 @@ def format_report(report: PerfReport) -> str:lines.append(" ! Excluded tools dominate — consider compressing stale Read outputs")lines.append("")- # TOIN status+ # TOIN status — log-derived counters first, then live-store highlights.if report.toin_records:latest = report.toin_records[-1]lines.append("TOIN Learning")@@ -513,6 +596,17 @@ def format_report(report: PerfReport) -> str:lines.append(" ! 0% retrieval rate — TOIN learning but never used")lines.append("")+ # TOIN highlights — read the live on-disk pattern store and surface+ # strategy distribution + top high-impact patterns in human-readable+ # form. Pattern keys are opaque hashes, so the actionable signal is+ # *which strategies are winning* and *how many patterns have crossed+ # the recommendation threshold*. Best-effort: if TOIN isn't installed+ # or the store is empty, we skip the section silently.+ toin_lines = _format_toin_highlights()+ if toin_lines:+ lines.extend(toin_lines)+ lines.append("")+# Recommendationsrecommendations = _generate_recommendations(report)if recommendations:@@ -531,6 +625,88 @@ def format_report(report: PerfReport) -> str:return "\n".join(lines)+def _format_toin_highlights() -> list[str]:+ """Render a human-readable TOIN highlights block from the live store.++ Returns an empty list when TOIN is unavailable or has no patterns.+ Pattern keys (auth_mode, model_family, structure_hash) are opaque+ hashes so we don't print them as rows — instead we group by the+ learned ``optimal_strategy`` (a human-readable string like+ ``"lossless:table(240->len=7026)"``) and surface the highest-impact+ slices via ``avg_token_reduction``.+ """+ try:+ from headroom.telemetry.toin import get_toin+ except ImportError:+ return []++ try:+ pairs = get_toin().iter_patterns()+ except Exception: # noqa: BLE001 — perf must never fail on TOIN errors+ return []++ if not pairs:+ return []++ # Strategy distribution: how many patterns settled on each strategy.+ strategy_counts: dict[str, int] = {}+ for _key, pattern in pairs:+ strategy = pattern.optimal_strategy or "default"+ strategy_counts[strategy] = strategy_counts.get(strategy, 0) + 1++ # Top patterns by avg token reduction (the high-impact learnings).+ by_impact = sorted(+ pairs,+ key=lambda kp: kp[1].avg_token_reduction,+ reverse=True,+ )[:5]++ # How many patterns have enough samples to drive a recommendation.+ # Falls back to 0 if the threshold attr isn't reachable.+ try:+ from headroom.telemetry.toin import get_toin as _get++ threshold = _get()._config.min_samples_for_recommendation+ except Exception: # noqa: BLE001+ threshold = 1+ qualified = sum(1 for _k, p in pairs if p.sample_size >= threshold)++ lines: list[str] = []+ lines.append("TOIN Highlights (live store)")+ lines.append("-" * 40)+ lines.append(+ f" {qualified}/{len(pairs)} patterns have ≥{threshold} samples "+ f"(eligible for `python -m headroom.cli.toin_publish`)"+ )+ lines.append("")+ lines.append(" Strategy distribution:")+ for strategy, count in sorted(strategy_counts.items(), key=lambda kv: kv[1], reverse=True)[:8]:+ lines.append(f" {count:>4} pattern(s) {strategy}")++ # Only surface patterns with non-trivial impact AND a non-default+ # strategy — single-digit-token "wins" against the default strategy+ # are noise, not insight.+ impact_rows = [+ (kp[1].avg_token_reduction, kp[1].total_compressions, kp[1].optimal_strategy or "default")+ for kp in by_impact+ if kp[1].avg_token_reduction >= 50 and (kp[1].optimal_strategy or "default") != "default"+ ]+ if impact_rows:+ lines.append("")+ lines.append(" Top patterns by avg token reduction:")+ for avg_red, n, strategy in impact_rows:+ lines.append(f" {avg_red:>7.0f} tok avg ({n:>3} compression(s)) {strategy}")++ if qualified == 0 and len(pairs) > 0:+ lines.append("")+ lines.append(+ f" ! No pattern has reached {threshold} samples — TOIN is still warming up. "+ "Recommendations TOML will be empty until traffic grows."+ )++ return lines++def _generate_recommendations(report: PerfReport) -> list[str]:"""Generate actionable recommendations from the report data."""recs: list[str] = []diff --git a/headroom/providers/openclaw/wrap.py b/headroom/providers/openclaw/wrap.pyindex 2ccbeadf0..664128ea9 100644--- a/headroom/providers/openclaw/wrap.py+++ b/headroom/providers/openclaw/wrap.py@@ -35,6 +35,15 @@ def decode_entry_json(raw_value: str | None) -> Any | None:return raw_value+# Keys we know newer openclaw plugin schemas reject when echoed back.+# We strip them defensively from `existing_entry` so a stale entry left+# over from an older Headroom or older OpenClaw install doesn't cause+# `openclaw config set` to fail with "Unrecognized key". The list is+# narrow on purpose — anything else is assumed user-managed and+# preserved verbatim.+_LEGACY_REJECTED_TOP_LEVEL_KEYS: frozenset[str] = frozenset({"mcpServers"})++def build_plugin_entry(*,existing_entry: Any,@@ -46,7 +55,8 @@ def build_plugin_entry(enabled: bool,) -> dict[str, object]:"""Merge managed Headroom plugin settings with any existing entry payload."""- base_entry = existing_entry if isinstance(existing_entry, dict) else {}+ raw_base = existing_entry if isinstance(existing_entry, dict) else {}+ base_entry = {k: v for k, v in raw_base.items() if k not in _LEGACY_REJECTED_TOP_LEVEL_KEYS}existing_config = base_entry.get("config")next_config = dict(existing_config) if isinstance(existing_config, dict) else {}diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 8e285077b..b7ffcfc0f 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -2598,14 +2598,15 @@ def _get_code_aware_banner_status(config: ProxyConfig) -> str:return "NOT INSTALLED (pip install headroom-ai[code])"else:if is_tree_sitter_available():- return "DISABLED (remove --no-code-aware to enable)"- return "DISABLED"+ return "DISABLED (--code-aware or HEADROOM_CODE_AWARE_ENABLED=1 to enable)"+ return "DISABLED (install headroom-ai[code] to enable)"def run_server(config: ProxyConfig | None = None,workers: int = 1,limit_concurrency: int = 1000,+ print_banner: bool = True,):"""Run the proxy server.@@ -2613,6 +2614,11 @@ def run_server(config: Proxy configurationworkers: Number of worker processes (use N for multi-core scaling)limit_concurrency: Max concurrent connections before 503 response+ print_banner: When False, skip the legacy ASCII banner. The+ Click CLI (`headroom proxy`) prints its own startup banner+ before calling this — printing a second banner here is the+ "dual banner" UX issue. Direct `python -m headroom.proxy.server`+ still gets the banner since it has no other startup output."""if not FASTAPI_AVAILABLE:print("ERROR: FastAPI required. Install: pip install fastapi uvicorn httpx")@@ -2631,7 +2637,8 @@ def run_server(bedrock_region=config.bedrock_region,)- print(f"""+ if print_banner:+ print(f"""╔══════════════════════════════════════════════════════════════════════╗║ HEADROOM PROXY SERVER ║╠══════════════════════════════════════════════════════════════════════╣diff --git a/pyproject.toml b/pyproject.tomlindex 90828428a..64af1b81b 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -75,17 +75,13 @@ proxy = [code = ["tree-sitter-language-pack>=0.10.0",]-# ML-based compression with Kompress (ModernBERT)+# ML-based compression with Kompress (ModernBERT).+# (The legacy [llmlingua] extra was removed in 0.9.x — no live code path used it.+# Use [ml] for the supported ML compression dependencies.)ml = ["torch>=2.0.0","transformers>=4.30.0",]-# Legacy ML compression (LLMLingua-2 — use [ml] instead for Kompress)-llmlingua = [- "llmlingua>=0.2.0",- "torch>=2.0.0",- "transformers>=4.30.0",-]# Memory system (hierarchical memory with vector search)memory = ["hnswlib>=0.8.0",diff --git a/tests/test_anthropic_pre_upstream_backpressure.py b/tests/test_anthropic_pre_upstream_backpressure.pyindex 237536e77..97aea531c 100644--- a/tests/test_anthropic_pre_upstream_backpressure.py+++ b/tests/test_anthropic_pre_upstream_backpressure.py@@ -721,7 +721,7 @@ def _run_cli_capture(args: list[str], env: dict | None = None) -> ProxyConfig:captured: dict[str, ProxyConfig] = {}orig_run = server_mod.run_server- def _fake_run(config: ProxyConfig): # noqa: D401 - stub+ def _fake_run(config: ProxyConfig, **_kwargs): # noqa: D401 - stubcaptured["config"] = configreturn 0diff --git a/tests/test_cli_proxy_env.py b/tests/test_cli_proxy_env.pyindex c8c910493..b240c9c9e 100644--- a/tests/test_cli_proxy_env.py+++ b/tests/test_cli_proxy_env.py@@ -30,7 +30,7 @@ class TestCLIProxyEnvVars:"""HEADROOM_HOST env var should be passed to ProxyConfig."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -48,7 +48,7 @@ class TestCLIProxyEnvVars:"""HEADROOM_PORT env var should be passed to ProxyConfig."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -66,7 +66,7 @@ class TestCLIProxyEnvVars:"""HEADROOM_BUDGET env var should be passed to ProxyConfig."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -84,7 +84,7 @@ class TestCLIProxyEnvVars:"""OPENAI_TARGET_API_URL env var should be passed to ProxyConfig."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -102,7 +102,7 @@ class TestCLIProxyEnvVars:"""GEMINI_TARGET_API_URL env var should be passed to ProxyConfig."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -120,7 +120,7 @@ class TestCLIProxyEnvVars:"""--openai-api-url CLI flag should take precedence."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -137,7 +137,7 @@ class TestCLIProxyEnvVars:"""CLI flag should take precedence over env var."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -155,7 +155,7 @@ class TestCLIProxyEnvVars:"""Without env var or flag, openai_api_url should be None."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = config# Ensure the env var is not set@@ -178,7 +178,7 @@ class TestCLIProxyEnvVars:"""Both OPENAI and GEMINI target URLs can be set via env."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -200,7 +200,7 @@ class TestCLIProxyEnvVars:"""Fast-fail CLI flags should map into ProxyConfig."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -243,7 +243,12 @@ class TestCLIProxyEnvVars:assert result.exit_code == 0, result.outputassert captured["config"].max_connections == 200assert captured["config"].max_keepalive_connections == 50- assert captured["kwargs"] == {"workers": 4, "limit_concurrency": 250}+ # Click CLI also passes `print_banner=False` to suppress the legacy+ # run_server banner (cli/proxy.py prints its own). Assert the+ # production-scaling keys we care about, not the full kwargs dict.+ assert captured["kwargs"]["workers"] == 4+ assert captured["kwargs"]["limit_concurrency"] == 250+ assert captured["kwargs"].get("print_banner") is Falsedef test_production_scaling_cli_flags_override_env_vars(self, runner):captured = {}@@ -278,7 +283,11 @@ class TestCLIProxyEnvVars:assert result.exit_code == 0, result.outputassert captured["config"].max_connections == 150assert captured["config"].max_keepalive_connections == 25- assert captured["kwargs"] == {"workers": 3, "limit_concurrency": 125}+ # Click CLI also passes `print_banner=False`. Assert production+ # scaling keys explicitly rather than the full kwargs dict.+ assert captured["kwargs"]["workers"] == 3+ assert captured["kwargs"]["limit_concurrency"] == 125+ assert captured["kwargs"].get("print_banner") is Falseclass TestCLIProxyBackend:@@ -288,7 +297,7 @@ class TestCLIProxyBackend:"""--backend litellm-hosted_vllm should be accepted (not rejected)."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -305,7 +314,7 @@ class TestCLIProxyBackend:"""--backend litellm-vertex should be accepted."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -322,7 +331,7 @@ class TestCLIProxyBackend:"""Full vLLM setup: litellm backend + OPENAI_TARGET_API_URL."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -350,7 +359,7 @@ class TestCLIAnyllmProviderEnv:"""HEADROOM_ANYLLM_PROVIDER env var should override the default."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):@@ -368,7 +377,7 @@ class TestCLIAnyllmProviderEnv:"""--anyllm-provider flag should still work."""captured_config = {}- def mock_run_server(config):+ def mock_run_server(config, **kwargs):captured_config["config"] = configwith patch("headroom.proxy.server.run_server", mock_run_server):diff --git a/tests/test_provider_openclaw_wrap.py b/tests/test_provider_openclaw_wrap.pyindex 5025aa6e0..be24c82ca 100644--- a/tests/test_provider_openclaw_wrap.py+++ b/tests/test_provider_openclaw_wrap.py@@ -117,3 +117,34 @@ def test_build_unwrap_entry_disables_plugin_and_removes_managed_keys_only() -> Ndef test_build_unwrap_entry_handles_non_mapping_input() -> None:# Arrange / Act / Assertassert build_unwrap_entry("not-a-dict") == {"enabled": False, "config": {}}+++def test_build_plugin_entry_strips_mcpServers_from_existing_entry() -> None:+ """Newer OpenClaw schemas reject `mcpServers` at the plugin-entry root.++ `headroom init -g` was failing with `Config invalid: Unrecognized+ key: "mcpServers"` because the prior plugin entry in the user's+ config still had that legacy field, and we were spreading it back in+ via `**existing_entry`. Pin the strip so we don't regress.+ """+ existing_entry = {+ "enabled": True,+ "name": "headroom",+ "mcpServers": {"some": "stale-block"}, # legacy, must be removed+ "config": {"keep": "value"},+ }++ entry = build_plugin_entry(+ existing_entry=existing_entry,+ proxy_port=8787,+ startup_timeout_ms=1500,+ python_path=None,+ no_auto_start=False,+ gateway_provider_ids=None,+ enabled=True,+ )++ assert "mcpServers" not in entry+ assert entry["enabled"] is True+ assert entry["name"] == "headroom"+ assert entry["config"]["keep"] == "value"diff --git a/wiki/ARCHITECTURE.md b/wiki/ARCHITECTURE.mdindex 93d815aba..497e6b63f 100644--- a/wiki/ARCHITECTURE.md+++ b/wiki/ARCHITECTURE.md@@ -239,32 +239,18 @@ analysis = {----#### Transform 4: LLMLingua Compressor (Optional)+#### Transform 4: ML Compressor (Optional, Kompress)**When to use:** Maximum compression needed and latency is acceptable.-```python-# Opt-in ML-based compression using Microsoft's LLMLingua-2-# BERT-based token classifier trained via GPT-4 distillation--# Before: Long tool output text-"The function processUserData takes a user object and validates all fields..."--# After: Compressed while preserving semantic meaning-"function processUserData validates user fields..."-```--**Key characteristics:**-- Uses `microsoft/llmlingua-2-xlm-roberta-large-meetingbank` model-- Auto-detects content type (code, JSON, text) for optimal compression rates-- Stores original in CCR for retrieval if needed-- Adds 50-200ms latency per request-- Requires ~1GB RAM when loaded+The proxy ships an opt-in ML compression path backed by **Kompress**+(ModernBERT-based token classifier). Install with `pip install+'headroom-ai[ml]'`; see `wiki/transforms.md` for current configuration.-**Proxy integration (opt-in):**-```bash-headroom proxy --llmlingua --llmlingua-device cuda-```+**Note:** The earlier LLMLingua-2 integration (`--llmlingua` flag, the+`headroom-ai[llmlingua]` extra, and the `LLMLinguaCompressor` class) was+retired and replaced by Kompress. `pip install 'headroom-ai[llmlingua]'`+no longer resolves; use `[ml]` instead.---@@ -418,8 +404,8 @@ def apply(self, messages, ...):# - Compresses to 17 points (preserving spike)# - Factors out constant "host" field- # Transform 3: LLMLingua (if enabled via --llmlingua)- # - ML-based compression on remaining long text+ # Transform 3: Kompress ML compressor (opt-in via headroom-ai[ml])+ # - ModernBERT-based compression on remaining long text# - Auto-detects content type for optimal rate# - Stores original in CCR for retrieval@@ -1082,7 +1068,7 @@ headroom/│ ├── rolling_window.py # Token limit enforcement (position-based)│ ├── intelligent_context.py # Semantic context management (score-based)│ ├── scoring.py # Message importance scoring-│ └── llmlingua_compressor.py # ML-based compression (opt-in)+│ └── (legacy llmlingua_compressor.py removed — see [ml] extra for Kompress)│├── cache/ # CCR Architecture - Caching & Storage│ ├── compression_store.py # Phase 1: Store original contentdiff --git a/wiki/LIMITATIONS.md b/wiki/LIMITATIONS.mdindex 4dfe1f683..0323d16f3 100644--- a/wiki/LIMITATIONS.md+++ b/wiki/LIMITATIONS.md@@ -73,24 +73,23 @@ SmartCrusher doesn't use fixed K values. It uses information-theoretic sizing:These are kept even if they exceed the K budget.-## Text Compression (LLMLingua)+## ML Text Compression (Kompress, opt-in)-- **Requires**: `headroom-ai[llmlingua]` — downloads ~2GB model, needs ~1GB RAM-- **First call**: 10-30s model load latency (cached globally after)-- **Sequence length**: Content chunked at 512 tokens (model limit)-- **Content < 100 tokens**: Skipped-- **Latency**: Adds overhead that doesn't break even on fast models (GPT-4o Mini, Sonnet). Use for **cost savings**, not speed+- **Requires**: `headroom-ai[ml]` — downloads model weights and needs GPU/CPU RAM for inference+- **First call**: model-load latency (cached globally after)+- **Latency**: Adds overhead that doesn't break even on fast models. Use for **cost savings**, not speed- **Thread safety**: Single global model instance with lock — sequential access under concurrency+> The earlier LLMLingua-2 integration (`headroom-ai[llmlingua]`) was retired and is no longer installable.+## Error HandlingAll compressors follow the same principle: **fail gracefully, return original content unchanged**.- Invalid JSON → passthrough (no error raised)-- AST parse failure in CodeCompressor → falls back to original or LLMLingua+- AST parse failure in CodeCompressor → falls back to original- Compression makes output larger → original returned-- Missing optional dependencies (tree-sitter, LLMLingua) → passthrough with warning log-- **One exception**: LLMLingua out-of-memory during model loading raises `RuntimeError`+- Missing optional dependencies (tree-sitter, ML stack) → passthrough with warning logErrors are logged at WARNING level and never propagated to callers.diff --git a/wiki/compression.md b/wiki/compression.mdindex 61ad7bb38..a76a173c3 100644--- a/wiki/compression.md+++ b/wiki/compression.md@@ -8,7 +8,7 @@ Universal Compression combines several techniques:1. **ML-based Detection** - Automatically detects content type (JSON, code, logs, text) using Magika2. **Structure Preservation** - Keeps keys, signatures, and templates intact via structure masks-3. **Intelligent Compression** - Compresses content while preserving meaning with LLMLingua+3. **Intelligent Compression** - Compresses content while preserving meaning with the optional ML compressor (Kompress)4. **Reversible via CCR** - Stores originals for retrieval when LLM needs full context## Quick Start@@ -51,9 +51,9 @@ result = compressor.compress(content)│ │ │▼ ▼ ▼┌─────────────┐ ┌─────────────┐ ┌─────────────┐- │ Magika │ │ Handler │ │ LLMLingua │- │ (ML) │ │ (JSON, │ │ (optional) │- │ │ │ Code...) │ │ │+ │ Magika │ │ Handler │ │ Kompress │+ │ (ML) │ │ (JSON, │ │ (ML, opt- │+ │ │ │ Code...) │ │ in [ml]) │└─────────────┘ └─────────────┘ └─────────────┘```@@ -82,7 +82,9 @@ config = UniversalCompressorConfig(use_magika=True, # Use ML-based detection (requires magika)# Compression- use_llmlingua=True, # Use LLMLingua for compression+ # (Note: the legacy `use_llmlingua` flag was retired with the+ # LLMLingua-2 integration. The optional ML compressor is now Kompress,+ # installed via `headroom-ai[ml]` and configured separately.)compression_ratio_target=0.3, # Keep 30% of content (70% reduction)min_content_length=100, # Skip content shorter than thisdiff --git a/wiki/configuration.md b/wiki/configuration.mdindex 5e0787383..d5808f9d3 100644--- a/wiki/configuration.md+++ b/wiki/configuration.md@@ -59,9 +59,9 @@ headroom proxy --no-ccr-responses# Disable proactive expansionheadroom proxy --no-ccr-expansion-# Enable LLMLingua ML compression-headroom proxy --llmlingua-headroom proxy --llmlingua --llmlingua-device cuda --llmlingua-rate 0.4+# (The earlier --llmlingua flag was retired in 0.9.x and replaced by+# Kompress (ModernBERT). See `wiki/transforms.md` for the current+# opt-in path via the `[ml]` extra.)```### All Optionsdiff --git a/wiki/llmlingua.md b/wiki/llmlingua.mddeleted file mode 100644index be9cee960..000000000--- a/wiki/llmlingua.md+++ /dev/null@@ -1,188 +0,0 @@-# LLMLingua-2 Integration--For maximum compression, Headroom integrates with **LLMLingua-2**, Microsoft's BERT-based token classifier trained via GPT-4 distillation. It achieves **up to 20x compression** while preserving semantic meaning.--## When to Use LLMLingua-2--| Approach | Best For | Compression | Speed |-|----------|----------|-------------|-------|-| **SmartCrusher** | JSON tool outputs | 70-90% | ~1ms |-| **Text Utilities** | Search/logs | 50-90% | ~1ms |-| **LLMLingua-2** | Any text, max compression | 80-95% | ~50-200ms |--LLMLingua-2 is ideal when you need maximum compression and can tolerate slightly higher latency (e.g., compressing large tool outputs before storage, offline processing).--## Installation--```bash-# Adds ~2GB of model weights-pip install "headroom-ai[llmlingua]"-```--## Basic Usage--```python-from headroom.transforms import LLMLinguaCompressor--# Create compressor (model loaded lazily on first use)-compressor = LLMLinguaCompressor()--# Compress any text-long_output = "The function processUserData takes a user object and validates..."-result = compressor.compress(long_output)--print(f"Before: {result.original_tokens} tokens")-print(f"After: {result.compressed_tokens} tokens")-print(f"Saved: {result.savings_percentage:.1f}%")-print(result.compressed)-```--## Content-Aware Compression--LLMLingua-2 automatically adjusts compression based on content type:--```python-from headroom.transforms import LLMLinguaCompressor, LLMLinguaConfig--# Conservative for code (keep 40% of tokens)-config = LLMLinguaConfig(- code_compression_rate=0.4, # More conservative- json_compression_rate=0.35, # Moderate- text_compression_rate=0.25, # Aggressive-)--compressor = LLMLinguaCompressor(config)--# Auto-detects content type-code_result = compressor.compress("def calculate(x): return x * 2")-text_result = compressor.compress("This is a verbose explanation...")-```--## Memory Management--The model uses ~1GB RAM. Unload it when done:--```python-from headroom.transforms import (- LLMLinguaCompressor,- unload_llmlingua_model,- is_llmlingua_model_loaded,-)--compressor = LLMLinguaCompressor()-result = compressor.compress(content) # Model loaded here--# Check if loaded-print(is_llmlingua_model_loaded()) # True--# Free memory when done-unload_llmlingua_model() # Frees ~1GB-print(is_llmlingua_model_loaded()) # False--# Next compression will reload automatically-```--## Device Configuration--```python-from headroom.transforms import LLMLinguaConfig, LLMLinguaCompressor--# Force CPU (slower but works everywhere)-config = LLMLinguaConfig(device="cpu")--# Force GPU (faster but needs CUDA)-config = LLMLinguaConfig(device="cuda")--# Auto-detect (default): uses CUDA > MPS > CPU-config = LLMLinguaConfig(device="auto")--compressor = LLMLinguaCompressor(config)-```--## Use in Pipeline--```python-from headroom.transforms import TransformPipeline, LLMLinguaCompressor, SmartCrusher--# Combine with other transforms-pipeline = TransformPipeline([- SmartCrusher(), # First: compress JSON- LLMLinguaCompressor(), # Then: ML compression on remaining text-])--result = pipeline.apply(messages, tokenizer)-```--## Proxy Integration--Enable LLMLingua in the proxy server for automatic ML compression:--```bash-# Enable LLMLingua in proxy (requires: pip install headroom-ai[llmlingua,proxy])-headroom proxy --llmlingua--# With custom settings-headroom proxy --llmlingua --llmlingua-device cuda --llmlingua-rate 0.4--# The proxy shows LLMLingua status at startup:-# LLMLingua: ENABLED (device=cuda, rate=0.4)-#-# If llmlingua is installed but not enabled, you'll see a helpful hint:-# LLMLingua: available (enable with --llmlingua for ML compression)-```--## Configuration Reference--| Option | Default | Description |-|--------|---------|-------------|-| `device` | `"auto"` | Device to run model on: auto, cpu, cuda, mps |-| `code_compression_rate` | `0.4` | Keep 40% of tokens for code |-| `json_compression_rate` | `0.35` | Keep 35% of tokens for JSON |-| `text_compression_rate` | `0.25` | Keep 25% of tokens for text |-| `force_tokens` | `[]` | Tokens to always preserve |-| `drop_consecutive` | `True` | Drop consecutive whitespace |--## Performance Characteristics--| Metric | Value |-|--------|-------|-| Model size | ~500MB |-| Memory usage | ~1GB RAM |-| Cold start | 10-30s (first load) |-| Inference | 50-200ms per request |-| Compression | 80-95% |--## Why Opt-In?--LLMLingua adds significant dependencies and overhead:--| Aspect | Default Proxy | With LLMLingua |-|--------|--------------|----------------|-| Dependencies | ~50MB | ~2GB |-| Cold start | <1s | 10-30s |-| Per-request | ~1-5ms | ~50-200ms |-| Compression | 70-90% | 80-95% |--The default proxy is lightweight and fast. Enable LLMLingua when you need maximum compression and can accept the tradeoffs.--## Troubleshooting--### "Model not found"--```bash-# Ensure llmlingua extra is installed-pip install "headroom-ai[llmlingua]"-```--### "CUDA out of memory"--```python-# Force CPU mode-config = LLMLinguaConfig(device="cpu")-```--### "Slow compression"--- Use GPU if available: `device="cuda"`-- Batch multiple compressions-- Consider using SmartCrusher for JSON (faster, similar results)diff --git a/wiki/macos-deployment.md b/wiki/macos-deployment.mdindex 3c9a5cecb..5e7e34350 100644--- a/wiki/macos-deployment.md+++ b/wiki/macos-deployment.md@@ -202,21 +202,14 @@ Configure additional options in the plist `EnvironmentVariables` section:<key>ANTHROPIC_API_KEY</key><string>sk-ant-...</string>- <!-- Optional: Enable LLMLingua compression -->- <key>HEADROOM_COMPRESSION_PROVIDER</key>- <string>llmlingua</string>-- <!-- Optional: LLMLingua device (auto, cuda, cpu, mps) -->- <key>HEADROOM_LLMLINGUA_DEVICE</key>- <string>mps</string></dict>```-**Note:** LLMLingua requires additional installation:--```bash-pip install headroom-ai[llmlingua]-```+**Note:** The earlier LLMLingua-2 launch-agent variables+(`HEADROOM_COMPRESSION_PROVIDER=llmlingua`, `HEADROOM_LLMLINGUA_DEVICE`,+the `headroom-ai[llmlingua]` extra) were retired with the+`--llmlingua` flag. For ML compression today, install the `[ml]`+extra and follow `wiki/transforms.md`.### Crash Recovery@@ -683,4 +676,4 @@ A: The LaunchAgent setup is Anthropic-specific. For other providers, see [proxy.**Q: Does this work with Apple Silicon (M1/M2/M3)?**-A: Yes, fully compatible. For LLMLingua compression, use `--llmlingua-device mps` for Apple Silicon acceleration.+A: Yes, fully compatible. ML compression (Kompress, opt-in via `headroom-ai[ml]`) auto-detects MPS on Apple Silicon.diff --git a/wiki/metrics.md b/wiki/metrics.mdindex 5e9142fd6..7408558c1 100644--- a/wiki/metrics.md+++ b/wiki/metrics.md@@ -303,8 +303,7 @@ curl http://localhost:8787/health{"status": "healthy","version": "0.1.0",- "uptime_seconds": 3600,- "llmlingua_enabled": false+ "uptime_seconds": 3600}```diff --git a/wiki/proxy.md b/wiki/proxy.mdindex c52e02ff9..ae95a5d78 100644--- a/wiki/proxy.md+++ b/wiki/proxy.md@@ -117,26 +117,12 @@ headroom proxy --no-intelligent-contextheadroom proxy --no-intelligent-scoring```-### LLMLingua Options (ML Compression)+### ML Compression — RETIRED `--llmlingua` flag-| Option | Default | Description |-|--------|---------|-------------|-| `--llmlingua` | `false` | Enable LLMLingua-2 ML-based compression |-| `--llmlingua-device` | `auto` | Device for model: `auto`, `cuda`, `cpu`, `mps` |-| `--llmlingua-rate` | `0.3` | Target compression rate (0.3 = keep 30% of tokens) |--**Note:** LLMLingua requires additional dependencies: `pip install headroom-ai[llmlingua]`--```bash-# Enable LLMLingua with GPU acceleration-headroom proxy --llmlingua --llmlingua-device cuda--# More aggressive compression (keep only 20%)-headroom proxy --llmlingua --llmlingua-rate 0.2--# Conservative compression for code (keep 50%)-headroom proxy --llmlingua --llmlingua-rate 0.5-```+The `--llmlingua` / `--llmlingua-device` / `--llmlingua-rate` flags and+the `headroom-ai[llmlingua]` extra were retired and replaced by Kompress+(ModernBERT). For the current opt-in path, install `headroom-ai[ml]`+and see [transforms.md](transforms.md) and [ARCHITECTURE.md](ARCHITECTURE.md).## API Endpoints@@ -341,41 +327,14 @@ client = OpenAI(## Features-### LLMLingua ML Compression (Opt-In)--When enabled, the proxy uses Microsoft's LLMLingua-2 model for ML-based token compression:--```bash-headroom proxy --llmlingua-```--**How it works:**-- LLMLinguaCompressor is added to the transform pipeline (before RollingWindow)-- Automatically detects content type (JSON, code, text) and adjusts compression-- Stores original content in CCR for retrieval if needed--**Startup feedback:**--```-# When enabled and available:-LLMLingua: ENABLED (device=cuda, rate=0.3)--# When installed but not enabled (helpful hint):-LLMLingua: available (enable with --llmlingua for ML compression)--# When enabled but not installed:-WARNING: LLMLingua requested but not installed. Install with: pip install headroom-ai[llmlingua]-```--**Why opt-in?**-| Concern | Default Proxy | With LLMLingua |-|---------|---------------|----------------|-| Dependencies | ~50MB | +2GB (torch, transformers) |-| Cold start | <1s | 10-30s (model load) |-| Memory | ~100MB | +1GB (model in RAM) |-| Overhead | <5ms | 50-200ms per request |+### ML Compression (Opt-In, Kompress)-Enable LLMLingua when maximum compression justifies the resource cost.+> The earlier LLMLingua-2 integration documented in this section+> (`--llmlingua`, `--llmlingua-device`, `--llmlingua-rate`,+> `headroom-ai[llmlingua]`, `LLMLinguaCompressor`) was retired and+> replaced by **Kompress** (ModernBERT). Install with `pip install+> 'headroom-ai[ml]'`. See [transforms.md](transforms.md) and+> [ARCHITECTURE.md](ARCHITECTURE.md) for current configuration.### Semantic Cachingdiff --git a/wiki/transforms.md b/wiki/transforms.mdindex 307a54354..4c9d93493 100644--- a/wiki/transforms.md+++ b/wiki/transforms.md@@ -325,73 +325,16 @@ intelligent_config = IntelligentContextConfig(----## LLMLinguaCompressor (Optional)+## LLMLinguaCompressor — RETIRED-ML-based compression using Microsoft's LLMLingua-2 model.--### When to Use--| Transform | Best For | Speed | Compression |-|-----------|----------|-------|-------------|-| SmartCrusher | JSON arrays | ~1ms | 70-90% |-| Text Utilities | Search/logs | ~1ms | 50-90% |-| **LLMLinguaCompressor** | Any text, max compression | 50-200ms | 80-95% |--### Installation--```bash-pip install "headroom-ai[llmlingua]" # Adds ~2GB-```--### Configuration--```python-from headroom.transforms import LLMLinguaCompressor, LLMLinguaConfig--config = LLMLinguaConfig(- device="auto", # auto, cuda, cpu, mps- target_compression_rate=0.3, # Keep 30% of tokens- min_tokens_for_compression=100, # Skip small content- code_compression_rate=0.4, # Conservative for code- json_compression_rate=0.35, # Moderate for JSON- text_compression_rate=0.25, # Aggressive for text- enable_ccr=True, # Store original for retrieval-)--compressor = LLMLinguaCompressor(config)-```--### Content-Aware Rates--LLMLinguaCompressor auto-detects content type:--| Content Type | Default Rate | Behavior |-|--------------|--------------|----------|-| Code | 0.4 | Conservative - preserves syntax |-| JSON | 0.35 | Moderate - keeps structure |-| Text | 0.3 | Aggressive - maximum compression |--### Memory Management--```python-from headroom.transforms import (- is_llmlingua_model_loaded,- unload_llmlingua_model,-)--# Check if model is loaded-print(is_llmlingua_model_loaded()) # True/False--# Free ~1GB RAM when done-unload_llmlingua_model()-```--### Proxy Integration--```bash-# Enable in proxy-headroom proxy --llmlingua --llmlingua-device cuda --llmlingua-rate 0.3-```+The earlier LLMLingua-2 integration (`LLMLinguaCompressor`,+`LLMLinguaConfig`, `is_llmlingua_model_loaded`, `unload_llmlingua_model`,+the `headroom-ai[llmlingua]` extra, and the `--llmlingua` proxy flag)+was retired in 0.9.x and replaced by **Kompress** (ModernBERT).+`pip install 'headroom-ai[llmlingua]'` no longer resolves; use the+`[ml]` extra instead. The Kompress transform shipped with the proxy+runs as Transform 4 in the live-zone pipeline (see+[ARCHITECTURE.md](ARCHITECTURE.md)).---@@ -405,14 +348,14 @@ AST-based compression for source code using tree-sitter.|-----------|----------|-------|-------------|| SmartCrusher | JSON arrays | ~1ms | 70-90% || **CodeAwareCompressor** | Source code | ~10-50ms | 40-70% |-| LLMLinguaCompressor | Any text | 50-200ms | 80-95% |+| Kompress (ML) | Any text | 50-200ms | 80-95% |### Key Benefits- **Syntax validity guaranteed** — Output always parses correctly- **Preserves critical structure** — Imports, signatures, types, error handlers- **Multi-language support** — Python, JavaScript, TypeScript, Go, Rust, Java, C, C++-- **Lightweight** — ~50MB vs ~1GB for LLMLingua+- **Lightweight** — ~50MB vs ~1GB for the ML compressor### Installation@@ -436,7 +379,6 @@ config = CodeCompressorConfig(max_body_lines=5, # Lines to keep per function bodymin_tokens_for_compression=100, # Skip small contentlanguage_hint=None, # Auto-detect if None- fallback_to_llmlingua=True, # Use LLMLingua for unknown langs)compressor = CodeAwareCompressor(config)@@ -553,9 +495,10 @@ print(result.routing_log) # List of routing decisions| SEARCH | Grep/find output | SearchCompressor || LOG | Log files | LogCompressor || TEXT | Plain text | TextCompressor |-| LLMLINGUA | Any (max compression) | LLMLinguaCompressor || PASSTHROUGH | Small content | None |+(The earlier `LLMLINGUA` strategy was retired with the LLMLingua integration; ML compression is now provided by Kompress.)+### Content DetectionThe router automatically detects content types by analyzing the content itself:@@ -572,7 +515,7 @@ No manual hints required - the router inspects content directly.ContentRouter records all compressions to TOIN (Tool Output Intelligence Network) for cross-user learning:-- **All strategies tracked**: Code, search, logs, text, and LLMLingua compressions are recorded+- **All strategies tracked**: Code, search, logs, text, and ML compressions are recorded- **Retrieval feedback**: When users retrieve original content via CCR, TOIN learns which compressions need expansion- **Pattern learning**: TOIN builds signatures for each content type to improve future compressions@@ -597,21 +540,9 @@ result = pipeline.transform(messages)print(f"Saved {result.tokens_saved} tokens")```-### With LLMLingua (Optional)--```python-from headroom.transforms import (- TransformPipeline, SmartCrusher, CacheAligner,- RollingWindow, LLMLinguaCompressor-)+### With ML compression (Optional, Kompress)-pipeline = TransformPipeline([- CacheAligner(), # 1. Stabilize prefix- SmartCrusher(), # 2. Compress JSON arrays- LLMLinguaCompressor(), # 3. ML compression on remaining text- RollingWindow(), # 4. Final size constraint (always last)-])-```+The earlier hand-assembled `TransformPipeline([..., LLMLinguaCompressor(), ...])` recipe is no longer supported. ML compression now ships as part of the live-zone pipeline when the `[ml]` extra is installed; see [ARCHITECTURE.md](ARCHITECTURE.md) for the current placement.### Recommended Order@@ -619,13 +550,13 @@ pipeline = TransformPipeline([|-------|-----------|---------|| 1 | CacheAligner | Stabilize prefix for caching || 2 | SmartCrusher | Compress JSON tool outputs |-| 3 | LLMLinguaCompressor | ML compression (optional) |+| 3 | Kompress (ML) | ML compression on remaining text (optional, `[ml]` extra) || 4 | RollingWindow | Enforce token limits (always last) |**Why this order?**- CacheAligner first to maximize prefix stability- SmartCrusher handles JSON arrays efficiently-- LLMLingua compresses remaining long text+- Kompress compresses remaining long text- RollingWindow truncates only if still over limit---