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.

feat: 3-layer context compression pipeline (L1+L2+L3) (#1405)

Gen Li3dd9660d91ab
diff --git a/headroom/evals/runners/compression_only.py b/headroom/evals/runners/compression_only.py
index 4ef71dbc0..e3ad17888 100644
--- a/headroom/evals/runners/compression_only.py
+++ b/headroom/evals/runners/compression_only.py
@@ -489,7 +489,7 @@ class CompressionOnlyRunner:
(no dangling required entry pointing at a stripped property)
- schema-level annotations ($schema, title at root level) ARE dropped
"""
- from headroom.proxy.handlers.openai import _compact_openai_responses_tools
+ from headroom.proxy.tool_schema_compaction import compact_tools
if cases is None:
cases = self.generate_tool_schema_cases()
@@ -512,9 +512,7 @@ class CompressionOnlyRunner:
total_original += original_bytes
try:
- compacted, modified, before_bytes, after_bytes = _compact_openai_responses_tools(
- payload
- )
+ compacted, modified, before_bytes, after_bytes = compact_tools(payload)
total_compressed += after_bytes if modified else original_bytes
case_errors: list[str] = []
diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.py
index b99c3cff4..60b59f4ac 100644
--- a/headroom/proxy/handlers/anthropic.py
+++ b/headroom/proxy/handlers/anthropic.py
@@ -2303,6 +2303,100 @@ class AnthropicHandlerMixin:
if tools != _original_tools:
body["tools"] = tools
+ # Tool schema compaction: strip annotation keys ($schema, title,
+ # examples, etc.) and normalise description whitespace. Runs
+ # after tools are finalised (sorting, CCR injection) but before
+ # the PRE_SEND pipeline event so extensions see the compacted
+ # schema. Mirrors the same pass that the OpenAI handler applies.
+ _tools_compaction_started = time.time()
+ try:
+ from headroom.proxy.tool_schema_compaction import compact_tools
+
+ body, _tools_modified, _tools_before_bytes, _tools_after_bytes = compact_tools(body)
+ if _tools_modified:
+ tools = body["tools"]
+ transforms_applied.append("anthropic:tool_schema_compaction")
+ _tools_compaction_ms = (time.time() - _tools_compaction_started) * 1000
+ logger.debug(
+ "[%s] tool schema compaction: %d -> %d bytes (%.0f%% saved) in %.1fms",
+ request_id,
+ _tools_before_bytes,
+ _tools_after_bytes,
+ (1 - _tools_after_bytes / max(_tools_before_bytes, 1)) * 100,
+ _tools_compaction_ms,
+ )
+ except Exception as _tools_compaction_exc:
+ _tools_modified = False
+ logger.warning(
+ "[%s] tool schema compaction FAILED: %s", request_id, _tools_compaction_exc
+ )
+
+ # Layer 2: Tool description truncation (opt-in via
+ # HEADROOM_TOOL_DESC_MAX_CHARS). Preserves first sentence
+ # of each description so tool selection still works.
+ try:
+ from headroom.proxy.tool_schema_compaction import (
+ compact_tool_descriptions,
+ tool_desc_max_chars,
+ )
+
+ _desc_max = tool_desc_max_chars()
+ if _desc_max > 0:
+ body, _desc_modified, _desc_before, _desc_after = compact_tool_descriptions(
+ body, _desc_max
+ )
+ if _desc_modified:
+ tools = body["tools"]
+ transforms_applied.append("anthropic:tool_desc_compaction")
+ logger.debug(
+ "[%s] tool description compaction: %d -> %d bytes (%.0f%% saved, max_chars=%d)",
+ request_id,
+ _desc_before,
+ _desc_after,
+ (1 - _desc_after / max(_desc_before, 1)) * 100,
+ _desc_max,
+ )
+ except Exception as _desc_compaction_exc:
+ _desc_modified = False
+ logger.warning(
+ "[%s] tool desc compaction FAILED: %s", request_id, _desc_compaction_exc
+ )
+
+ # Layer 3: System prompt compaction (opt-in via
+ # HEADROOM_SYSTEM_COMPACT). Uses CCR to compress large
+ # system content blocks (CLAUDE.md, rules, hooks, etc.)
+ # while preserving cache_control and short instruction blocks.
+ try:
+ from headroom.proxy.system_compaction import (
+ compact_system_prompt,
+ system_compact_enabled,
+ )
+ from headroom.transforms.compression_units import find_content_router
+
+ if system_compact_enabled():
+ _sys_router = find_content_router(self.anthropic_pipeline)
+ if _sys_router is not None:
+ body, _sys_modified, _sys_before, _sys_after = compact_system_prompt(
+ body,
+ router=_sys_router,
+ model=model,
+ request_id=request_id,
+ )
+ if _sys_modified:
+ transforms_applied.append("anthropic:system_prompt_compaction")
+ logger.debug(
+ "[%s] system prompt compaction: %d -> %d bytes (%.0f%% saved)",
+ request_id,
+ _sys_before,
+ _sys_after,
+ (1 - _sys_after / max(_sys_before, 1)) * 100,
+ )
+ except Exception as _sys_compaction_exc:
+ _sys_modified = False
+ logger.warning(
+ "[%s] system prompt compaction FAILED: %s", request_id, _sys_compaction_exc
+ )
+
presend_event = self.pipeline_extensions.emit(
PipelineStage.PRE_SEND,
operation="proxy.request",
diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.py
index 0fbbfa4b1..329b2d4e4 100644
--- a/headroom/proxy/handlers/openai.py
+++ b/headroom/proxy/handlers/openai.py
@@ -513,6 +513,8 @@ _OPENAI_TOOL_SCHEMA_DROP_KEYS = {
"title",
"writeOnly",
}
+# Kept for backward compatibility with evals that import this symbol.
+# The canonical set lives in headroom.proxy.tool_schema_compaction.
def _json_byte_len(value: Any) -> int:
@@ -598,45 +600,18 @@ def _compact_openai_tool_schema_value(
value: Any,
_parent_key: str | None = None,
) -> Any:
- if isinstance(value, list):
- return [_compact_openai_tool_schema_value(item, _parent_key) for item in value]
-
- if not isinstance(value, dict):
- return value
-
- compacted: dict[str, Any] = {}
- for key, child in value.items():
- # Don't drop keys that are property *names* inside a JSON Schema
- # `properties` object — only drop them when they are schema annotations.
- # e.g. a tool with a field literally named "title" must not be stripped.
- if _parent_key != "properties" and key in _OPENAI_TOOL_SCHEMA_DROP_KEYS:
- continue
-
- if key == "description" and isinstance(child, str):
- compacted[key] = " ".join(child.split())
- continue
-
- compacted[key] = _compact_openai_tool_schema_value(child, key)
+ # Delegate to shared compaction logic.
+ from headroom.proxy.tool_schema_compaction import compact_tool_schema_value
- return compacted
+ return compact_tool_schema_value(value, _parent_key)
def _compact_openai_responses_tools(
payload: dict[str, Any],
) -> tuple[dict[str, Any], bool, int, int]:
- tools = payload.get("tools")
- if not isinstance(tools, list) or not tools:
- return payload, False, 0, 0
-
- compacted_tools = _compact_openai_tool_schema_value(tools)
- before = _json_byte_len(tools)
- after = _json_byte_len(compacted_tools)
- if after >= before:
- return payload, False, before, after
+ from headroom.proxy.tool_schema_compaction import compact_tools
- updated = copy.deepcopy(payload)
- updated["tools"] = compacted_tools
- return updated, True, before, after
+ return compact_tools(payload)
def _responses_request_allows_memory_tool_continuation(payload: dict[str, Any]) -> bool:
@@ -2149,6 +2124,48 @@ class OpenAIHandlerMixin:
tools_bytes_saved=tools_before_bytes - tools_after_bytes,
)
+ # Layer 2: Tool description truncation (opt-in via
+ # HEADROOM_TOOL_DESC_MAX_CHARS).
+ try:
+ from headroom.proxy.tool_schema_compaction import (
+ compact_tool_descriptions,
+ tool_desc_max_chars,
+ )
+
+ _desc_max = tool_desc_max_chars()
+ if _desc_max > 0:
+ _desc_compact_started = time.perf_counter()
+ desc_payload, desc_modified, desc_before, desc_after = compact_tool_descriptions(
+ working, _desc_max
+ )
+ _add_timing("compression_tool_desc_compaction", _desc_compact_started)
+ if desc_modified:
+ working = desc_payload
+ modified = True
+ transforms.append("openai:responses:tool_desc_compaction")
+ try:
+ tokenizer = self.openai_provider.get_token_counter(model)
+ tokens_saved += max(
+ 0,
+ tokenizer.count_text(_json_debug_dumps(payload.get("tools")))
+ - tokenizer.count_text(_json_debug_dumps(working.get("tools"))),
+ )
+ except Exception:
+ pass
+ if debug_enabled:
+ _log_codex_compression_debug(
+ "codex_tool_desc_compaction",
+ request_id=request_id,
+ pass_id=pass_id,
+ model=model,
+ modified=True,
+ tools_bytes_before=desc_before,
+ tools_bytes_after=desc_after,
+ tools_bytes_saved=desc_before - desc_after,
+ )
+ except Exception:
+ pass
+
# Server-side Tool Search deferral (OpenAI Responses, gpt-5.4+): mark
# non-core function/MCP tools defer_loading + inject {"type": "tool_search"}
# so OpenAI keeps their heavy parameter schemas out of the model's context
diff --git a/headroom/proxy/system_compaction.py b/headroom/proxy/system_compaction.py
new file mode 100644
index 000000000..03ac42d3f
--- /dev/null
+++ b/headroom/proxy/system_compaction.py
@@ -0,0 +1,146 @@
+"""System-prompt compaction for Headroom proxy handlers.
+
+Compresses the ``system`` field in Anthropic Messages API requests
+using the existing ContentRouter (CCR), reducing the token cost of
+static context blocks (CLAUDE.md, rules, hooks, MCP instructions)
+without removing them entirely.
+
+Opt-in via ``HEADROOM_SYSTEM_COMPACT=1`` (default disabled).
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+from typing import Any
+
+# Minimum length (chars) for a system block to be eligible for compression.
+# Short instruction blocks (< 500 chars) are almost always critical and
+# should not be lossily compressed.
+_SYSTEM_COMPACT_MIN_CHARS = 500
+
+
+def system_compact_enabled() -> bool:
+ """Return whether system-prompt compaction is enabled via env var."""
+ return os.environ.get("HEADROOM_SYSTEM_COMPACT", "").strip() in ("1", "true")
+
+
+def system_compact_min_chars() -> int:
+ """Return the minimum block length for compression (env-configurable)."""
+ try:
+ return int(
+ os.environ.get("HEADROOM_SYSTEM_COMPACT_MIN_CHARS", str(_SYSTEM_COMPACT_MIN_CHARS))
+ )
+ except ValueError:
+ return _SYSTEM_COMPACT_MIN_CHARS
+
+
+def _json_byte_len(value: Any) -> int:
+ """Byte length of compact JSON serialisation (for size comparisons)."""
+ return len(json.dumps(value, ensure_ascii=False, default=str, separators=(",", ":")))
+
+
+def _compact_system_blocks(
+ blocks: list[dict[str, Any]],
+ router: Any,
+ model: str,
+ request_id: str,
+ min_chars: int,
+) -> tuple[list[dict[str, Any]], bool]:
+ """Compress eligible text blocks in *blocks* using *router*.
+
+ Returns ``(updated_blocks, modified)``. Blocks shorter than
+ *min_chars* are left untouched. ``cache_control`` and other
+ non-text fields are preserved unchanged.
+ """
+ modified = False
+ updated: list[dict[str, Any]] = []
+
+ for block in blocks:
+ if not isinstance(block, dict) or block.get("type") != "text":
+ updated.append(block)
+ continue
+
+ text = block.get("text", "")
+ if not isinstance(text, str) or len(text) < min_chars:
+ updated.append(block)
+ continue
+
+ # Attempt CCR compression.
+ try:
+ result = router.compress(text, context="")
+ compressed_text = result.compressed if hasattr(result, "compressed") else str(result)
+ except Exception:
+ # CCR failure → leave block unchanged.
+ updated.append(block)
+ continue
+
+ if not isinstance(compressed_text, str) or len(compressed_text) >= len(text):
+ # Compression didn't help → leave unchanged.
+ updated.append(block)
+ continue
+
+ new_block: dict[str, Any] = {"type": "text", "text": compressed_text}
+ # Preserve any other fields (cache_control, etc.)
+ for k, v in block.items():
+ if k not in ("type", "text"):
+ new_block[k] = v
+ updated.append(new_block)
+ modified = True
+
+ return updated, modified
+
+
+def compact_system_prompt(
+ payload: dict[str, Any],
+ router: Any,
+ model: str,
+ request_id: str,
+) -> tuple[dict[str, Any], bool, int, int]:
+ """Compress the ``system`` field in *payload* using CCR.
+
+ Returns ``(updated_payload, modified, before_bytes, after_bytes)``.
+ If compaction doesn't reduce size, the original payload is returned
+ unchanged and *modified* is ``False``.
+ """
+ system = payload.get("system")
+ if system is None:
+ return payload, False, 0, 0
+
+ min_chars = system_compact_min_chars()
+
+ # Anthropic system field can be a string or a list of content blocks.
+ if isinstance(system, str):
+ if len(system) < min_chars:
+ return payload, False, 0, 0
+ blocks: list[dict[str, Any]] = [{"type": "text", "text": system}]
+ elif isinstance(system, list):
+ blocks = system
+ else:
+ return payload, False, 0, 0
+
+ before = _json_byte_len(blocks)
+
+ updated_blocks, modified = _compact_system_blocks(
+ blocks,
+ router,
+ model,
+ request_id,
+ min_chars,
+ )
+
+ after = _json_byte_len(updated_blocks)
+ if not modified or after >= before:
+ return payload, False, before, after
+
+ updated = copy.deepcopy(payload)
+ # Restore in the original format.
+ if isinstance(system, str):
+ # Single-string system → reassemble from compressed blocks.
+ texts = [b.get("text", "") for b in updated_blocks if b.get("type") == "text"]
+ updated["system"] = "\n".join(texts)
+ else:
+ updated["system"] = updated_blocks
+
+ return updated, True, before, after
diff --git a/headroom/proxy/tool_schema_compaction.py b/headroom/proxy/tool_schema_compaction.py
new file mode 100644
index 000000000..d43a04cc5
--- /dev/null
+++ b/headroom/proxy/tool_schema_compaction.py
@@ -0,0 +1,416 @@
+"""Shared tool-schema compaction for Headroom proxy handlers.
+
+Strips JSON Schema annotation keys ($schema, title, examples, etc.)
+and normalises description whitespace to reduce the token cost of
+tool definitions without changing their semantics.
+
+Both the OpenAI and Anthropic handlers call the same compaction
+logic from this module.
+
+**Layer 2 — Tool Description Compaction**
+
+Truncates tool and parameter ``description`` strings to a configurable
+maximum length, preserving the first complete sentence so that the model
+can still select the right tool. Opt-in via
+``HEADROOM_TOOL_DESC_MAX_CHARS`` (default ``0`` = disabled).
+
+**Layer 3 — Semantic Parameter Description Removal**
+
+When a parameter name is self-explanatory (e.g. ``query``, ``owner``,
+``repo``), the ``description`` field adds little value — the model can
+infer the meaning from the name alone. Opt-in via
+``HEADROOM_TOOL_DESC_STRIP_SEMANTIC=1`` (default disabled).
+
+**Caching**
+
+Compaction results are keyed by the JSON digest of the tools array and
+the compaction config. Within a session where tools don't change, the
+cached result is reused — avoiding redundant recursive walks over 141+
+tool schemas on every API call.
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import os
+import re
+import threading
+from typing import Any
+
+# Keys that are JSON Schema annotations, not constraints.
+# Removing them does not change the set of valid inputs.
+TOOL_SCHEMA_DROP_KEYS: frozenset[str] = frozenset(
+ {
+ "$id",
+ "$schema",
+ "$comment",
+ "deprecated",
+ "examples",
+ "example",
+ "markdownDescription",
+ "readOnly",
+ "title",
+ "writeOnly",
+ }
+)
+
+# Parameter names that are self-explanatory. When ``description``
+# matches the name (case-insensitive prefix), it can be stripped.
+_SEMANTIC_PARAM_NAMES: frozenset[str] = frozenset(
+ {
+ "query",
+ "search",
+ "filter",
+ "sort",
+ "order",
+ "limit",
+ "offset",
+ "page",
+ "per_page",
+ "perpage",
+ "cursor",
+ "after",
+ "before",
+ "owner",
+ "repo",
+ "repository",
+ "org",
+ "organization",
+ "user",
+ "username",
+ "email",
+ "name",
+ "title",
+ "description",
+ "id",
+ "number",
+ "count",
+ "url",
+ "path",
+ "file",
+ "filename",
+ "branch",
+ "tag",
+ "sha",
+ "commit",
+ "ref",
+ "key",
+ "token",
+ "type",
+ "format",
+ "state",
+ "status",
+ "action",
+ "method",
+ "body",
+ "content",
+ "message",
+ "text",
+ "comment",
+ "note",
+ "start",
+ "end",
+ "from",
+ "to",
+ "direction",
+ "ascending",
+ "dry_run",
+ "verbose",
+ "force",
+ "recursive",
+ "include",
+ "exclude",
+ "pattern",
+ "regex",
+ "since",
+ "until",
+ }
+)
+
+# ---------------------------------------------------------------------------
+# Env-var helpers
+# ---------------------------------------------------------------------------
+
+_TOOL_DESC_MAX_CHARS: int | None = None
+_STRIP_SEMANTIC: bool | None = None
+
+
+def tool_desc_max_chars() -> int:
+ """Return the configured max description length (cached per-process).
+
+ ``HEADROOM_TOOL_DESC_MAX_CHARS=0`` (default) disables truncation.
+ """
+ global _TOOL_DESC_MAX_CHARS
+ if _TOOL_DESC_MAX_CHARS is None:
+ try:
+ _TOOL_DESC_MAX_CHARS = int(os.environ.get("HEADROOM_TOOL_DESC_MAX_CHARS", "0"))
+ except ValueError:
+ _TOOL_DESC_MAX_CHARS = 0
+ return _TOOL_DESC_MAX_CHARS
+
+
+def strip_semantic_params() -> bool:
+ """Return whether Layer 3 (semantic param removal) is enabled."""
+ global _STRIP_SEMANTIC
+ if _STRIP_SEMANTIC is None:
+ _STRIP_SEMANTIC = os.environ.get("HEADROOM_TOOL_DESC_STRIP_SEMANTIC", "0") == "1"
+ return _STRIP_SEMANTIC
+
+
+# ---------------------------------------------------------------------------
+# Compaction cache
+# ---------------------------------------------------------------------------
+
+_cache_lock = threading.Lock()
+_compaction_cache: dict[str, tuple[dict[str, Any], int, int]] = {}
+_CACHE_MAX_ENTRIES = 8
+
+
+def _cache_key(tools: list[Any], *config_vals: Any) -> str:
+ """Deterministic cache key from tools content + config values."""
+ h = hashlib.sha256()
+ h.update(json.dumps(tools, sort_keys=True, default=str, separators=(",", ":")).encode())
+ for v in config_vals:
+ h.update(str(v).encode())
+ return h.hexdigest()[:16]
+
+
+def _cache_get(key: str) -> tuple[dict[str, Any], int, int] | None:
+ with _cache_lock:
+ return _compaction_cache.get(key)
+
+
+def _cache_put(key: str, compacted: dict[str, Any], before: int, after: int) -> None:
+ with _cache_lock:
+ if len(_compaction_cache) >= _CACHE_MAX_ENTRIES:
+ # Evict oldest entry (first key).
+ _compaction_cache.pop(next(iter(_compaction_cache)))
+ _compaction_cache[key] = (compacted, before, after)
+
+
+def invalidate_cache() -> None:
+ """Clear the compaction cache (e.g. on config change)."""
+ with _cache_lock:
+ _compaction_cache.clear()
+
+
+# ---------------------------------------------------------------------------
+# Layer 1: annotation-key compaction
+# ---------------------------------------------------------------------------
+
+
+def _json_byte_len(value: Any) -> int:
+ """Byte length of compact JSON serialisation (for size comparisons)."""
+ return len(json.dumps(value, ensure_ascii=False, default=str, separators=(",", ":")))
+
+
+def compact_tool_schema_value(
+ value: Any,
+ _parent_key: str | None = None,
+) -> Any:
+ """Recursively compact a tool-schema structure.
+
+ - Drops annotation keys (``TOOL_SCHEMA_DROP_KEYS``) unless they appear
+ as property *names* inside a ``properties`` object (e.g. a field
+ literally named ``"title"`` must survive).
+ - Normalises ``description`` strings by collapsing whitespace.
+ """
+ if isinstance(value, list):
+ return [compact_tool_schema_value(item, _parent_key) for item in value]
+
+ if not isinstance(value, dict):
+ return value
+
+ compacted: dict[str, Any] = {}
+ for key, child in value.items():
+ # Don't drop keys that are property *names* inside a JSON Schema
+ # `properties` object — only drop them when they are schema annotations.
+ if _parent_key != "properties" and key in TOOL_SCHEMA_DROP_KEYS:
+ continue
+
+ if key == "description" and isinstance(child, str):
+ compacted[key] = " ".join(child.split())
+ continue
+
+ compacted[key] = compact_tool_schema_value(child, key)
+
+ return compacted
+
+
+def compact_tools(
+ payload: dict[str, Any],
+) -> tuple[dict[str, Any], bool, int, int]:
+ """Compact the ``tools`` array in *payload*.
+
+ Returns ``(updated_payload, modified, before_bytes, after_bytes)``.
+ If compaction did not reduce size, the original payload is returned
+ unchanged and *modified* is ``False``.
+
+ Results are cached by tools digest — repeated calls with the same
+ tools array return the cached compacted version immediately.
+ """
+ tools = payload.get("tools")
+ if not isinstance(tools, list) or not tools:
+ return payload, False, 0, 0
+
+ key = _cache_key(tools, "L1")
+ cached = _cache_get(key)
+ if cached is not None:
+ compacted_tools, before, after = cached
+ if after >= before:
+ return payload, False, before, after
+ updated = copy.deepcopy(payload)
+ updated["tools"] = compacted_tools
+ return updated, True, before, after
+
+ compacted_tools = compact_tool_schema_value(tools)
+ before = _json_byte_len(tools)
+ after = _json_byte_len(compacted_tools)
+ _cache_put(key, compacted_tools, before, after)
+
+ if after >= before:
+ return payload, False, before, after
+
+ updated = copy.deepcopy(payload)
+ updated["tools"] = compacted_tools
+ return updated, True, before, after
+
+
+# ---------------------------------------------------------------------------
+# Layer 2: description truncation
+# ---------------------------------------------------------------------------
+
+_FIRST_SENTENCE_RE = re.compile(r"^(.*?[.!?])(?:\s|$)", re.DOTALL)
+
+
+def _truncate_description(desc: str, max_chars: int) -> str:
+ """Truncate *desc* to *max_chars*, preserving the first complete sentence.
+
+ Strategy:
+ - *max_chars* ≤ 0: return *desc* unchanged (feature disabled).
+ - Short descriptions (≤ *max_chars*) pass through unchanged.
+ - Normalise whitespace before any truncation.
+ - If the first sentence fits in *max_chars*, keep it and optionally
+ append the second sentence when the combined length ≤ 1.5× *max_chars*.
+ - If the first sentence alone exceeds *max_chars*, hard-truncate
+ and append ``…``.
+ """
+ if max_chars <= 0:
+ return desc
+
+ # Normalise whitespace first (mirrors Layer 1 behaviour).
+ desc = " ".join(desc.split())
+
+ if len(desc) <= max_chars:
+ return desc
+
+ m = _FIRST_SENTENCE_RE.match(desc)
+ if m and len(m.group(1)) <= max_chars:
+ first = m.group(1)
+ rest = desc[len(first) :].strip()
+ if rest:
+ m2 = _FIRST_SENTENCE_RE.match(rest)
+ if m2 and len(first) + 1 + len(m2.group(1)) <= int(max_chars * 1.5):
+ return f"{first} {m2.group(1)}"
+ return first
+
+ # First sentence too long → hard truncation.
+ return desc[:max_chars].rstrip() + "…"
+
+
+def _is_semantic_param_name(name: str) -> bool:
+ """Check if a parameter name is self-explanatory."""
+ return name.lower().replace("-", "_") in _SEMANTIC_PARAM_NAMES
+
+
+def _truncate_descriptions_in_schema(
+ value: Any,
+ max_chars: int,
+ strip_semantic: bool = False,
+ _parent_key: str | None = None,
+ _grandparent_key: str | None = None,
+) -> Any:
+ """Recursively truncate ``description`` fields in a tool-schema structure.
+
+ When *strip_semantic* is True and the field lives inside
+ ``properties.<name>.description`` where *name* is self-explanatory,
+ the description is dropped entirely instead of truncated.
+ """
+ if isinstance(value, list):
+ return [_truncate_descriptions_in_schema(item, max_chars, strip_semantic) for item in value]
+
+ if not isinstance(value, dict):
+ return value
+
+ compacted: dict[str, Any] = {}
+ for key, child in value.items():
+ if key == "description" and isinstance(child, str):
+ # Layer 3: strip descriptions on self-explanatory params.
+ if (
+ strip_semantic
+ and _grandparent_key == "properties"
+ and _parent_key
+ and _is_semantic_param_name(_parent_key)
+ ):
+ # ponytail: drop description on semantic params — the name alone is enough.
+ continue
+ compacted[key] = _truncate_description(child, max_chars)
+ else:
+ compacted[key] = _truncate_descriptions_in_schema(
+ child,
+ max_chars,
+ strip_semantic,
+ _parent_key=key,
+ _grandparent_key=_parent_key,
+ )
+
+ return compacted
+
+
+def compact_tool_descriptions(
+ payload: dict[str, Any],
+ max_chars: int = 0,
+) -> tuple[dict[str, Any], bool, int, int]:
+ """Truncate tool descriptions in *payload* to *max_chars*.
+
+ Returns ``(updated_payload, modified, before_bytes, after_bytes)``.
+ If *max_chars* is 0 (default) or compaction doesn't reduce size,
+ the original payload is returned unchanged.
+
+ When ``HEADROOM_TOOL_DESC_STRIP_SEMANTIC=1``, descriptions on
+ self-explanatory parameters (e.g. ``query``, ``owner``) are
+ removed entirely instead of truncated.
+
+ Results are cached by tools digest + config.
+ """
+ if max_chars <= 0:
+ return payload, False, 0, 0
+
+ tools = payload.get("tools")
+ if not isinstance(tools, list) or not tools:
+ return payload, False, 0, 0
+
+ strip_sem = strip_semantic_params()
+ key = _cache_key(tools, "L2", max_chars, strip_sem)
+ cached = _cache_get(key)
+ if cached is not None:
+ compacted_tools, before, after = cached
+ if after >= before:
+ return payload, False, before, after
+ updated = copy.deepcopy(payload)
+ updated["tools"] = compacted_tools
+ return updated, True, before, after
+
+ compacted_tools = _truncate_descriptions_in_schema(tools, max_chars, strip_sem)
+ before = _json_byte_len(tools)
+ after = _json_byte_len(compacted_tools)
+ _cache_put(key, compacted_tools, before, after)
+
+ if after >= before:
+ return payload, False, before, after
+
+ updated = copy.deepcopy(payload)
+ updated["tools"] = compacted_tools
+ return updated, True, before, after
diff --git a/tests/test_anthropic_compaction_transforms.py b/tests/test_anthropic_compaction_transforms.py
new file mode 100644
index 000000000..f2f078eaa
--- /dev/null
+++ b/tests/test_anthropic_compaction_transforms.py
@@ -0,0 +1,313 @@
+"""Handler-level regression tests for Anthropic compaction transforms_applied reporting.
+
+Verifies that when tool-schema compaction (L1), tool-description compaction (L2),
+or system-prompt compaction (L3) modifies an Anthropic request, the corresponding
+label is appended to ``transforms_applied`` so that ``/stats`` and the
+transformation accounting remain accurate.
+
+These tests exercise the handler wiring directly (not just the helper functions)
+to catch the specific bug where Anthropic omitted the append calls that the
+OpenAI handler already had.
+"""
+
+from __future__ import annotations
+
+import os
+from unittest.mock import patch
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Fixtures / helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_anthropic_payload_with_tools() -> dict:
+ """Minimal Anthropic-style payload with tools that will be compacted."""
+ return {
+ "model": "claude-sonnet-4-6",
+ "system": "You are a helpful assistant.",
+ "messages": [{"role": "user", "content": "hello"}],
+ "tools": [
+ {
+ "name": "read_file",
+ "description": "Read the contents of a file from disk. "
+ "Returns the full text content as a string.",
+ "input_schema": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "read_file_schema",
+ "examples": [{"path": "/tmp/test.txt"}],
+ "type": "object",
+ "properties": {
+ "path": {"type": "string", "description": "File path"},
+ },
+ "required": ["path"],
+ },
+ }
+ ],
+ "max_tokens": 1024,
+ }
+
+
+def _make_anthropic_payload_with_long_system() -> dict:
+ """Payload with a long system prompt that qualifies for L3 compaction."""
+ long_text = "x" * 5000 # well above default min_chars
+ return {
+ "model": "claude-sonnet-4-6",
+ "system": [
+ {"type": "text", "text": long_text, "cache_control": {"type": "ephemeral"}},
+ ],
+ "messages": [{"role": "user", "content": "hello"}],
+ "tools": [],
+ "max_tokens": 1024,
+ }
+
+
+# ---------------------------------------------------------------------------
+# L1: Tool schema compaction
+# ---------------------------------------------------------------------------
+
+
+class TestAnthropicToolSchemaCompactionTransforms:
+ """When L1 compaction modifies tools, ``anthropic:tool_schema_compaction``
+ must appear in ``transforms_applied``."""
+
+ def test_l1_appends_transform_label(self) -> None:
+ from headroom.proxy.tool_schema_compaction import compact_tools
+
+ payload = _make_anthropic_payload_with_tools()
+ body, modified, before, after = compact_tools(payload)
+
+ assert modified is True
+ # The handler code does:
+ # if _tools_modified:
+ # transforms_applied.append("anthropic:tool_schema_compaction")
+ # We verify the condition that triggers the append is met.
+ assert before > after
+
+ def test_l1_skips_label_when_no_compaction(self) -> None:
+ from headroom.proxy.tool_schema_compaction import compact_tools
+
+ payload = _make_anthropic_payload_with_tools()
+ # Already compact — remove annotation keys AND normalise description
+ # so compact_tools has nothing to change.
+ schema = payload["tools"][0]["input_schema"]
+ schema.pop("$schema", None)
+ schema.pop("title", None)
+ schema.pop("examples", None)
+ # Normalise description whitespace to match compaction output.
+ payload["tools"][0]["description"] = " ".join(payload["tools"][0]["description"].split())
+
+ body, modified, before, after = compact_tools(payload)
+ # When nothing can be compacted, the handler should NOT append the label.
+ # We verify the condition: _tools_modified must be False.
+ assert modified is False
+
+
+# ---------------------------------------------------------------------------
+# L2: Tool description compaction
+# ---------------------------------------------------------------------------
+
+
+class TestAnthropicToolDescCompactionTransforms:
+ """When L2 compaction truncates descriptions,
+ ``anthropic:tool_desc_compaction`` must appear in ``transforms_applied``."""
+
+ def test_l2_appends_transform_label(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from headroom.proxy.tool_schema_compaction import (
+ compact_tool_descriptions,
+ tool_desc_max_chars,
+ )
+
+ # Opt-in with a very short max so truncation triggers.
+ monkeypatch.setenv("HEADROOM_TOOL_DESC_MAX_CHARS", "20")
+
+ payload = _make_anthropic_payload_with_tools()
+ max_chars = tool_desc_max_chars()
+ assert max_chars == 20
+
+ body, modified, before, after = compact_tool_descriptions(payload, max_chars)
+ assert modified is True
+ assert before > after
+
+ def test_l2_skips_label_when_disabled(self) -> None:
+ import headroom.proxy.tool_schema_compaction as _mod
+ from headroom.proxy.tool_schema_compaction import tool_desc_max_chars
+
+ # Reset the per-process cache so the env var is re-read.
+ _mod._TOOL_DESC_MAX_CHARS = None
+ with patch.dict(os.environ, {}, clear=True):
+ max_chars = tool_desc_max_chars()
+ # Restore cache state for subsequent tests.
+ _mod._TOOL_DESC_MAX_CHARS = None
+ # When max_chars == 0, the handler skips the entire L2 block,
+ # so no append happens.
+ assert max_chars == 0
+
+
+# ---------------------------------------------------------------------------
+# L3: System prompt compaction
+# ---------------------------------------------------------------------------
+
+
+class TestAnthropicSystemCompactionTransforms:
+ """When L3 compaction compresses system blocks,
+ ``anthropic:system_prompt_compaction`` must appear in ``transforms_applied``."""
+
+ def test_l3_appends_transform_label(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from headroom.proxy.system_compaction import (
+ compact_system_prompt,
+ )
+
+ monkeypatch.setenv("HEADROOM_SYSTEM_COMPACT", "1")
+
+ payload = _make_anthropic_payload_with_long_system()
+
+ # Mock the router so we don't need a real one.
+ class _MockCompressResult:
+ def __init__(self, compressed: str):
+ self.compressed = compressed
+
+ class _MockRouter:
+ def compress(self, text: str, **kwargs):
+ return _MockCompressResult(text[:100])
+
+ body, modified, before, after = compact_system_prompt(
+ payload,
+ router=_MockRouter(),
+ model="claude-sonnet-4-6",
+ request_id="test-req",
+ )
+
+ assert modified is True
+ assert before > after
+
+ def test_l3_skips_label_when_disabled(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ from headroom.proxy.system_compaction import system_compact_enabled
+
+ monkeypatch.delenv("HEADROOM_SYSTEM_COMPACT", raising=False)
+ assert system_compact_enabled() is False
+ # When disabled, the handler skips L3 entirely, so no append.
+
+
+# ---------------------------------------------------------------------------
+# Handler-level end-to-end regression (issue: Anthropic omitted the append)
+#
+# The tests above exercise the helper return values in isolation. These below
+# drive the *handler wiring* end-to-end: a real ``_handle_anthropic_request``
+# runs against a tool-bearing payload, the live ``compact_tools`` mutates it,
+# and the L1 label must surface on the ``x-headroom-transforms`` response
+# header. This is the gap the maintainer flagged -- the bug lived in the
+# handler's append call, not in the helpers.
+# ---------------------------------------------------------------------------
+
+import httpx # noqa: E402
+
+pytest.importorskip("fastapi")
+
+from fastapi.testclient import TestClient # noqa: E402
+
+from headroom.proxy.server import ProxyConfig, create_app # noqa: E402
+
+
+def _make_proxy_client() -> TestClient:
+ config = ProxyConfig(
+ optimize=True,
+ mode="token",
+ cache_enabled=False,
+ rate_limit_enabled=False,
+ cost_tracking_enabled=False,
+ log_requests=False,
+ ccr_inject_tool=False,
+ ccr_handle_responses=False,
+ ccr_context_tracking=False,
+ image_optimize=False,
+ )
+ app = create_app(config)
+ return TestClient(app)
+
+
+def _ok_response(msg_id: str) -> httpx.Response:
+ return httpx.Response(
+ 200,
+ json={
+ "id": msg_id,
+ "type": "message",
+ "role": "assistant",
+ "content": [{"type": "text", "text": "ok"}],
+ "usage": {
+ "input_tokens": 10,
+ "output_tokens": 3,
+ "cache_read_input_tokens": 0,
+ "cache_creation_input_tokens": 0,
+ },
+ },
+ )
+
+
+class TestAnthropicHandlerReportsL1Transform:
+ """End-to-end: when L1 tool-schema compaction mutates the request, the
+ handler must append ``anthropic:tool_schema_compaction`` so it reaches the
+ ``x-headroom-transforms`` response header -- not just the helper's
+ ``modified`` flag."""
+
+ def test_l1_label_reaches_response_header(self) -> None:
+ from types import SimpleNamespace
+
+ with _make_proxy_client() as client:
+ proxy = client.app.state.proxy
+
+ def _fake_apply(**kwargs):
+ # Return the minimum result shape the handler reads; let the
+ # handler's own compaction pass (which runs after apply) do the
+ # real mutation we are testing.
+ return SimpleNamespace(
+ messages=kwargs["messages"],
+ transforms_applied=[],
+ timing={},
+ tokens_before=10,
+ tokens_after=10,
+ waste_signals=None,
+ )
+
+ proxy.anthropic_pipeline.apply = _fake_apply
+
+ async def _fake_retry(method, url, headers, body, stream=False, **kwargs): # noqa: ANN001
+ return _ok_response("msg_l1_e2e")
+
+ proxy._retry_request = _fake_retry
+
+ response = client.post(
+ "/v1/messages",
+ headers={
+ "x-api-key": "test-key",
+ "anthropic-version": "2023-06-01",
+ },
+ json={
+ "model": "claude-sonnet-4-6",
+ "max_tokens": 64,
+ "messages": [{"role": "user", "content": "hello"}],
+ "tools": [
+ {
+ "name": "read_file",
+ "description": "Read a file from disk. Returns text content.",
+ "input_schema": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "read_file_schema",
+ "examples": [{"path": "/tmp/test.txt"}],
+ "type": "object",
+ "properties": {
+ "path": {"type": "string"},
+ },
+ "required": ["path"],
+ },
+ }
+ ],
+ },
+ )
+
+ assert response.status_code == 200, response.text
+ transforms_header = response.headers.get("x-headroom-transforms", "")
+ assert "anthropic:tool_schema_compaction" in transforms_header, (
+ f"expected L1 label in x-headroom-transforms, got: {transforms_header!r}"
+ )
diff --git a/tests/test_system_compaction.py b/tests/test_system_compaction.py
new file mode 100644
index 000000000..c39c3a888
--- /dev/null
+++ b/tests/test_system_compaction.py
@@ -0,0 +1,249 @@
+"""Tests for headroom.proxy.system_compaction — Layer 3 system-prompt compression.
+
+Verifies that system-prompt compaction:
+- compresses eligible (long) text blocks via a mock ContentRouter
+- preserves short blocks, cache_control, and non-text blocks
+- handles both string and content-blocks system field formats
+- returns payload unchanged when compaction doesn't help
+"""
+
+from __future__ import annotations
+
+from headroom.proxy.system_compaction import (
+ compact_system_prompt,
+ system_compact_enabled,
+ system_compact_min_chars,
+)
+
+
+class _MockCompressResult:
+ def __init__(self, compressed: str):
+ self.compressed = compressed
+
+
+class _MockRouter:
+ """Minimal mock of ContentRouter that shortens text by 50%."""
+
+ def compress(self, text: str, context: str = "", model: str = "") -> _MockCompressResult:
+ # Simple "compression": keep first half
+ half = len(text) // 2
+ return _MockCompressResult(text[:half])
+
+
+class _NoopRouter:
+ """Mock router whose compression never reduces size."""
+
+ def compress(self, text: str, context: str = "", model: str = "") -> _MockCompressResult:
+ # Return something longer than input
+ return _MockCompressResult(text + " expanded")
+
+
+class _FailRouter:
+ """Mock router that always raises."""
+
+ def compress(self, text: str, context: str = "", model: str = "") -> None:
+ raise RuntimeError("CCR unavailable")
+
+
+class TestCompactSystemPromptContentBlocks:
+ """Tests for content-blocks format (Anthropic standard)."""
+
+ def test_compresses_long_blocks(self) -> None:
+ payload = {
+ "model": "claude-sonnet-4-20250514",
+ "system": [
+ {"type": "text", "text": "A" * 1000},
+ {"type": "text", "text": "B" * 600},
+ ],
+ "messages": [],
+ }
+ result, modified, before, after = compact_system_prompt(
+ payload,
+ router=_MockRouter(),
+ model="claude-sonnet-4-20250514",
+ request_id="test1",
+ )
+ assert modified is True
+ assert after < before
+ # Each block should be compressed
+ for block in result["system"]:
+ if block.get("type") == "text":
+ assert len(block["text"]) < 1000
+
+ def test_preserves_short_blocks(self) -> None:
+ """Blocks shorter than min_chars should not be touched."""
+ payload = {
+ "system": [
+ {"type": "text", "text": "Short instruction."},
+ ],
+ }
+ result, modified, _, _ = compact_system_prompt(
+ payload,
+ router=_MockRouter(),
+ model="m",
+ request_id="test2",
+ )
+ assert modified is False
+ assert result["system"][0]["text"] == "Short instruction."
+
+ def test_preserves_cache_control(self) -> None:
+ """cache_control must survive compaction."""
+ payload = {
+ "system": [
+ {
+ "type": "text",
+ "text": "A" * 1000,
+ "cache_control": {"type": "ephemeral"},
+ },
+ ],
+ }
+ result, modified, _, _ = compact_system_prompt(
+ payload,
+ router=_MockRouter(),
+ model="m",
+ request_id="test3",
+ )
+ assert modified is True
+ block = result["system"][0]
+ assert block["cache_control"] == {"type": "ephemeral"}
+
+ def test_preserves_non_text_blocks(self) -> None:
+ payload = {
+ "system": [
+ {"type": "text", "text": "A" * 1000},
+ {"type": "image", "source": {"type": "base64", "data": "..."}},
+ ],
+ }
+ result, modified, _, _ = compact_system_prompt(
+ payload,
+ router=_MockRouter(),
+ model="m",
+ request_id="test4",
+ )
+ assert modified is True
+ # Image block preserved unchanged
+ image_block = result["system"][1]
+ assert image_block["type"] == "image"
+
+ def test_noop_router_returns_unchanged(self) -> None:
+ payload = {
+ "system": [
+ {"type": "text", "text": "A" * 1000},
+ ],
+ }
+ result, modified, _, _ = compact_system_prompt(
+ payload,
+ router=_NoopRouter(),
+ model="m",
+ request_id="test5",
+ )
+ assert modified is False
+ assert result is payload
+
+ def test_failing_router_returns_unchanged(self) -> None:
+ payload = {
+ "system": [
+ {"type": "text", "text": "A" * 1000},
+ ],
+ }
+ result, modified, _, _ = compact_system_prompt(
+ payload,
+ router=_FailRouter(),
+ model="m",
+ request_id="test6",
+ )
+ assert modified is False
+
+ def test_no_system_field_returns_unchanged(self) -> None:
+ payload = {"model": "claude-sonnet-4-20250514", "messages": []}
+ result, modified, _, _ = compact_system_prompt(
+ payload,
+ router=_MockRouter(),
+ model="m",
+ request_id="test7",
+ )
+ assert modified is False
+ assert result is payload
+
+ def test_empty_system_list(self) -> None:
+ payload = {"system": []}
+ result, modified, _, _ = compact_system_prompt(
+ payload,
+ router=_MockRouter(),
+ model="m",
+ request_id="test8",
+ )
+ assert modified is False
+
+ def test_preserves_non_system_fields(self) -> None:
+ payload = {
+ "model": "claude-sonnet-4-20250514",
+ "max_tokens": 8192,
+ "system": [
+ {"type": "text", "text": "A" * 1000},
+ ],
+ "messages": [{"role": "user", "content": "hi"}],
+ }
+ result, _, _, _ = compact_system_prompt(
+ payload,
+ router=_MockRouter(),
+ model="m",
+ request_id="test9",
+ )
+ assert result["model"] == "claude-sonnet-4-20250514"
+ assert result["max_tokens"] == 8192
+ assert len(result["messages"]) == 1
+
+
+class TestCompactSystemPromptString:
+ """Tests for string-format system field."""
+
+ def test_compresses_long_string(self) -> None:
+ payload = {
+ "system": "A" * 1000,
+ }
+ result, modified, before, after = compact_system_prompt(
+ payload,
+ router=_MockRouter(),
+ model="m",
+ request_id="test_s1",
+ )
+ assert modified is True
+ assert after < before
+ assert len(result["system"]) < 1000
+
+ def test_short_string_unchanged(self) -> None:
+ payload = {
+ "system": "Short instruction.",
+ }
+ result, modified, _, _ = compact_system_prompt(
+ payload,
+ router=_MockRouter(),
+ model="m",
+ request_id="test_s2",
+ )
+ assert modified is False
+
+
+class TestEnvVarHelpers:
+ """Tests for env-var configuration helpers."""
+
+ def test_system_compact_enabled_default(self, monkeypatch) -> None:
+ monkeypatch.delenv("HEADROOM_SYSTEM_COMPACT", raising=False)
+ # Force re-read
+ import headroom.proxy.system_compaction as sc
+
+ # The function reads env directly, so this should work
+ assert not sc.system_compact_enabled()
+
+ def test_system_compact_enabled_true(self, monkeypatch) -> None:
+ monkeypatch.setenv("HEADROOM_SYSTEM_COMPACT", "1")
+ assert system_compact_enabled()
+
+ def test_system_compact_min_chars_default(self, monkeypatch) -> None:
+ monkeypatch.delenv("HEADROOM_SYSTEM_COMPACT_MIN_CHARS", raising=False)
+ assert system_compact_min_chars() == 500
+
+ def test_system_compact_min_chars_custom(self, monkeypatch) -> None:
+ monkeypatch.setenv("HEADROOM_SYSTEM_COMPACT_MIN_CHARS", "200")
+ assert system_compact_min_chars() == 200
diff --git a/tests/test_tool_schema_compaction.py b/tests/test_tool_schema_compaction.py
new file mode 100644
index 000000000..3fc7467a9
--- /dev/null
+++ b/tests/test_tool_schema_compaction.py
@@ -0,0 +1,471 @@
+"""Tests for headroom.proxy.tool_schema_compaction — shared tool-schema compaction.
+
+Verifies that the compaction logic (shared by OpenAI and Anthropic handlers):
+- strips JSON Schema annotation keys ($schema, title, examples, …)
+- preserves property names that collide with DROP_KEYS (e.g. a field named "title")
+- normalises description whitespace
+- never inflates payload size
+"""
+
+from __future__ import annotations
+
+from headroom.proxy.tool_schema_compaction import (
+ compact_tool_schema_value,
+ compact_tools,
+)
+
+# ---------------------------------------------------------------------------
+# compact_tool_schema_value
+# ---------------------------------------------------------------------------
+
+
+class TestCompactToolSchemaValue:
+ """Unit tests for compact_tool_schema_value."""
+
+ def test_drops_schema_annotations(self) -> None:
+ schema = {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "MyToolParams",
+ "type": "object",
+ "properties": {"x": {"type": "integer"}},
+ "required": ["x"],
+ }
+ result = compact_tool_schema_value(schema)
+ assert "$schema" not in result
+ assert "title" not in result
+ assert "type" in result
+ assert "properties" in result
+ assert "required" in result
+
+ def test_preserves_property_named_title(self) -> None:
+ """A field literally named 'title' must survive (not a schema annotation)."""
+ schema = {
+ "type": "object",
+ "properties": {
+ "title": {"type": "string"},
+ "code": {"type": "string"},
+ },
+ "required": ["title", "code"],
+ }
+ result = compact_tool_schema_value(schema)
+ props = result["properties"]
+ assert "title" in props, "property named 'title' must survive"
+ assert "code" in props
+
+ def test_normalises_description_whitespace(self) -> None:
+ schema = {
+ "name": "my_tool",
+ "description": " This is a description \n with extra spaces ",
+ "input_schema": {"type": "object", "properties": {}},
+ }
+ result = compact_tool_schema_value(schema)
+ assert result["description"] == "This is a description with extra spaces"
+
+ def test_drops_examples_and_deprecated(self) -> None:
+ schema = {
+ "type": "object",
+ "properties": {
+ "x": {
+ "type": "integer",
+ "examples": [1, 2, 3],
+ "deprecated": True,
+ },
+ },
+ }
+ result = compact_tool_schema_value(schema)
+ prop_x = result["properties"]["x"]
+ assert "examples" not in prop_x
+ assert "deprecated" not in prop_x
+ assert prop_x["type"] == "integer"
+
+ def test_preserves_property_named_deprecated(self) -> None:
+ schema = {
+ "type": "object",
+ "properties": {
+ "deprecated": {"type": "boolean", "description": "Is it deprecated?"},
+ },
+ }
+ result = compact_tool_schema_value(schema)
+ assert "deprecated" in result["properties"]
+
+ def test_handles_list_of_tools(self) -> None:
+ tools = [
+ {
+ "name": "tool_a",
+ "description": " First tool ",
+ "input_schema": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "ToolAParams",
+ "type": "object",
+ "properties": {"a": {"type": "string"}},
+ },
+ },
+ {
+ "name": "tool_b",
+ "description": " Second tool ",
+ "input_schema": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "ToolBParams",
+ "type": "object",
+ "properties": {"b": {"type": "integer"}},
+ },
+ },
+ ]
+ result = compact_tool_schema_value(tools)
+ assert len(result) == 2
+ for tool in result:
+ assert "$schema" not in tool["input_schema"]
+ assert "title" not in tool["input_schema"]
+ assert " " not in tool["description"]
+
+ def test_nested_properties_preserved(self) -> None:
+ schema = {
+ "type": "object",
+ "properties": {
+ "config": {
+ "type": "object",
+ "title": "ConfigObject", # annotation — should be dropped
+ "properties": {
+ "title": {"type": "string"}, # property name — must survive
+ "value": {"type": "integer"},
+ },
+ },
+ },
+ }
+ result = compact_tool_schema_value(schema)
+ # Top-level config annotation dropped
+ assert "title" not in result["properties"]["config"]
+ # But nested property named "title" preserved
+ assert "title" in result["properties"]["config"]["properties"]
+
+
+# ---------------------------------------------------------------------------
+# compact_tools
+# ---------------------------------------------------------------------------
+
+
+class TestCompactTools:
+ """Unit tests for compact_tools (full payload compaction)."""
+
+ def test_compacts_anthropic_style_payload(self) -> None:
+ """Anthropic Messages API format uses 'input_schema'."""
+ payload = {
+ "model": "claude-sonnet-4-20250514",
+ "messages": [{"role": "user", "content": "hello"}],
+ "tools": [
+ {
+ "name": "get_weather",
+ "description": " Get the current weather ",
+ "input_schema": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "GetWeatherParams",
+ "type": "object",
+ "properties": {
+ "location": {"type": "string"},
+ },
+ "required": ["location"],
+ },
+ },
+ ],
+ }
+ result, modified, before, after = compact_tools(payload)
+ assert modified is True
+ assert after < before
+ tool = result["tools"][0]
+ assert " " not in tool["description"]
+ assert "$schema" not in tool["input_schema"]
+ assert "title" not in tool["input_schema"]
+ assert "properties" in tool["input_schema"]
+
+ def test_compacts_openai_style_payload(self) -> None:
+ """OpenAI format uses 'parameters' instead of 'input_schema'."""
+ payload = {
+ "tools": [
+ {
+ "type": "function",
+ "name": "read_file",
+ "description": "Read a file from disk.",
+ "parameters": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": "ReadFileParams",
+ "type": "object",
+ "properties": {
+ "path": {"type": "string", "examples": ["/tmp/test"]},
+ },
+ "required": ["path"],
+ },
+ },
+ ],
+ }
+ result, modified, before, after = compact_tools(payload)
+ assert modified is True
+ assert after < before
+ params = result["tools"][0]["parameters"]
+ assert "$schema" not in params
+ assert "title" not in params
+ assert "examples" not in params["properties"]["path"]
+
+ def test_returns_unchanged_when_no_tools(self) -> None:
+ payload = {"model": "claude-sonnet-4-20250514", "messages": []}
+ result, modified, _, _ = compact_tools(payload)
+ assert modified is False
+ assert result is payload # same object, not copied
+
+ def test_returns_unchanged_when_empty_tools(self) -> None:
+ payload = {"tools": []}
+ result, modified, _, _ = compact_tools(payload)
+ assert modified is False
+
+ def test_returns_unchanged_when_already_compact(self) -> None:
+ payload = {
+ "tools": [
+ {
+ "name": "simple",
+ "description": "A simple tool",
+ "input_schema": {
+ "type": "object",
+ "properties": {"x": {"type": "integer"}},
+ },
+ },
+ ],
+ }
+ result, modified, before, after = compact_tools(payload)
+ # May or may not be modified depending on description whitespace
+ # but should never inflate
+ assert after <= before
+
+ def test_preserves_non_tool_fields(self) -> None:
+ payload = {
+ "model": "claude-sonnet-4-20250514",
+ "max_tokens": 1024,
+ "messages": [{"role": "user", "content": "hi"}],
+ "tools": [
+ {
+ "name": "t",
+ "description": "test",
+ "input_schema": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "type": "object",
+ },
+ },
+ ],
+ }
+ result, _, _, _ = compact_tools(payload)
+ assert result["model"] == "claude-sonnet-4-20250514"
+ assert result["max_tokens"] == 1024
+ assert len(result["messages"]) == 1
+
+ def test_large_github_like_tool_set(self) -> None:
+ """Simulate a large tool set (like GitHub MCP with 44 tools)."""
+ tools = []
+ for i in range(44):
+ tools.append(
+ {
+ "name": f"github_tool_{i}",
+ "description": f" Perform operation {i} on GitHub repositories ",
+ "input_schema": {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "title": f"GithubTool{i}Params",
+ "type": "object",
+ "properties": {
+ "owner": {"type": "string", "description": " Repo owner "},
+ "repo": {"type": "string", "examples": ["my-repo"]},
+ },
+ "required": ["owner", "repo"],
+ },
+ }
+ )
+ payload = {"model": "claude-sonnet-4-20250514", "tools": tools}
+ result, modified, before, after = compact_tools(payload)
+ assert modified is True
+ savings_pct = (1 - after / before) * 100
+ # Expect meaningful savings (at least 15% with annotation keys + whitespace)
+ assert savings_pct >= 10, f"Expected ≥10% savings, got {savings_pct:.1f}%"
+
+
+# ---------------------------------------------------------------------------
+# Layer 2: compact_tool_descriptions
+# ---------------------------------------------------------------------------
+
+
+class TestTruncateDescription:
+ """Unit tests for _truncate_description."""
+
+ def test_short_description_unchanged(self) -> None:
+ from headroom.proxy.tool_schema_compaction import _truncate_description
+
+ assert _truncate_description("Read a file.", 120) == "Read a file."
+
+ def test_first_sentence_preserved(self) -> None:
+ from headroom.proxy.tool_schema_compaction import _truncate_description
+
+ desc = "Fast and precise code search across ALL GitHub repositories. Best for finding exact symbols."
+ result = _truncate_description(desc, 60)
+ assert result == "Fast and precise code search across ALL GitHub repositories."
+
+ def test_first_sentence_plus_second(self) -> None:
+ from headroom.proxy.tool_schema_compaction import _truncate_description
+
+ desc = "Read a file. Returns the contents as text."
+ result = _truncate_description(desc, 60)
+ # First sentence is short enough, second fits within 1.5x budget
+ assert "Read a file." in result
+ assert "Returns the contents as text." in result
+
+ def test_long_first_sentence_truncated(self) -> None:
+ from headroom.proxy.tool_schema_compaction import _truncate_description
+
+ desc = "This is an extremely long description that goes on and on without any sentence boundary"
+ result = _truncate_description(desc, 40)
+ assert len(result) <= 45 # 40 + "…"
+ assert result.endswith("…")
+
+ def test_whitespace_normalised_before_truncation(self) -> None:
+ from headroom.proxy.tool_schema_compaction import _truncate_description
+
+ desc = " Search code. Very useful. "
+ result = _truncate_description(desc, 60)
+ # Whitespace normalised, both sentences fit within 1.5x budget
+ assert result == "Search code. Very useful."
+
+ def test_max_chars_zero_returns_original(self) -> None:
+ from headroom.proxy.tool_schema_compaction import _truncate_description
+
+ desc = "Any long description that would normally be truncated."
+ result = _truncate_description(desc, 0)
+ # max_chars=0 means disabled, return unchanged
+ assert result == "Any long description that would normally be truncated."
+
+ def test_chinese_description(self) -> None:
+ from headroom.proxy.tool_schema_compaction import _truncate_description
+
+ desc = "搜索代码仓库中的函数和类。支持正则表达式匹配。"
+ result = _truncate_description(desc, 30)
+ # First Chinese sentence fits
+ assert "搜索代码仓库中的函数和类。" in result
+
+
+class TestCompactToolDescriptions:
+ """Unit tests for compact_tool_descriptions (full payload)."""
+
+ def test_truncates_long_tool_description(self) -> None:
+ from headroom.proxy.tool_schema_compaction import compact_tool_descriptions
+
+ payload = {
+ "tools": [
+ {
+ "name": "search_code",
+ "description": "Fast and precise code search across ALL GitHub repositories using GitHub's native search engine. Best for finding exact symbols, functions, classes, or specific code patterns. Returns ranked results.",
+ "input_schema": {"type": "object", "properties": {}},
+ },
+ ],
+ }
+ result, modified, before, after = compact_tool_descriptions(payload, max_chars=60)
+ assert modified is True
+ assert after < before
+ tool = result["tools"][0]
+ # First sentence ends at "repositories." (abbrev regex match)
+ # With max_chars=60, first sentence "Fast...repositories." is 60 chars exactly
+ # so it should be preserved. Second sentence may or may not fit in 1.5x budget.
+ assert tool["description"].startswith("Fast and precise code search")
+ assert len(tool["description"]) < len(payload["tools"][0]["description"])
+
+ def test_truncates_nested_param_descriptions(self) -> None:
+ from headroom.proxy.tool_schema_compaction import compact_tool_descriptions
+
+ payload = {
+ "tools": [
+ {
+ "name": "t",
+ "description": "Short.",
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "q": {
+ "type": "string",
+ "description": "The search query string to find matching code. Supports advanced syntax like OR, NOT, and quoted phrases for exact match.",
+ },
+ },
+ },
+ },
+ ],
+ }
+ result, modified, before, after = compact_tool_descriptions(payload, max_chars=60)
+ assert modified is True
+ param_desc = result["tools"][0]["input_schema"]["properties"]["q"]["description"]
+ assert "The search query string to find matching code." == param_desc
+
+ def test_disabled_when_max_chars_zero(self) -> None:
+ from headroom.proxy.tool_schema_compaction import compact_tool_descriptions
+
+ payload = {
+ "tools": [
+ {"name": "t", "description": "A" * 500, "input_schema": {"type": "object"}},
+ ],
+ }
+ result, modified, _, _ = compact_tool_descriptions(payload, max_chars=0)
+ assert modified is False
+ assert result is payload
+
+ def test_no_tools_returns_unchanged(self) -> None:
+ from headroom.proxy.tool_schema_compaction import compact_tool_descriptions
+
+ result, modified, _, _ = compact_tool_descriptions({"model": "x"}, max_chars=120)
+ assert modified is False
+
+ def test_preserves_non_description_fields(self) -> None:
+ from headroom.proxy.tool_schema_compaction import compact_tool_descriptions
+
+ payload = {
+ "model": "claude-sonnet-4-20250514",
+ "tools": [
+ {
+ "name": "get_weather",
+ "description": "Get the current weather for a location. Supports any city worldwide.",
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "city": {
+ "type": "string",
+ "description": "The city name to get weather for.",
+ },
+ },
+ },
+ },
+ ],
+ }
+ result, _, _, _ = compact_tool_descriptions(payload, max_chars=50)
+ assert result["model"] == "claude-sonnet-4-20250514"
+ assert result["tools"][0]["name"] == "get_weather"
+ assert result["tools"][0]["input_schema"]["properties"]["city"]["type"] == "string"
+
+ def test_large_tool_set_savings(self) -> None:
+ """44 GitHub-like tools with verbose descriptions should see significant savings."""
+ from headroom.proxy.tool_schema_compaction import compact_tool_descriptions
+
+ tools = []
+ for i in range(44):
+ tools.append(
+ {
+ "name": f"github_tool_{i}",
+ "description": f"Perform operation {i} on GitHub repositories. This tool supports advanced filtering and pagination for large result sets. Use it for code search, issue management, and PR operations.",
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "owner": {
+ "type": "string",
+ "description": "Repository owner username or organization name.",
+ },
+ "repo": {
+ "type": "string",
+ "description": "The name of the repository to operate on.",
+ },
+ },
+ },
+ }
+ )
+ payload = {"tools": tools}
+ result, modified, before, after = compact_tool_descriptions(payload, max_chars=80)
+ assert modified is True
+ savings_pct = (1 - after / before) * 100
+ assert savings_pct >= 10, f"Expected ≥10% savings, got {savings_pct:.1f}%"