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.

Integrate DynamicContentDetector into CacheAligner (Phase 1)

chopratejas2ce26438a043
diff --git a/headroom/config.py b/headroom/config.py
index 838fd54b9..838b65030 100644
--- a/headroom/config.py
+++ b/headroom/config.py
@@ -49,6 +49,20 @@ class ToolCrusherConfig:
class CacheAlignerConfig:
"""Configuration for cache alignment.
+ Phase 1 Enhancement: Now integrates DynamicContentDetector for comprehensive
+ dynamic content detection beyond just dates.
+
+ New Detection Capabilities (when use_dynamic_detector=True):
+ - UUIDs: 550e8400-e29b-41d4-a716-446655440000
+ - API keys/tokens: sk-abc123..., api_key_xyz...
+ - JWT tokens: eyJhbGciOiJIUzI1NiIs...
+ - Unix timestamps: 1705312847
+ - Request/trace IDs: req_abc123, trace_xyz789
+ - Hex hashes: MD5 (32 chars), SHA1 (40 chars), SHA256 (64 chars)
+ - Version numbers: v1.2.3, v2.0.0-beta
+ - Structural patterns: "Session: abc123", "User: [email protected]"
+ - High-entropy strings: Random-looking alphanumeric sequences
+
GOTCHAS:
- Date regex may match non-date content (e.g., version numbers like "2024-01-15")
- Moving dates to end of system prompt may confuse models if date was
@@ -63,6 +77,31 @@ class CacheAlignerConfig:
"""
enabled: bool = True
+
+ # === Phase 1: DynamicContentDetector Integration ===
+ # When True, uses the full DynamicContentDetector with 15+ patterns
+ # When False, uses legacy date_patterns only (backward compatible)
+ use_dynamic_detector: bool = True
+
+ # Which detection tiers to use (only when use_dynamic_detector=True)
+ # - "regex": Fast structural/universal patterns (~0ms) - RECOMMENDED
+ # - "ner": Named Entity Recognition via spaCy (~5-10ms) - optional
+ # - "semantic": Embedding similarity (~20-50ms) - optional
+ detection_tiers: list[Literal["regex", "ner", "semantic"]] = field(
+ default_factory=lambda: ["regex"]
+ )
+
+ # Additional dynamic labels to detect (extends default list)
+ # These are KEY names that hint the VALUE is dynamic
+ # e.g., "session" will detect "session: abc123" and extract "abc123"
+ extra_dynamic_labels: list[str] = field(default_factory=list)
+
+ # Entropy threshold for detecting random strings (0-1 scale)
+ # Higher = more selective (only very random strings like UUIDs)
+ # Lower = more aggressive (may catch non-random content)
+ entropy_threshold: float = 0.7
+
+ # === Legacy Configuration (used when use_dynamic_detector=False) ===
date_patterns: list[str] = field(
default_factory=lambda: [
r"Current [Dd]ate:?\s*\d{4}-\d{2}-\d{2}",
@@ -71,8 +110,11 @@ class CacheAlignerConfig:
r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}",
]
)
+
+ # === Whitespace Normalization ===
normalize_whitespace: bool = True
collapse_blank_lines: bool = True
+
# Separator used to mark where dynamic content begins in system message
# Content before this separator is cached; content after is dynamic
dynamic_tail_separator: str = "\n\n---\n[Dynamic Context]\n"
diff --git a/headroom/transforms/cache_aligner.py b/headroom/transforms/cache_aligner.py
index 3d640b90e..5b1e91051 100644
--- a/headroom/transforms/cache_aligner.py
+++ b/headroom/transforms/cache_aligner.py
@@ -1,4 +1,15 @@
-"""Cache alignment transform for Headroom SDK."""
+"""Cache alignment transform for Headroom SDK.
+
+Phase 1 Enhancement: Integrates DynamicContentDetector for comprehensive
+dynamic content detection beyond just dates.
+
+Detection capabilities include:
+- UUIDs, API keys, JWT tokens
+- Unix timestamps, request/trace IDs
+- Hex hashes (MD5, SHA1, SHA256)
+- Version numbers, structural patterns
+- High-entropy strings (random-looking IDs)
+"""
from __future__ import annotations
@@ -6,6 +17,10 @@ import logging
import re
from typing import Any
+from ..cache.dynamic_detector import (
+ DetectorConfig,
+ DynamicContentDetector,
+)
from ..config import CacheAlignerConfig, CachePrefixMetrics, TransformResult
from ..tokenizer import Tokenizer
from ..tokenizers import EstimatingTokenCounter
@@ -20,12 +35,20 @@ class CacheAligner(Transform):
Align messages for optimal cache hits.
This transform:
- 1. Extracts dynamic content (dates) from system prompt
+ 1. Extracts dynamic content from system prompt (dates, UUIDs, tokens, etc.)
2. Normalizes whitespace for consistent hashing
3. Computes a stable prefix hash
The goal is to make the prefix byte-identical across requests
so that LLM provider caching can be effective.
+
+ Phase 1 Enhancement: Now uses DynamicContentDetector for comprehensive
+ detection of 15+ dynamic content patterns including:
+ - UUIDs, API keys, JWT tokens
+ - Unix timestamps, request/trace IDs
+ - Hex hashes (MD5, SHA1, SHA256)
+ - Version numbers, structural patterns
+ - High-entropy strings
"""
name = "cache_aligner"
@@ -38,13 +61,45 @@ class CacheAligner(Transform):
config: Configuration for alignment behavior.
"""
self.config = config or CacheAlignerConfig()
+
+ # Initialize dynamic content detector if enabled
+ self._dynamic_detector: DynamicContentDetector | None = None
+ if self.config.use_dynamic_detector:
+ self._init_dynamic_detector()
+
+ # Legacy: compiled regex patterns (used when use_dynamic_detector=False)
self._compiled_patterns: list[re.Pattern[str]] = []
- self._compile_patterns()
+ if not self.config.use_dynamic_detector:
+ self._compile_patterns()
+
# Track previous hash for cache hit detection
self._previous_prefix_hash: str | None = None
+ def _init_dynamic_detector(self) -> None:
+ """Initialize the DynamicContentDetector with configured tiers."""
+ # Build detector config
+ detector_config = DetectorConfig(
+ tiers=list(self.config.detection_tiers),
+ entropy_threshold=self.config.entropy_threshold,
+ )
+
+ # Add extra dynamic labels if configured
+ if self.config.extra_dynamic_labels:
+ detector_config.dynamic_labels = (
+ detector_config.dynamic_labels + self.config.extra_dynamic_labels
+ )
+
+ self._dynamic_detector = DynamicContentDetector(detector_config)
+
+ # Log available tiers
+ available = self._dynamic_detector.available_tiers
+ logger.info(
+ "CacheAligner: DynamicContentDetector initialized with tiers: %s",
+ available,
+ )
+
def _compile_patterns(self) -> None:
- """Compile regex patterns for efficiency."""
+ """Compile regex patterns for efficiency (legacy mode)."""
self._compiled_patterns = [re.compile(pattern) for pattern in self.config.date_patterns]
def should_apply(
@@ -57,17 +112,29 @@ class CacheAligner(Transform):
if not self.config.enabled:
return False
- # Check if system prompt contains dynamic patterns
+ # Check if system prompt contains dynamic content
for msg in messages:
if msg.get("role") == "system":
content = msg.get("content", "")
if isinstance(content, str):
- for pattern in self._compiled_patterns:
- if pattern.search(content):
- return True
+ if self._has_dynamic_content(content):
+ return True
return False
+ def _has_dynamic_content(self, content: str) -> bool:
+ """Check if content has any dynamic patterns."""
+ if self.config.use_dynamic_detector and self._dynamic_detector:
+ # Use DynamicContentDetector for comprehensive detection
+ result = self._dynamic_detector.detect(content)
+ return len(result.spans) > 0
+ else:
+ # Legacy: use compiled date patterns only
+ for pattern in self._compiled_patterns:
+ if pattern.search(content):
+ return True
+ return False
+
def apply(
self,
messages: list[dict[str, Any]],
@@ -90,19 +157,23 @@ class CacheAligner(Transform):
transforms_applied: list[str] = []
warnings: list[str] = []
- extracted_dates: list[str] = []
+ extracted_dynamic: list[str] = []
+ detection_stats: dict[str, int] = {} # Track what was detected
# Process system messages
for msg in result_messages:
if msg.get("role") == "system":
content = msg.get("content", "")
if isinstance(content, str):
- # Extract and remove date patterns
- new_content, dates = self._extract_dates(content)
+ # Extract dynamic content (dates, UUIDs, tokens, etc.)
+ new_content, extracted, stats = self._extract_dynamic_content(content)
- if dates:
- extracted_dates.extend(dates)
+ if extracted:
+ extracted_dynamic.extend(extracted)
msg["content"] = new_content
+ # Accumulate detection stats
+ for category, count in stats.items():
+ detection_stats[category] = detection_stats.get(category, 0) + count
# Normalize whitespace if configured
if self.config.normalize_whitespace:
@@ -135,16 +206,28 @@ class CacheAligner(Transform):
previous_hash=previous_hash,
)
- # If we extracted dates, add them as dynamic context
- if extracted_dates:
- # Insert dates as a small user message or append to context
+ # If we extracted dynamic content, add it as dynamic context
+ if extracted_dynamic:
+ # Insert dynamic content as a context note after system messages
# Strategy: add as a context note after system messages
- self._reinsert_dates(result_messages, extracted_dates)
+ self._reinsert_dynamic_content(result_messages, extracted_dynamic)
transforms_applied.append("cache_align")
- logger.debug(
- "CacheAligner: extracted %d date patterns for cache alignment",
- len(extracted_dates),
- )
+
+ # Log what was detected
+ if detection_stats:
+ stats_str = ", ".join(
+ f"{cat}={cnt}" for cat, cnt in sorted(detection_stats.items())
+ )
+ logger.info(
+ "CacheAligner: extracted %d dynamic patterns (%s)",
+ len(extracted_dynamic),
+ stats_str,
+ )
+ else:
+ logger.debug(
+ "CacheAligner: extracted %d dynamic patterns for cache alignment",
+ len(extracted_dynamic),
+ )
# Log cache hit/miss
if prefix_changed:
@@ -172,9 +255,64 @@ class CacheAligner(Transform):
return result
- def _extract_dates(self, content: str) -> tuple[str, list[str]]:
+ def _extract_dynamic_content(self, content: str) -> tuple[str, list[str], dict[str, int]]:
"""
- Extract date patterns from content.
+ Extract dynamic content from text.
+
+ Uses DynamicContentDetector when enabled, otherwise falls back
+ to legacy date pattern matching.
+
+ Returns:
+ Tuple of (content_without_dynamic, list_of_extracted, category_counts).
+ """
+ if self.config.use_dynamic_detector and self._dynamic_detector:
+ return self._extract_with_detector(content)
+ else:
+ # Legacy mode: extract dates only
+ result, extracted = self._extract_dates_legacy(content)
+ stats = {"date": len(extracted)} if extracted else {}
+ return result, extracted, stats
+
+ def _extract_with_detector(self, content: str) -> tuple[str, list[str], dict[str, int]]:
+ """
+ Extract dynamic content using DynamicContentDetector.
+
+ Returns:
+ Tuple of (static_content, extracted_values, category_counts).
+ """
+ if not self._dynamic_detector:
+ return content, [], {}
+
+ result = self._dynamic_detector.detect(content)
+
+ if not result.spans:
+ return content, [], {}
+
+ # Count by category
+ category_counts: dict[str, int] = {}
+ extracted: list[str] = []
+
+ for span in result.spans:
+ category = span.category.value
+ category_counts[category] = category_counts.get(category, 0) + 1
+ extracted.append(span.text)
+
+ # Use the static content from the detector
+ static_content = self._cleanup_empty_lines(result.static_content)
+
+ # Log detection details at debug level
+ logger.debug(
+ "DynamicContentDetector found %d spans in %.2fms: %s",
+ len(result.spans),
+ result.processing_time_ms,
+ category_counts,
+ )
+
+ return static_content, extracted, category_counts
+
+ def _extract_dates_legacy(self, content: str) -> tuple[str, list[str]]:
+ """
+ Extract date patterns from content (legacy mode).
Returns:
Tuple of (content_without_dates, list_of_extracted_dates).
@@ -193,6 +331,19 @@ class CacheAligner(Transform):
return result, extracted
+ def _extract_dates(self, content: str) -> tuple[str, list[str]]:
+ """
+ Extract date patterns from content.
+
+ DEPRECATED: Use _extract_dynamic_content instead.
+ Kept for backward compatibility.
+
+ Returns:
+ Tuple of (content_without_dates, list_of_extracted_dates).
+ """
+ result, extracted, _ = self._extract_dynamic_content(content)
+ return result, extracted
+
def _normalize_whitespace(self, content: str) -> str:
"""Normalize whitespace for consistent hashing."""
# Normalize line endings
@@ -234,13 +385,13 @@ class CacheAligner(Transform):
return "\n".join(new_lines).strip()
- def _reinsert_dates(
+ def _reinsert_dynamic_content(
self,
messages: list[dict[str, Any]],
- dates: list[str],
+ dynamic_values: list[str],
) -> None:
"""
- Reinsert extracted dates as dynamic context.
+ Reinsert extracted dynamic content as dynamic context.
Strategy: Append to the end of system message with a clear separator.
The separator marks where static (cacheable) content ends and
@@ -249,22 +400,40 @@ class CacheAligner(Transform):
Note: The stable prefix hash is computed BEFORE this method is called,
so the hash is based on static content only.
"""
- if not dates:
+ if not dynamic_values:
return
- # Format dates as a simple note
- date_note = ", ".join(dates)
+ # Format dynamic content as a note
+ # Use newlines for multiple items to improve readability
+ if len(dynamic_values) <= 3:
+ dynamic_note = ", ".join(dynamic_values)
+ else:
+ dynamic_note = "\n".join(f"- {v}" for v in dynamic_values)
+
separator = self.config.dynamic_tail_separator
- # Find last system message and append dates
+ # Find last system message and append dynamic content
for msg in reversed(messages):
if msg.get("role") == "system":
content = msg.get("content", "")
if isinstance(content, str):
# Use separator to clearly mark dynamic content
- msg["content"] = content.strip() + separator + date_note
+ msg["content"] = content.strip() + separator + dynamic_note
break
+ def _reinsert_dates(
+ self,
+ messages: list[dict[str, Any]],
+ dates: list[str],
+ ) -> None:
+ """
+ Reinsert extracted dates as dynamic context.
+
+ DEPRECATED: Use _reinsert_dynamic_content instead.
+ Kept for backward compatibility.
+ """
+ self._reinsert_dynamic_content(messages, dates)
+
def _get_stable_prefix_content(self, messages: list[dict[str, Any]]) -> str:
"""Get the stable prefix content (static portion of system messages).
@@ -304,6 +473,7 @@ class CacheAligner(Transform):
Compute cache alignment score (0-100).
Higher score means better cache alignment potential.
+ Uses DynamicContentDetector when enabled for comprehensive detection.
"""
score = 100.0
@@ -312,9 +482,15 @@ class CacheAligner(Transform):
content = msg.get("content", "")
if isinstance(content, str):
# Penalize for each dynamic pattern found
- for pattern in self._compiled_patterns:
- matches = pattern.findall(content)
- score -= len(matches) * 10
+ if self.config.use_dynamic_detector and self._dynamic_detector:
+ # Use comprehensive detector
+ result = self._dynamic_detector.detect(content)
+ score -= len(result.spans) * 10
+ else:
+ # Legacy: use compiled date patterns
+ for pattern in self._compiled_patterns:
+ matches = pattern.findall(content)
+ score -= len(matches) * 10
# Penalize for inconsistent whitespace
if "\r" in content:
diff --git a/tests/test_transforms/test_cache_aligner.py b/tests/test_transforms/test_cache_aligner.py
index bed03acff..5513f4fea 100644
--- a/tests/test_transforms/test_cache_aligner.py
+++ b/tests/test_transforms/test_cache_aligner.py
@@ -775,3 +775,466 @@ Please be helpful, harmless, and honest."""
# apply should work but not modify anything
result = aligner.apply(messages, tokenizer)
assert "cache_align" not in result.transforms_applied
+
+
+# ============================================================================
+# Phase 1: DynamicContentDetector Integration Tests
+# ============================================================================
+
+
+class TestDynamicContentDetectorIntegration:
+ """Tests for Phase 1: DynamicContentDetector integration."""
+
+ def test_uuid_detection(self, tokenizer):
+ """Test extraction of UUID patterns."""
+ system_prompt = (
+ "You are a helpful assistant.\n"
+ "Session ID: 550e8400-e29b-41d4-a716-446655440000\n"
+ "Please help the user."
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+ assert "cache_align" in result.transforms_applied
+ # UUID should be in dynamic section
+ dynamic_section = system_content.split("[Dynamic Context]")[1]
+ assert "550e8400-e29b-41d4-a716-446655440000" in dynamic_section
+
+ def test_api_key_detection(self, tokenizer):
+ """Test extraction of API key patterns."""
+ system_prompt = (
+ "You are an assistant with API access.\n"
+ "API Key: sk-abc123def456ghi789jkl012mno345pqr678\n"
+ "Use this to make requests."
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+ # API key should be extracted
+ assert "cache_align" in result.transforms_applied
+
+ def test_jwt_token_detection(self, tokenizer):
+ """Test extraction of JWT token patterns."""
+ jwt_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
+ system_prompt = f"You are an assistant.\nAuth Token: {jwt_token}\nHelp the user."
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+ assert "cache_align" in result.transforms_applied
+
+ def test_unix_timestamp_detection(self, tokenizer):
+ """Test extraction of Unix timestamp patterns."""
+ system_prompt = (
+ "You are a logging assistant.\nRequest started at: 1705312200000\nHelp analyze logs."
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+
+ def test_request_trace_id_detection(self, tokenizer):
+ """Test extraction of request/trace ID patterns."""
+ system_prompt = (
+ "You are a debugging assistant.\n"
+ "Trace ID: req_abc123def456\n"
+ "Request ID: tx_987654321abc\n"
+ "Help debug issues."
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+ assert "cache_align" in result.transforms_applied
+
+ def test_hex_hash_md5_detection(self, tokenizer):
+ """Test extraction of MD5 hash patterns (32 hex chars)."""
+ system_prompt = (
+ "You are a file assistant.\n"
+ "File hash: d41d8cd98f00b204e9800998ecf8427e\n"
+ "Help with file operations."
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+ dynamic_section = system_content.split("[Dynamic Context]")[1]
+ assert "d41d8cd98f00b204e9800998ecf8427e" in dynamic_section
+
+ def test_hex_hash_sha1_detection(self, tokenizer):
+ """Test extraction of SHA1 hash patterns (40 hex chars)."""
+ system_prompt = (
+ "You are a git assistant.\n"
+ "Commit: da39a3ee5e6b4b0d3255bfef95601890afd80709\n"
+ "Help with git operations."
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+ dynamic_section = system_content.split("[Dynamic Context]")[1]
+ assert "da39a3ee5e6b4b0d3255bfef95601890afd80709" in dynamic_section
+
+ def test_hex_hash_sha256_detection(self, tokenizer):
+ """Test extraction of SHA256 hash patterns (64 hex chars)."""
+ sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ system_prompt = f"You are a security assistant.\nHash: {sha256}\nHelp verify files."
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+ dynamic_section = system_content.split("[Dynamic Context]")[1]
+ assert sha256 in dynamic_section
+
+ def test_version_number_detection(self, tokenizer):
+ """Test extraction of version number patterns."""
+ system_prompt = (
+ "You are a deployment assistant.\n"
+ "Current version: v2.15.3\n"
+ "Previous version: 1.14.2\n"
+ "Help with deployments."
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+ assert "cache_align" in result.transforms_applied
+
+ def test_combined_dynamic_content(self, tokenizer):
+ """Test extraction of multiple dynamic content types together."""
+ system_prompt = (
+ "You are a comprehensive assistant.\n"
+ "Session: 550e8400-e29b-41d4-a716-446655440000\n"
+ "Current date: 2024-01-15\n"
+ "Request ID: req_abc123def456\n"
+ "Version: v3.2.1\n"
+ "Commit: da39a3ee5e6b4b0d3255bfef95601890afd80709\n"
+ "Help the user with their tasks."
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+ assert "cache_align" in result.transforms_applied
+
+ # Multiple dynamic values should be present in dynamic section
+ dynamic_section = system_content.split("[Dynamic Context]")[1]
+ # At least some of these should be in the dynamic section
+ dynamic_items_found = sum(
+ [
+ "550e8400" in dynamic_section,
+ "2024-01-15" in dynamic_section,
+ "da39a3ee" in dynamic_section,
+ ]
+ )
+ assert dynamic_items_found >= 2, "Expected multiple dynamic items in dynamic section"
+
+ def test_detection_stats_tracking(self, tokenizer):
+ """Test that detection statistics are properly tracked."""
+ system_prompt = (
+ "Assistant.\n"
+ "UUID: 550e8400-e29b-41d4-a716-446655440000\n"
+ "Current date: 2024-01-15T10:30:00\n"
+ "Hash: d41d8cd98f00b204e9800998ecf8427e\n"
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ # Cache metrics should show detection occurred
+ assert result.cache_metrics is not None
+ assert result.cache_metrics.stable_prefix_hash
+ assert "cache_align" in result.transforms_applied
+
+ def test_stable_hash_with_dynamic_detector(self, tokenizer):
+ """Test that hash remains stable when only dynamic content changes."""
+ # Same static content, different dynamic content
+ messages_v1 = [
+ {
+ "role": "system",
+ "content": "You are helpful.\nSession: 550e8400-e29b-41d4-a716-446655440000",
+ },
+ {"role": "user", "content": "Hello"},
+ ]
+ messages_v2 = [
+ {
+ "role": "system",
+ "content": "You are helpful.\nSession: 661f9511-f30c-52e5-b827-557766551111",
+ },
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner1 = CacheAligner(config)
+ aligner2 = CacheAligner(config)
+
+ result1 = aligner1.apply(messages_v1, tokenizer)
+ result2 = aligner2.apply(messages_v2, tokenizer)
+
+ # Hashes should be identical - only the UUID changed
+ assert result1.cache_metrics.stable_prefix_hash == result2.cache_metrics.stable_prefix_hash
+
+
+class TestLegacyModeBackwardCompatibility:
+ """Tests for backward compatibility with legacy date-only mode."""
+
+ def test_legacy_mode_only_detects_dates(self, tokenizer):
+ """Test that legacy mode only extracts date patterns."""
+ system_prompt = (
+ "You are an assistant.\n"
+ "Current date: 2024-01-15\n"
+ "Session: 550e8400-e29b-41d4-a716-446655440000\n"
+ "Help users."
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ # Legacy mode - should only detect dates
+ config = CacheAlignerConfig(use_dynamic_detector=False)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+
+ # In legacy mode, UUID should NOT be in dynamic section (still in static)
+ # Split by separator to get static and dynamic parts
+ parts = system_content.split("---")
+ if len(parts) > 1:
+ static_part = parts[0]
+ # UUID should still be in static part in legacy mode
+ assert "550e8400-e29b-41d4-a716-446655440000" in static_part
+
+ def test_legacy_mode_uses_configured_patterns(self, tokenizer):
+ """Test that legacy mode uses configured date_patterns."""
+ custom_patterns = [r"Build #\d+", r"Release \d+\.\d+"]
+ system_prompt = "Assistant.\nBuild #123\nRelease 2.5\nHelp users."
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=False, date_patterns=custom_patterns)
+ aligner = CacheAligner(config)
+ result = aligner.apply(messages, tokenizer)
+
+ system_content = result.messages[0]["content"]
+ assert "[Dynamic Context]" in system_content
+ assert "cache_align" in result.transforms_applied
+
+ def test_default_config_uses_dynamic_detector(self, tokenizer):
+ """Test that default config enables dynamic detector."""
+ config = CacheAlignerConfig()
+ assert config.use_dynamic_detector is True
+
+ aligner = CacheAligner(config)
+ assert aligner._dynamic_detector is not None
+
+
+class TestDynamicDetectorConfiguration:
+ """Tests for DynamicContentDetector configuration options."""
+
+ def test_detection_tiers_default(self, tokenizer):
+ """Test that default detection tier is regex only."""
+ config = CacheAlignerConfig()
+ assert config.detection_tiers == ["regex"]
+
+ def test_detection_tiers_configurable(self, tokenizer):
+ """Test that detection tiers can be configured."""
+ config = CacheAlignerConfig(detection_tiers=["regex", "ner"])
+ assert "regex" in config.detection_tiers
+ assert "ner" in config.detection_tiers
+
+ def test_extra_dynamic_labels_empty_by_default(self, tokenizer):
+ """Test that extra_dynamic_labels is empty by default."""
+ config = CacheAlignerConfig()
+ assert config.extra_dynamic_labels == []
+
+ def test_entropy_threshold_default(self, tokenizer):
+ """Test that entropy threshold has correct default."""
+ config = CacheAlignerConfig()
+ assert config.entropy_threshold == 0.7
+
+ def test_entropy_threshold_configurable(self, tokenizer):
+ """Test that entropy threshold can be configured."""
+ config = CacheAlignerConfig(entropy_threshold=0.8)
+ assert config.entropy_threshold == 0.8
+
+
+class TestAlignmentScoreWithDynamicDetector:
+ """Tests for alignment score with dynamic detector enabled."""
+
+ def test_alignment_score_penalizes_uuids(self, tokenizer):
+ """Test alignment score decreases with UUID patterns."""
+ messages_no_uuid = [
+ {"role": "system", "content": "You are a helpful assistant."},
+ {"role": "user", "content": "Hello"},
+ ]
+ messages_with_uuid = [
+ {
+ "role": "system",
+ "content": "You are a helpful assistant.\nSession: 550e8400-e29b-41d4-a716-446655440000",
+ },
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+
+ score_no_uuid = aligner.get_alignment_score(messages_no_uuid)
+ score_with_uuid = aligner.get_alignment_score(messages_with_uuid)
+
+ assert score_with_uuid < score_no_uuid
+
+ def test_alignment_score_penalizes_multiple_dynamic_patterns(self, tokenizer):
+ """Test alignment score decreases significantly with many dynamic patterns."""
+ system_prompt = (
+ "Assistant.\n"
+ "Session: 550e8400-e29b-41d4-a716-446655440000\n"
+ "Request: req_abc123def456\n"
+ "Date: 2024-01-15T10:30:00\n"
+ "Hash: d41d8cd98f00b204e9800998ecf8427e\n"
+ "Version: v2.5.1\n"
+ )
+ messages = [
+ {"role": "system", "content": system_prompt},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligner = CacheAligner(config)
+
+ score = aligner.get_alignment_score(messages)
+
+ # Many dynamic patterns should significantly reduce score
+ assert score < 60.0 # 5+ patterns at 10 points each = at least 50 point reduction
+
+
+class TestConvenienceFunction:
+ """Tests for align_for_cache convenience function."""
+
+ def test_align_for_cache_basic(self):
+ """Test align_for_cache convenience function."""
+ from headroom.transforms.cache_aligner import align_for_cache
+
+ messages = [
+ {"role": "system", "content": "Assistant. Current date: 2024-01-15"},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ aligned_messages, stable_hash = align_for_cache(messages)
+
+ assert "[Dynamic Context]" in aligned_messages[0]["content"]
+ assert len(stable_hash) == 16
+
+ def test_align_for_cache_with_config(self):
+ """Test align_for_cache with custom config."""
+ from headroom.transforms.cache_aligner import align_for_cache
+
+ messages = [
+ {
+ "role": "system",
+ "content": "Assistant. Session: 550e8400-e29b-41d4-a716-446655440000",
+ },
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=True)
+ aligned_messages, stable_hash = align_for_cache(messages, config)
+
+ assert "[Dynamic Context]" in aligned_messages[0]["content"]
+ assert len(stable_hash) == 16
+
+ def test_align_for_cache_legacy_mode(self):
+ """Test align_for_cache with legacy mode."""
+ from headroom.transforms.cache_aligner import align_for_cache
+
+ messages = [
+ {"role": "system", "content": "Assistant. Current date: 2024-01-15"},
+ {"role": "user", "content": "Hello"},
+ ]
+
+ config = CacheAlignerConfig(use_dynamic_detector=False)
+ aligned_messages, stable_hash = align_for_cache(messages, config)
+
+ assert "[Dynamic Context]" in aligned_messages[0]["content"]
+ assert len(stable_hash) == 16
diff --git a/tests/test_transforms/test_code_compressor.py b/tests/test_transforms/test_code_compressor.py
index e485f9398..7a9dd0302 100644
--- a/tests/test_transforms/test_code_compressor.py
+++ b/tests/test_transforms/test_code_compressor.py
@@ -503,19 +503,32 @@ class TestFallbackCompression:
assert result.syntax_valid is True # Fallback guarantees validity
def test_fallback_preserves_structure(self, default_config):
- """Fallback compression preserves basic structure."""
- with patch(
- "headroom.transforms.code_compressor._check_tree_sitter_available",
- return_value=False,
+ """Fallback compression preserves basic structure when no compressor available.
+
+ When both tree-sitter and LLMLingua are unavailable, the fallback
+ returns the original code unchanged - preserving all structure.
+ """
+ with (
+ patch(
+ "headroom.transforms.code_compressor._check_tree_sitter_available",
+ return_value=False,
+ ),
+ patch(
+ "headroom.transforms.llmlingua_compressor._check_llmlingua_available",
+ return_value=False,
+ ),
):
compressor = CodeAwareCompressor(default_config)
code = generate_python_code(3)
result = compressor.compress(code)
- # Should preserve imports and class/function signatures
+ # With no compressor available, original code is returned unchanged
+ # This preserves all imports and class/function signatures
assert "import os" in result.compressed
assert "def function_" in result.compressed
+ # Compression ratio should be 1.0 (no compression)
+ assert result.compression_ratio == 1.0
# =============================================================================
diff --git a/uv.lock b/uv.lock
index 65f0ab646..0879a30fd 100644
--- a/uv.lock
+++ b/uv.lock
@@ -849,7 +849,7 @@ wheels = [
[[package]]
name = "headroom-ai"
-version = "0.2.12"
+version = "0.2.14"
source = { editable = "." }
dependencies = [
{ name = "litellm" },