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: never grep-fold timestamped logs, size-weight savings, warn on no-op model limits (#3419)
Morteza Rastgoo73a6edbe83af
diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdxindex ce44b245a..305f19ed1 100644--- a/docs/content/docs/configuration.mdx+++ b/docs/content/docs/configuration.mdx@@ -334,6 +334,7 @@ headroom proxy --learn --min-evidence 3| `HEADROOM_TELEMETRY` | Set to `on` for **local-only** usage stats (powers your own `/stats` and dashboard; nothing is sent externally) | `off` || `HEADROOM_STATELESS` | Set to `true` to disable filesystem writes | `false` || `HEADROOM_MODEL_LIMITS` | Custom model config (JSON string or file path) | -- |+| `HEADROOM_LOSSLESS_COMPACTION` | Set to `0` to disable the byte-reversible lossless folds (grep heading, log run-collapse, diff/config folds) while leaving the rest of the compression pipeline active. Read per request, so the proxy's `/admin/runtime-env` hot-sync applies without a restart. | `1` || `HEADROOM_BASE_URL` | Base URL of the Headroom proxy (TypeScript SDK) | `http://localhost:8787` || `HEADROOM_API_KEY` | Optional API key for authenticated Headroom endpoints (TypeScript SDK) | -- || `HEADROOM_CONFIG_DIR` | Canonical config (read-mostly) root. Derives `models.json` and per-plugin config paths when set. | `~/.headroom/config` |diff --git a/headroom/providers/anthropic.py b/headroom/providers/anthropic.pyindex fb7278ab4..badce7a24 100644--- a/headroom/providers/anthropic.py+++ b/headroom/providers/anthropic.py@@ -287,6 +287,31 @@ def _load_custom_model_config() -> dict[str, Any]:config["context_limits"].update(anthropic_config["context_limits"])if "pricing" in anthropic_config:config["pricing"].update(anthropic_config["pricing"])+ # Another provider's namespaced section ({"openai": {"context_limits":+ # ...}}) is a correctly shaped config that this loader is simply not+ # meant to consume, so it must not trip the no-effect warning below.+ other_provider_section = "anthropic" not in loaded and any(+ isinstance(section, dict)+ and any(key in section for key in ("context_limits", "pricing", "encodings"))+ for section in loaded.values()+ )+ if (+ "context_limits" not in anthropic_config+ and "pricing" not in anthropic_config+ and not other_provider_section+ ):+ # Valid JSON object, but none of the keys we consume. Previously+ # this was a SILENT no-op: the unknown-model warning tells the+ # operator to "set HEADROOM_MODEL_LIMITS", they set the obvious+ # flat shape {"my-model": 262144}, nothing happens, and there is+ # no diagnostic anywhere. Name the expected shape instead.+ logger.warning(+ "HEADROOM_MODEL_LIMITS parsed but contained no 'context_limits' "+ "or 'pricing' key, so it had NO EFFECT. Expected shape: "+ '{"context_limits": {"<model>": <int>}, "pricing": {...}} '+ '(optionally nested under an "anthropic" key). '+ f"Got top-level keys: {sorted(map(str, anthropic_config))[:10]}"+ )logger.debug(f"Loaded custom model config from HEADROOM_MODEL_LIMITS: {loaded}")except (ValueError, OSError) as e:diff --git a/headroom/proxy/cost.py b/headroom/proxy/cost.pyindex fc5d41545..bd11f1465 100644--- a/headroom/proxy/cost.py+++ b/headroom/proxy/cost.py@@ -641,10 +641,16 @@ def build_session_summary(best_compression = 0.0best_detail = ""if compressed_requests:- avg_compression = round(- sum(r["savings_pct"] for r in compressed_requests) / len(compressed_requests),- 1,- )+ # Size-WEIGHTED, not a mean of per-request percentages. An unweighted+ # mean lets one tiny, highly-compressible request (e.g. a repeated log+ # line that folds 6,070 -> 83 tokens, 98.6%) dominate the headline while+ # the large real requests it is averaged with barely moved, so the card+ # can read "18.6% saved" on traffic whose forwarded bytes fell ~3%.+ # Weighting by original size makes the number mean what an operator+ # reads it as: the share of total tokens actually removed.+ _orig_total = sum(r["original"] for r in compressed_requests)+ _saved_total = sum(r["tokens_saved"] for r in compressed_requests)+ avg_compression = round(100.0 * _saved_total / _orig_total, 1) if _orig_total else 0.0best = max(compressed_requests, key=lambda r: r["savings_pct"])best_compression = best["savings_pct"]best_detail = f"{best['original']:,} → {best['optimized']:,} tokens"diff --git a/headroom/transforms/lossless_compaction.py b/headroom/transforms/lossless_compaction.pyindex 76c167e15..035615d83 100644--- a/headroom/transforms/lossless_compaction.py+++ b/headroom/transforms/lossless_compaction.py@@ -14,6 +14,7 @@ unchanged. Nothing here raises.from __future__ import annotations+import osimport re__all__ = [@@ -59,6 +60,21 @@ _GREP_ROW_RE = re.compile(r"^(?P<path>[^\n:]+):(?P<line>\d+):(?P<content>.*)$")# heading-form data row (``line:content``) produced by search_heading._HEADING_ROW_RE = re.compile(r"^(?P<line>\d+):(?P<content>.*)$")+# A timestamped log line is NOT a grep row, but it has the same colon-delimited+# shape: ``2026-09-02 14:30:00 [FATAL] ...`` splits as path=``2026-09-02 14``,+# line=``30``, content=``00 [FATAL] ...``. Folding it hoists the date+hour into+# a heading and strips it from every row, so the model sees ``30:00 [FATAL]``+# and has to reconstruct the clock itself. The fold round-trips exactly, so the+# inverse-check in compact_lossless cannot catch it -- it must be excluded here.+_TIMESTAMP_ROW_RE = re.compile(+ r"^\s*\[?(?:"+ r"\d{4}-\d{2}-\d{2}[ T]\d{1,2}:\d{2}" # 2026-09-02 14:30 / ISO 8601 'T'+ r"|\d{2}/\d{2}/\d{2,4}[ T]\d{1,2}:\d{2}" # 09/02/2026 14:30+ r"|[A-Z][a-z]{2}\s+\d{1,2}\s+\d{1,2}:\d{2}" # syslog: Aug 16 11:02+ r"|\d{1,2}:\d{2}:\d{2}(?:[.,]\d+)?(?:\s|\]|$)" # bare 15:03:53 / [15:03:53]+ r")"+)+# unified-diff ``index <sha>..<sha> <mode>`` line. The diff still applies# without it (git only uses it for rename/blob bookkeeping)._DIFF_INDEX_RE = re.compile(r"^index [0-9a-fA-F]+\.\.[0-9a-fA-F]+( [0-7]+)?$")@@ -234,7 +250,7 @@ def search_heading(text: str) -> str:out: list[str] = []current_path: str | None = Nonefor line in lines:- m = _GREP_ROW_RE.match(line)+ m = None if _TIMESTAMP_ROW_RE.match(line) else _GREP_ROW_RE.match(line)if m:path = m.group("path")if path != current_path:@@ -307,7 +323,7 @@ def search_dir_heading(text: str) -> str:out: list[str] = []current_dir: str | None = Nonefor line in lines:- m = _GREP_ROW_RE.match(line)+ m = None if _TIMESTAMP_ROW_RE.match(line) else _GREP_ROW_RE.match(line)if m and "/" in m.group("path"):path = m.group("path")cut = path.rindex("/") + 1@@ -435,6 +451,19 @@ def _smaller(candidate: str, original: str) -> bool:return len(candidate) < len(original)+#: Env kill-switch for every fold in this module. Read per call (not cached at+#: import) so the proxy's live ``POST /admin/runtime-env`` hot-sync applies+#: without a restart, matching how the output-shaper switches behave.+_LOSSLESS_COMPACTION_ENV = "HEADROOM_LOSSLESS_COMPACTION"+++def _lossless_compaction_enabled() -> bool:+ raw = os.environ.get(_LOSSLESS_COMPACTION_ENV)+ if raw is None:+ return True+ return raw.strip().lower() not in ("0", "false", "no", "off")++def compact_lossless(content: str, kind: str) -> str:"""Dispatch format-native lossless compaction by ``kind``.@@ -443,8 +472,15 @@ def compact_lossless(content: str, kind: str) -> str:non-semantic bits, e.g. ANSI color for logs); if verification fails or theresult is not smaller, the original content is returned unchanged. Neverraises; unknown kinds pass through.++ Set ``HEADROOM_LOSSLESS_COMPACTION=0`` to disable every fold here while+ leaving the rest of the pipeline (Kompress, SmartCrusher, CCR) active. The+ folds are byte-reversible, but the model only ever sees the folded side and+ must reconstruct the original shape itself, which costs output tokens on+ reasoning models. Operators need to be able to turn that off without+ resorting to ``--no-optimize`` (which disables all compression)."""- if not content:+ if not content or not _lossless_compaction_enabled():return contenttry:if kind == "log":diff --git a/tests/test_lossless_timestamp_guard.py b/tests/test_lossless_timestamp_guard.pynew file mode 100644index 000000000..9136a06d2--- /dev/null+++ b/tests/test_lossless_timestamp_guard.py@@ -0,0 +1,82 @@+"""Timestamped log lines must never be folded as grep ``path:line:content`` rows.++``2026-09-02 14:30:00 [FATAL] ...`` splits under _GREP_ROW_RE as+path=``2026-09-02 14`` / line=``30`` / content=``00 [FATAL] ...``. Folding it+hoists the date+hour into a heading and strips it from every row, so the model+receives ``30:00 [FATAL] ...`` and has to rebuild the clock itself. The fold is+byte-reversible, so compact_lossless's inverse-check cannot catch it.+"""++import os++import pytest++from headroom.transforms.lossless_compaction import compact_lossless+++def _multi_hour_log() -> str:+ lines = [+ f"2026-09-02 {h:02d}:{m:02d}:10 [INFO] worker heartbeat ok id={m}"+ for h in (14, 15, 16)+ for m in range(60)+ ]+ lines.insert(90, "2026-09-02 14:30:00 [FATAL] node evicted disk full")+ return "\n".join(lines)+++ "sample",+ [+ _multi_hour_log(),+ "\n".join(+ f"Aug 16 11:{m:02d}:22 web-01 systemd[3397]: Starting example-worker.service {m}"+ for m in range(60)+ ),+ "\n".join(f"[15:{m:02d}:53] tool: Bash(cmd {m})" for m in range(60)),+ "\n".join(f"2026-09-02T14:{m:02d}:10 [WARN] latency high {m}" for m in range(60)),+ ],+ ids=["iso-datetime", "syslog", "bracketed-time", "iso-T"],+)+def test_timestamped_logs_are_never_folded(sample: str) -> None:+ assert compact_lossless(sample, "search") == sample+++def test_fatal_line_keeps_its_full_timestamp() -> None:+ out = compact_lossless(_multi_hour_log(), "search")+ fatal = [line for line in out.split("\n") if "FATAL" in line]+ assert fatal == ["2026-09-02 14:30:00 [FATAL] node evicted disk full"]+++def test_genuine_grep_output_still_folds() -> None:+ """The guard must not cost us the real feature."""+ grep = "\n".join(+ f"src/lumina_tray/panel.py:{i}: def handler_{i}(self): pass" for i in range(40)+ )+ out = compact_lossless(grep, "search")+ assert out != grep+ assert len(out) < len(grep)+ assert out.split("\n")[0] == "src/lumina_tray/panel.py"+++def test_env_kill_switch_disables_all_folds(monkeypatch: pytest.MonkeyPatch) -> None:+ grep = "\n".join(+ f"src/lumina_tray/panel.py:{i}: def handler_{i}(self): pass" for i in range(40)+ )+ monkeypatch.setenv("HEADROOM_LOSSLESS_COMPACTION", "0")+ assert compact_lossless(grep, "search") == grep+ monkeypatch.setenv("HEADROOM_LOSSLESS_COMPACTION", "1")+ assert compact_lossless(grep, "search") != grep+++def test_kill_switch_is_read_live_not_cached_at_import() -> None:+ """The proxy hot-syncs runtime env; a cached flag would ignore it."""+ grep = "\n".join(f"src/a.py:{i}: x = {i}" for i in range(40))+ prior = os.environ.pop("HEADROOM_LOSSLESS_COMPACTION", None)+ try:+ assert compact_lossless(grep, "search") != grep+ os.environ["HEADROOM_LOSSLESS_COMPACTION"] = "off"+ assert compact_lossless(grep, "search") == grep+ finally:+ os.environ.pop("HEADROOM_LOSSLESS_COMPACTION", None)+ if prior is not None:+ os.environ["HEADROOM_LOSSLESS_COMPACTION"] = priordiff --git a/tests/test_provider_model_fallback.py b/tests/test_provider_model_fallback.pyindex 9a83ec0ac..1edd18299 100644--- a/tests/test_provider_model_fallback.py+++ b/tests/test_provider_model_fallback.py@@ -1,6 +1,7 @@"""Tests for provider model fallback and configuration."""import json+import loggingimport osimport tempfilefrom pathlib import Path@@ -245,6 +246,51 @@ class TestAnthropicConfigLoading:loaded = anthropic_load_config()assert loaded == {"context_limits": {}, "pricing": {}}+ def test_flat_shape_env_var_warns_that_it_had_no_effect(self, caplog):+ """A JSON *object* using the intuitive-but-wrong flat shape+ ``{"my-model": 262144}`` is silently ignored by the loader.++ The unknown-model warning tells operators to "set HEADROOM_MODEL_LIMITS",+ so the flat shape is the natural first guess. Without a diagnostic the+ operator sees the conservative default silently persist and has no way+ to tell the config was never applied. Assert we now say so explicitly.+ """+ with patch.dict(os.environ, {"HEADROOM_MODEL_LIMITS": '{"qwen3.8": 262144}'}):+ with caplog.at_level(logging.WARNING, logger="headroom.providers.anthropic"):+ loaded = anthropic_load_config()+ assert loaded == {"context_limits": {}, "pricing": {}}+ assert "NO EFFECT" in caplog.text+ assert "context_limits" in caplog.text++ def test_correct_shape_env_var_does_not_warn(self, caplog):+ """The documented nested shape must apply cleanly and stay silent."""+ cfg = '{"context_limits": {"qwen3.8": 262144}}'+ with patch.dict(os.environ, {"HEADROOM_MODEL_LIMITS": cfg}):+ with caplog.at_level(logging.WARNING, logger="headroom.providers.anthropic"):+ loaded = anthropic_load_config()+ assert loaded["context_limits"]["qwen3.8"] == 262144+ assert "NO EFFECT" not in caplog.text++ def test_other_provider_namespaced_env_var_does_not_warn(self, caplog):+ """``{"openai": {"context_limits": ...}}`` is the documented shape for the+ OpenAI loader. The Anthropic loader consumes nothing from it, which is+ correct, so it must not claim the config had no effect."""+ cfg = '{"openai": {"context_limits": {"gpt-x": 400000}}}'+ with patch.dict(os.environ, {"HEADROOM_MODEL_LIMITS": cfg}):+ with caplog.at_level(logging.WARNING, logger="headroom.providers.anthropic"):+ loaded = anthropic_load_config()+ assert loaded == {"context_limits": {}, "pricing": {}}+ assert "NO EFFECT" not in caplog.text++ def test_anthropic_section_without_known_keys_still_warns(self, caplog):+ """An explicit ``anthropic`` section that carries none of the consumed+ keys is the same silent no-op as the flat shape, so it warns."""+ cfg = '{"anthropic": {"qwen3.8": 262144}}'+ with patch.dict(os.environ, {"HEADROOM_MODEL_LIMITS": cfg}):+ with caplog.at_level(logging.WARNING, logger="headroom.providers.anthropic"):+ anthropic_load_config()+ assert "NO EFFECT" in caplog.text+def test_non_object_config_file_falls_back_to_defaults(self):"""A models.json whose top level is not an object must not crash."""with tempfile.TemporaryDirectory() as tmpdir: