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: 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.pyindex 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_toolsif cases is None:cases = self.generate_tool_schema_cases()@@ -512,9 +512,7 @@ class CompressionOnlyRunner:total_original += original_bytestry:- 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_bytescase_errors: list[str] = []diff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 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.pyindex 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 contextdiff --git a/headroom/proxy/system_compaction.py b/headroom/proxy/system_compaction.pynew file mode 100644index 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, afterdiff --git a/headroom/proxy/tool_schema_compaction.py b/headroom/proxy/tool_schema_compaction.pynew file mode 100644index 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, afterdiff --git a/tests/test_anthropic_compaction_transforms.py b/tests/test_anthropic_compaction_transforms.pynew file mode 100644index 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.pynew file mode 100644index 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() == 200diff --git a/tests/test_tool_schema_compaction.py b/tests/test_tool_schema_compaction.pynew file mode 100644index 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}%"