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
feat(router): route embedded & nested JSON through the compressor dispatch (#2623)
Tejas Chopra57bf720d5c60
diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex f317bfbd3..75ee193c4 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -2807,6 +2807,7 @@ class ContentRouter(Transform):language: str | None = None,question: str | None = None,bias: float = 1.0,+ _allow_embedded: bool = True,) -> tuple[str, int, list[str]]:"""Apply a compression strategy to content.@@ -2827,6 +2828,37 @@ class ContentRouter(Transform):log]``). Log readers use this to see *how* we got to thefinal compressor without parsing decision_reason strings."""+ # ── STRUCTURAL (embedded) JSON routing ───────────────────────────────+ # Before anything else: if this block is not a single JSON value but+ # CONTAINS balanced JSON span(s), route each span through this very+ # dispatch and splice the result back (surrounding bytes kept exact).+ # This is how nested/embedded JSON reaches the JSON compressors at all —+ # today's linear splitter never sees it. Each span goes through the+ # UNCHANGED path, so SmartCrusher/CodeCompressor register their+ # `<<ccr:…>>` markers exactly as for a whole-block JSON (CCR is hash-+ # keyed → location-agnostic). `_allow_embedded=False` on the recursive+ # call is a one-shot re-entrancy guard (NOT a depth cap). Deterministic ++ # benefit-gated (no size/min thresholds) → prefix-cache- and CCR-store-+ # stable, and a strict no-op when the block has no embedded JSON.+ if _allow_embedded:+ from headroom.transforms.recursive_json import route_embedded_json++ def _dispatch_span(span: str) -> str | None:+ strat = self._strategy_from_detection_type(_detect_content(span).content_type)+ text, _t, _c = self._apply_strategy_to_content(+ span,+ strat,+ context,+ question=question,+ bias=bias,+ _allow_embedded=False,+ )+ return text if text != span else None++ routed = route_embedded_json(content, _dispatch_span, tok=_estimate_tokens)+ if routed is not None:+ return routed, _estimate_tokens(routed), ["embedded_json"]+# Track original tokens for TOIN recordingoriginal_tokens = _estimate_tokens(content)compressed: str | None = Nonediff --git a/headroom/transforms/recursive_json.py b/headroom/transforms/recursive_json.pynew file mode 100644index 000000000..e6d7b1665--- /dev/null+++ b/headroom/transforms/recursive_json.py@@ -0,0 +1,162 @@+"""Structural (recursive) JSON routing for the ContentRouter.++Today the router is *linear*: it splits a block into textual sections and picks+one strategy per section. It never looks *inside* a structure, so JSON embedded+in a larger payload (a ``gh api`` dump, an MCP result, a ``curl | jq`` tail) is+invisible to the JSON compressors — even though, in practice, that embedded shape+is the overwhelming majority of JSON the agent ever sees.++This module adds the missing structural step: find balanced JSON spans at any+offset in a block and route each one through the router's *existing* dispatch,+splicing the result back in place with the surrounding bytes kept exact.++Why this is CCR-safe by construction+-------------------------------------+Each span is handed to the router's own ``_apply_strategy_to_content`` — the same+code path a whole-block JSON already takes — so SmartCrusher / CodeCompressor+register their ``<<ccr:HASH…>>`` retrieval markers exactly as they do today. CCR+is hash-keyed and therefore location-agnostic: a marker resolves whether it sits+at the top of a block or nested inside one. This module never touches the CCR+store; it only relocates where the dispatch is invoked.++Safety invariants (no thresholds — outcome-gated only):+ * A span that already contains a ``<<ccr:`` marker is passed through untouched+ (never re-compressed / re-hashed).+ * Traversal is deterministic (left-to-right, no clocks/rng) so prompt bytes and+ CCR hashes are stable across turns → prefix cache and store both stay stable.+ * A rewrite is kept only if it is strictly smaller in tokens; otherwise the+ original bytes are returned unchanged. No min-size, no max-depth.+"""++from __future__ import annotations++import json+from collections.abc import Callable++_OPEN = "[{"+_CLOSE = "]}"+_PAIR = {"}": "{", "]": "["}++#: A dispatch callback: given a JSON span's text, return the compressed text+#: (which may carry CCR markers) or ``None`` to leave it unchanged.+Dispatch = Callable[[str], "str | None"]+++def _match_span(text: str, start: int) -> int | None:+ """Index just past the balanced JSON container opening at ``start`` (honoring+ string/escape rules), or ``None`` if it never balances."""+ stack: list[str] = []+ in_str = esc = False+ for j in range(start, len(text)):+ ch = text[j]+ if in_str:+ if esc:+ esc = False+ elif ch == "\\":+ esc = True+ elif ch == '"':+ in_str = False+ continue+ if ch == '"':+ in_str = True+ elif ch in _OPEN:+ stack.append(ch)+ elif ch in _CLOSE:+ if not stack or stack[-1] != _PAIR[ch]:+ return None+ stack.pop()+ if not stack:+ return j + 1+ return None+++def _spans(text: str) -> list[tuple[int, int]]:+ """Deterministic list of ``(start, end)`` for top-level balanced JSON spans.+ Nested spans are not returned separately — the dispatch handles depth."""+ out: list[tuple[int, int]] = []+ i, n = 0, len(text)+ while i < n:+ if text[i] in _OPEN:+ end = _match_span(text, i)+ if end is not None:+ out.append((i, end))+ i = end+ continue+ i += 1+ return out+++def _has_routable_json(span: str) -> bool:+ """True if ``span`` parses and contains an array of objects somewhere — the+ shape the JSON compressors actually act on. Cheap structural check, no size+ threshold."""+ try:+ v = json.loads(span)+ except (ValueError, TypeError):+ return False++ found = False++ def walk(x: object) -> None:+ nonlocal found+ if found:+ return+ if isinstance(x, list):+ if len(x) >= 2 and sum(isinstance(e, dict) for e in x) >= 0.8 * len(x):+ found = True+ return+ for e in x:+ walk(e)+ elif isinstance(x, dict):+ for e in x.values():+ walk(e)++ walk(v)+ return found+++def route_embedded_json(+ content: str,+ dispatch: Dispatch,+ *,+ tok: Callable[[str], int] | None = None,+) -> str | None:+ """Route every embedded JSON span in ``content`` through ``dispatch`` and+ splice the results back in place. Returns the rewritten block, or ``None``+ when nothing safe/smaller applied.++ ``content`` that is itself a single JSON value is intentionally skipped — the+ caller already routes pure-JSON blocks; this exists for the *embedded* case.+ """+ tok = tok or (lambda s: max(1, len(s) // 4))+ spans = _spans(content)+ if not spans:+ return None+ # Whole-block JSON is the caller's job, not ours.+ if len(spans) == 1 and spans[0] == (0, len(content.strip())):+ return None++ repls: list[tuple[int, int, str]] = []+ for a, b in spans:+ chunk = content[a:b]+ if "<<ccr:" in chunk: # R1: already compressed — never re-route+ continue+ if not _has_routable_json(chunk):+ continue+ out = dispatch(chunk)+ if out is None or out == chunk:+ continue+ if tok(out) < tok(chunk): # benefit gate (outcome, not a threshold)+ repls.append((a, b, out))++ if not repls:+ return None+ parts: list[str] = []+ last = 0+ for a, b, out in repls:+ parts.append(content[last:a])+ parts.append(out)+ last = b+ parts.append(content[last:])+ new = "".join(parts)+ return new if tok(new) < tok(content) else Nonediff --git a/tests/test_recursive_json.py b/tests/test_recursive_json.pynew file mode 100644index 000000000..32e8709e6--- /dev/null+++ b/tests/test_recursive_json.py@@ -0,0 +1,67 @@+"""Unit tests for headroom.transforms.recursive_json — the structural (embedded)+JSON routing step. Uses a fake dispatch so the mechanism is tested in isolation+from the real compressors."""++from __future__ import annotations++import json++from headroom.transforms.recursive_json import route_embedded_json+++def _upper_dispatch(span: str) -> str | None:+ """Fake compressor: returns a shorter deterministic stand-in for any span."""+ try:+ v = json.loads(span)+ except ValueError:+ return None+ return f"<TABLE n={len(v)}>" if isinstance(v, list) else "<OBJ>"+++def test_embedded_json_routed_and_surroundings_exact() -> None:+ payload = json.dumps([{"id": i, "ok": True} for i in range(6)], separators=(",", ":"))+ content = f"Fetched rows from API:\n{payload}\nDone (200 OK)."+ out = route_embedded_json(content, _upper_dispatch)+ assert out is not None+ assert out.startswith("Fetched rows from API:\n")+ assert out.endswith("\nDone (200 OK).")+ assert "<TABLE n=6>" in out+++def test_ccr_marker_span_passed_through() -> None:+ # A span already carrying a CCR marker must never be re-routed (R1).+ content = 'prefix [{"a":1,"b":2},{"a":3,"b":"<<ccr:deadbeef,json,900>>"}] suffix'+ out = route_embedded_json(content, _upper_dispatch)+ assert out is None # only span contains a marker → skipped → nothing to do+++def test_no_json_is_noop() -> None:+ assert route_embedded_json("just prose, nothing structured here", _upper_dispatch) is None+++def test_whole_block_json_is_callers_job() -> None:+ # A block that IS a single JSON value is skipped (routed by the caller).+ content = json.dumps([{"a": i} for i in range(5)], separators=(",", ":"))+ assert route_embedded_json(content, _upper_dispatch) is None+++def test_benefit_gate_declines_when_not_smaller() -> None:+ payload = json.dumps([{"a": i} for i in range(5)], separators=(",", ":"))+ content = f"x {payload} y"+ # Dispatch that returns something LARGER → must be declined (outcome gate).+ assert route_embedded_json(content, lambda s: s + " " * 999) is None+++def test_deterministic() -> None:+ payload = json.dumps([{"k": i} for i in range(8)], separators=(",", ":"))+ content = f"a {payload} b {payload} c"+ r1 = route_embedded_json(content, _upper_dispatch)+ r2 = route_embedded_json(content, _upper_dispatch)+ assert r1 == r2 and r1 is not None+ assert r1.count("<TABLE n=8>") == 2 # both embedded spans routed+++def test_scalar_array_not_routed() -> None:+ # array of scalars is not a "routable" JSON shape (no dict rows)+ content = "nums: [1,2,3,4,5,6,7,8] done"+ assert route_embedded_json(content, _upper_dispatch) is None