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
Remove hardcoded source hint system from ContentRouter
chopratejas0b3e4d25860c
diff --git a/docs/transforms.md b/docs/transforms.mdindex 1b2718701..f4fb1f490 100644--- a/docs/transforms.md+++ b/docs/transforms.md@@ -516,15 +516,14 @@ router = ContentRouter(config)### Example```python-from headroom.transforms import ContentRouter, generate_source_hint+from headroom.transforms import ContentRouterrouter = ContentRouter()-# With source hint for high-confidence routing-hint = generate_source_hint(tool_name="grep", file_path="src/auth.py")-result = router.compress(content, source_hint=hint)+# Router auto-detects content type and routes to optimal compressor+result = router.compress(content)-print(result.strategy) # CompressionStrategy.SEARCH or CODE_AWARE+print(result.strategy_used) # CompressionStrategy.CODE_AWARE, SMART_CRUSHER, etc.print(result.routing_log) # List of routing decisions```@@ -540,22 +539,17 @@ print(result.routing_log) # List of routing decisions| LLMLINGUA | Any (max compression) | LLMLinguaCompressor || PASSTHROUGH | Small content | None |-### Source Hints+### Content Detection-Use source hints for accurate routing:+The router automatically detects content types by analyzing the content itself:-```python-from headroom.transforms import generate_source_hint--# From tool invocation-hint = generate_source_hint(tool_name="Read", file_path="main.py")+- **Source code**: Detected by syntax patterns, indentation, keywords+- **JSON arrays**: Detected by JSON structure with array elements+- **Search results**: Detected by `file:line:` patterns+- **Log output**: Detected by timestamp and log level patterns+- **Plain text**: Fallback for prose content-# From file extension-hint = generate_source_hint(file_path="components/Button.tsx")--# From explicit tool-hint = generate_source_hint(tool_name="Grep") # Routes to SEARCH-```+No manual hints required - the router inspects content directly.---diff --git a/headroom/transforms/__init__.py b/headroom/transforms/__init__.pyindex 37d34df44..43ffea900 100644--- a/headroom/transforms/__init__.py+++ b/headroom/transforms/__init__.py@@ -57,7 +57,6 @@ from .content_router import (ContentRouter,ContentRouterConfig,RouterCompressionResult,- generate_source_hint,)__all__ = [@@ -101,7 +100,6 @@ __all__ = ["ContentRouterConfig","RouterCompressionResult","CompressionStrategy",- "generate_source_hint",# Other transforms"CacheAligner","RollingWindow",diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex 1bfb448cd..62e98a550 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -360,51 +360,6 @@ def _extract_json_block(lines: list[str], start: int) -> tuple[str | None, int]:return None, start-def generate_source_hint(tool_name: str, tool_input: dict[str, Any]) -> str:- """Generate a source hint from tool metadata.-- This enables higher-confidence routing decisions.-- Args:- tool_name: Name of the tool that produced the output.- tool_input: Input parameters to the tool.-- Returns:- Source hint string (e.g., "file:auth.py", "tool:grep").- """- # File read operations- if tool_name in ("Read", "read_file", "cat", "ReadFile"):- file_path = tool_input.get("file_path", tool_input.get("path", ""))- if file_path:- return f"file:{file_path}"-- # Search operations- if tool_name in ("Grep", "grep", "ripgrep", "rg", "search", "Search"):- return "tool:grep"-- # Glob operations- if tool_name in ("Glob", "glob", "find"):- return "tool:glob"-- # Build/test operations- if tool_name == "Bash":- command = str(tool_input.get("command", ""))- if any(cmd in command for cmd in ["pytest", "npm test", "cargo test", "go test"]):- return "tool:pytest"- if any(cmd in command for cmd in ["npm run build", "cargo build", "make"]):- return "tool:build"- if "git diff" in command:- return "tool:git-diff"- if "git log" in command:- return "tool:git-log"-- # Web fetch- if tool_name in ("WebFetch", "fetch", "curl", "WebSearch"):- return "tool:web"-- return ""--class ContentRouter(Transform):"""Intelligent router that selects optimal compression strategy.@@ -462,15 +417,12 @@ class ContentRouter(Transform):def compress(self,content: str,- source_hint: str | None = None,context: str = "",) -> RouterCompressionResult:- """Compress content using optimal strategy.+ """Compress content using optimal strategy based on content detection.Args:content: Content to compress.- source_hint: Optional hint about content source.- Examples: "file:auth.py", "tool:grep", "tool:pytest"context: Optional context for relevance-aware compression.Returns:@@ -484,87 +436,31 @@ class ContentRouter(Transform):routing_log=[],)- # Determine strategy- strategy = self._determine_strategy(content, source_hint)+ # Determine strategy from content analysis+ strategy = self._determine_strategy(content)if strategy == CompressionStrategy.MIXED:return self._compress_mixed(content, context)else:return self._compress_pure(content, strategy, context)- def _determine_strategy(- self,- content: str,- source_hint: str | None,- ) -> CompressionStrategy:- """Determine the compression strategy.+ def _determine_strategy(self, content: str) -> CompressionStrategy:+ """Determine the compression strategy from content analysis.Args:content: Content to analyze.- source_hint: Optional source hint.Returns:Selected compression strategy."""- # 1. Source hint takes priority- if source_hint:- strategy = self._strategy_from_hint(source_hint)- if strategy:- return strategy-- # 2. Check for mixed content+ # 1. Check for mixed contentif is_mixed_content(content):return CompressionStrategy.MIXED- # 3. Detect content type+ # 2. Detect content type from content itselfdetection = detect_content_type(content)return self._strategy_from_detection(detection)- def _strategy_from_hint(self, hint: str) -> CompressionStrategy | None:- """Get strategy from source hint.-- Args:- hint: Source hint string.-- Returns:- Strategy if determinable, None otherwise.- """- hint_lower = hint.lower()-- # File hints- if hint_lower.startswith("file:"):- file_path = hint_lower[5:]- if file_path.endswith((".py", ".pyw")):- return CompressionStrategy.CODE_AWARE- if file_path.endswith((".js", ".jsx", ".ts", ".tsx", ".mjs")):- return CompressionStrategy.CODE_AWARE- if file_path.endswith((".go", ".rs", ".java", ".c", ".cpp", ".h", ".hpp")):- return CompressionStrategy.CODE_AWARE- if file_path.endswith(".json"):- return CompressionStrategy.SMART_CRUSHER- if file_path.endswith((".md", ".txt", ".rst")):- return CompressionStrategy.TEXT- if file_path.endswith((".log", ".out")):- return CompressionStrategy.LOG-- # Tool hints- if hint_lower.startswith("tool:"):- tool = hint_lower[5:]- if tool in ("grep", "rg", "ripgrep", "ag", "search"):- return CompressionStrategy.SEARCH- if tool in ("pytest", "jest", "cargo-test", "go-test", "npm-test"):- return CompressionStrategy.LOG- if tool in ("build", "make", "cargo-build", "npm-build"):- return CompressionStrategy.LOG- if tool in ("git-diff", "diff"):- return CompressionStrategy.DIFF-- # Direct strategy hints (used by _process_content_blocks for tool_result)- if hint_lower == "json_array":- return CompressionStrategy.SMART_CRUSHER-- return None-def _strategy_from_detection(self, detection: Any) -> CompressionStrategy:"""Get strategy from content detection result.@@ -897,14 +793,13 @@ class ContentRouter(Transform):Args:messages: Messages to transform.tokenizer: Tokenizer for counting.- **kwargs: Additional arguments (context, source_hints).+ **kwargs: Additional arguments (context).Returns:TransformResult with routed and compressed messages."""tokens_before = sum(tokenizer.count_text(str(m.get("content", ""))) for m in messages)context = kwargs.get("context", "")- source_hints = kwargs.get("source_hints", {}) # message_id -> hinttransformed_messages: list[dict[str, Any]] = []transforms_applied: list[str] = []@@ -945,9 +840,6 @@ class ContentRouter(Transform):transformed_messages.append(message)continue- # Get source hint if available- source_hint = source_hints.get(i) or source_hints.get(str(i))-# Detect content type for protection decisionsdetection = detect_content_type(content)is_code = detection.content_type == ContentType.SOURCE_CODE@@ -969,8 +861,8 @@ class ContentRouter(Transform):transforms_applied.append("router:protected:analysis_context")continue- # Route and compress- result = self.compress(content, source_hint=source_hint, context=context)+ # Route and compress based on content detection+ result = self.compress(content, context=context)if result.compression_ratio < 0.9:transformed_messages.append({**message, "content": result.compressed})@@ -1013,8 +905,6 @@ class ContentRouter(Transform):Returns:Transformed message with compressed content blocks."""- import json-new_blocks = []any_compressed = False@@ -1031,33 +921,7 @@ class ContentRouter(Transform):# Only process string contentif isinstance(tool_content, str) and len(tool_content) > 500:- # Try to detect if it's JSON array data (SmartCrusher target)- try:- parsed = json.loads(tool_content)- if isinstance(parsed, list) and len(parsed) > 10:- # Route to SmartCrusher for arrays- result = self.compress(- tool_content,- source_hint="json_array",- context=context,- )- if result.compression_ratio < 0.9:- new_blocks.append(- {- **block,- "content": result.compressed,- }- )- transforms_applied.append(- f"router:tool_result:{result.strategy_used.value}"- )- any_compressed = True- continue- except (json.JSONDecodeError, TypeError):- # Not JSON, try general compression- pass-- # Try general compression for large non-JSON content+ # Compress using content detection (will auto-detect JSON arrays, etc.)result = self.compress(tool_content, context=context)if result.compression_ratio < 0.9:new_blocks.append({**block, "content": result.compressed})@@ -1140,15 +1004,13 @@ class ContentRouter(Transform):def route_and_compress(content: str,- source_hint: str | None = None,context: str = "",) -> str:"""Convenience function for one-off routing and compression.Args:content: Content to compress.- source_hint: Optional source hint.- context: Optional context.+ context: Optional context for relevance-aware compression.Returns:Compressed content.@@ -1157,5 +1019,5 @@ def route_and_compress(>>> compressed = route_and_compress(mixed_content)"""router = ContentRouter()- result = router.compress(content, source_hint=source_hint, context=context)+ result = router.compress(content, context=context)return result.compresseddiff --git a/headroom/transforms/intelligent_context.py b/headroom/transforms/intelligent_context.pyindex f86a7a8e8..0bc5a4c54 100644--- a/headroom/transforms/intelligent_context.py+++ b/headroom/transforms/intelligent_context.py@@ -444,16 +444,8 @@ class IntelligentContextManager(Transform):# Focus on tool messages (highest compression potential)if role == "tool" and isinstance(content, str) and len(content) > 100:try:- # Get source hint from tool call context- tool_call_id = msg.get("tool_call_id", "")- source_hint = self._get_tool_source_hint(messages, tool_call_id)-- # Compress using ContentRouter- result = router.compress(- content,- source_hint=source_hint,- context="", # No specific context in compress-first mode- )+ # Compress using ContentRouter (auto-detects content type)+ result = router.compress(content)# Check if compression was effectiveif result.compression_ratio < 0.9: # At least 10% savings@@ -500,46 +492,6 @@ class IntelligentContextManager(Transform):return compressed_messages, transforms_applied, total_tokens_saved- def _get_tool_source_hint(self, messages: list[dict[str, Any]], tool_call_id: str) -> str:- """Extract source hint from the tool call that produced this result.-- Args:- messages: List of all messages.- tool_call_id: The ID of the tool call to find.-- Returns:- Source hint string (e.g., "tool:grep", "file:main.py").- """- if not tool_call_id:- return ""-- # Find the assistant message with this tool call- for msg in messages:- if msg.get("role") == "assistant" and msg.get("tool_calls"):- for tc in msg.get("tool_calls", []):- if tc.get("id") == tool_call_id:- func = tc.get("function", {})- tool_name = func.get("name", "")-- # Import here to avoid circular imports- try:- import json-- from .content_router import generate_source_hint-- args_str = func.get("arguments", "{}")- try:- args = (- json.loads(args_str) if isinstance(args_str, str) else args_str- )- except json.JSONDecodeError:- args = {}-- return generate_source_hint(tool_name, args)- except ImportError:- return f"tool:{tool_name}" if tool_name else ""- return ""-def _compress_content_blocks(self,content_blocks: list[Any],diff --git a/tests/test_transforms/test_content_router.py b/tests/test_transforms/test_content_router.pyindex c90f55da7..7038fd5b5 100644--- a/tests/test_transforms/test_content_router.py+++ b/tests/test_transforms/test_content_router.py@@ -4,7 +4,6 @@ Comprehensive tests covering:- ContentRouterConfig: Configuration validation and defaults- ContentRouter: Core routing functionality- Strategy detection: Code, JSON, search, logs, text-- Source hint parsing: File paths, tool names- Mixed content handling: Split, route, reassemble- Transform interface: apply(), should_apply() methods"""@@ -18,7 +17,6 @@ from headroom.transforms.content_router import (ContentRouterConfig,RouterCompressionResult,RoutingDecision,- generate_source_hint,)# =============================================================================@@ -279,51 +277,6 @@ class TestRouterCompressionResult:assert result.savings_percentage == 0.0-# =============================================================================-# TestSourceHintGeneration-# =============================================================================---class TestSourceHintGeneration:- """Tests for generate_source_hint function."""-- def test_file_path_hint_with_file_path(self):- """File path generates file: hint."""- hint = generate_source_hint("Read", {"file_path": "/src/auth.py"})- assert hint == "file:/src/auth.py"-- def test_file_path_hint_with_path(self):- """File path with 'path' key also works."""- hint = generate_source_hint("read_file", {"path": "/src/auth.py"})- assert hint == "file:/src/auth.py"-- def test_grep_tool_hint(self):- """Grep tool generates tool:grep hint."""- hint = generate_source_hint("Grep", {"pattern": "def.*"})- assert hint == "tool:grep"-- def test_glob_tool_hint(self):- """Glob tool generates tool:glob hint."""- hint = generate_source_hint("Glob", {"pattern": "*.py"})- assert hint == "tool:glob"-- def test_bash_test_command(self):- """Bash with test command generates tool:pytest hint."""- hint = generate_source_hint("Bash", {"command": "pytest tests/"})- assert hint == "tool:pytest"-- def test_bash_build_command(self):- """Bash with build command generates tool:build hint."""- hint = generate_source_hint("Bash", {"command": "npm run build"})- assert "tool:" in hint-- def test_unknown_tool(self):- """Unknown tool returns generic tool hint."""- hint = generate_source_hint("CustomTool", {"arg": "value"})- # Should return some hint, not crash- assert hint is not None--# =============================================================================# TestStrategyDetection# =============================================================================@@ -335,54 +288,32 @@ class TestStrategyDetection:def test_detect_python_code(self, router):"""Python code is detected."""code = generate_python_code(5)- strategy = router._determine_strategy(code, None)+ strategy = router._determine_strategy(code)# Should be either CODE_AWARE or fallbackassert strategy in CompressionStrategydef test_detect_json_content(self, router):"""JSON content is detected."""json_data = generate_json_data(20)- strategy = router._determine_strategy(json_data, None)+ strategy = router._determine_strategy(json_data)assert strategy in CompressionStrategydef test_detect_search_results(self, router):"""Search/grep results are detected."""search_results = generate_search_results(10)- strategy = router._determine_strategy(search_results, None)+ strategy = router._determine_strategy(search_results)assert strategy in CompressionStrategydef test_detect_log_output(self, router):"""Build/test logs are detected."""logs = generate_log_output(30)- strategy = router._determine_strategy(logs, None)+ strategy = router._determine_strategy(logs)assert strategy in CompressionStrategydef test_detect_plain_text(self, router):"""Plain text detection."""text = "This is just plain text without any special formatting."- strategy = router._determine_strategy(text, None)- assert strategy in CompressionStrategy---# =============================================================================-# TestSourceHintRouting-# =============================================================================---class TestSourceHintRouting:- """Tests for source hint-based routing."""-- def test_file_hint_routes_appropriately(self, router):- """file:*.py hint influences routing."""- content = generate_python_code(3)- strategy = router._determine_strategy(content, "file:/src/auth.py")- # Should return a valid strategy- assert strategy in CompressionStrategy-- def test_grep_hint_routes_appropriately(self, router):- """tool:grep hint influences routing."""- content = generate_search_results(5)- strategy = router._determine_strategy(content, "tool:grep")+ strategy = router._determine_strategy(text)assert strategy in CompressionStrategy@@ -430,14 +361,6 @@ class TestContentRouter:assert result.original == contentassert result.strategy_used is not None- def test_compress_with_source_hint(self, router):- """Source hint influences routing decision."""- content = generate_python_code(5)- result = router.compress(content, source_hint="file:/src/auth.py")-- # Should return a valid result- assert isinstance(result, RouterCompressionResult)-def test_name_property(self, router):"""Router has correct name."""assert router.name == "content_router"@@ -515,7 +438,7 @@ class TestCompressorDisabling:code = generate_python_code(10)# Should not crash- result = router.compress(code, source_hint="file:/src/auth.py")+ result = router.compress(code)assert result is not Nonedef test_config_accepts_disable_search_compression(self):@@ -528,7 +451,7 @@ class TestCompressorDisabling:search_results = generate_search_results(10)# Should not crash- result = router.compress(search_results, source_hint="tool:grep")+ result = router.compress(search_results)assert result is not Nonedef test_config_accepts_disable_log_compression(self):@@ -541,7 +464,7 @@ class TestCompressorDisabling:logs = generate_log_output(30)# Should not crash- result = router.compress(logs, source_hint="tool:pytest")+ result = router.compress(logs)assert result is not None@@ -570,18 +493,6 @@ class TestEdgeCases:result = router.compress(content)assert result is not None- def test_null_source_hint(self, router):- """Null source hint doesn't crash."""- content = generate_python_code(5)- result = router.compress(content, source_hint=None)- assert result is not None-- def test_empty_source_hint(self, router):- """Empty source hint doesn't crash."""- content = generate_python_code(5)- result = router.compress(content, source_hint="")- assert result is not None-# =============================================================================# TestRoutingLogdiff --git a/tests/test_transforms/test_intelligent_context.py b/tests/test_transforms/test_intelligent_context.pyindex bcf87d944..fa06a17f7 100644--- a/tests/test_transforms/test_intelligent_context.py+++ b/tests/test_transforms/test_intelligent_context.py@@ -1017,49 +1017,6 @@ class TestCompressFirstStrategy:router2 = manager._get_content_router()assert router is router2- def test_source_hint_extraction(self):- """Source hints should be extracted from tool calls."""- manager = IntelligentContextManager()-- messages = [- {- "role": "assistant",- "tool_calls": [- {- "id": "call_1",- "function": {- "name": "Read",- "arguments": '{"file_path": "/src/main.py"}',- },- }- ],- },- {- "role": "assistant",- "tool_calls": [- {- "id": "call_2",- "function": {- "name": "Grep",- "arguments": '{"pattern": "def"}',- },- }- ],- },- ]-- # Test file read hint- hint1 = manager._get_tool_source_hint(messages, "call_1")- assert "file:" in hint1 or hint1 == "" # May not have content_router import-- # Test grep hint- hint2 = manager._get_tool_source_hint(messages, "call_2")- assert "grep" in hint2.lower() or hint2 == ""-- # Test unknown tool call- hint3 = manager._get_tool_source_hint(messages, "unknown")- assert hint3 == ""-class TestCompressFirstWithContentBlocks:"""Tests for COMPRESS_FIRST with Anthropic-style content blocks."""