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
Add Phase 2 Progressive Summarization and fix Agno integration tests
chopratejas4102402c5e27
diff --git a/headroom/integrations/agno/model.py b/headroom/integrations/agno/model.pyindex a01a1e7b7..b9ce80e8b 100644--- a/headroom/integrations/agno/model.py+++ b/headroom/integrations/agno/model.py@@ -232,17 +232,14 @@ class HeadroomAgnoModel(Model): # type: ignore[misc]result.append({"role": "user", "content": content})return result- def _convert_messages_from_openai(- self, messages: list[dict[str, Any]], original_messages: list[Any]- ) -> list[Any]:- """Convert OpenAI format messages back to Agno Message objects.+ def _ensure_message_objects(self, messages: list[Any]) -> list[Any]:+ """Ensure all messages are Agno Message objects (not dicts).- The Agno base model's response() method expects Message objects,- not dicts, because it calls .log() on them internally.+ Agno's base Model methods call _log_messages() which requires+ Message objects with a .log() method.Args:- messages: The optimized messages in OpenAI dict format- original_messages: The original Agno Message objects (for reference)+ messages: List of messages (may be dicts or Message objects)Returns:List of Agno Message objects@@ -252,8 +249,7 @@ class HeadroomAgnoModel(Model): # type: ignore[misc]result = []for msg in messages:if isinstance(msg, dict):- # Convert dict back to Agno Message- # Handle the basic fields that Headroom might have modified+ # Convert dict to Agno Messagetry:result.append(AgnoMessage.from_dict(msg))except Exception:@@ -271,6 +267,24 @@ class HeadroomAgnoModel(Model): # type: ignore[misc]result.append(msg)return result+ def _convert_messages_from_openai(+ self, messages: list[dict[str, Any]], original_messages: list[Any]+ ) -> list[Any]:+ """Convert OpenAI format messages back to Agno Message objects.++ The Agno base model's response() method expects Message objects,+ not dicts, because it calls .log() on them internally.++ Args:+ messages: The optimized messages in OpenAI dict format+ original_messages: The original Agno Message objects (for reference)++ Returns:+ List of Agno Message objects+ """+ # Reuse the ensure method which handles the conversion+ return self._ensure_message_objects(messages)+def _optimize_messages(self, messages: list[Any]) -> tuple[list[Any], OptimizationMetrics]:"""Apply Headroom optimization to messages.@@ -375,7 +389,9 @@ class HeadroomAgnoModel(Model): # type: ignore[misc]This ensures tool outputs are compressed on subsequent API calls."""- # Don't optimize here - let the tool loop in Model.response() call invoke(),+ # Ensure messages are Message objects (Agno's _log_messages requires .log() method)+ messages = self._ensure_message_objects(messages)+ # Let the tool loop in Model.response() call invoke(),# which will optimize messages for EACH API call (including tool results)return super().response(messages, **kwargs)@@ -385,6 +401,8 @@ class HeadroomAgnoModel(Model): # type: ignore[misc]Like response(), delegates to inherited Model.response_stream() whichcalls self.invoke_stream() for each API call."""+ # Ensure messages are Message objects (Agno's _log_messages requires .log() method)+ messages = self._ensure_message_objects(messages)# Let the inherited streaming method handle the tool loopyield from super().response_stream(messages, **kwargs)@@ -394,6 +412,8 @@ class HeadroomAgnoModel(Model): # type: ignore[misc]Delegates to inherited Model.aresponse() which calls self.ainvoke()for each API call, ensuring tool outputs are optimized."""+ # Ensure messages are Message objects (Agno's _log_messages requires .log() method)+ messages = self._ensure_message_objects(messages)# Let the inherited async method handle the tool loopreturn await super().aresponse(messages, **kwargs)@@ -403,6 +423,8 @@ class HeadroomAgnoModel(Model): # type: ignore[misc]Delegates to inherited Model.aresponse_stream() which calls self.ainvoke_stream()for each API call, ensuring tool outputs are optimized."""+ # Ensure messages are Message objects (Agno's _log_messages requires .log() method)+ messages = self._ensure_message_objects(messages)# Let the inherited async streaming method handle the tool loopasync for chunk in super().aresponse_stream(messages, **kwargs):yield chunkdiff --git a/headroom/transforms/intelligent_context.py b/headroom/transforms/intelligent_context.pyindex 81aa201c0..f86a7a8e8 100644--- a/headroom/transforms/intelligent_context.py+++ b/headroom/transforms/intelligent_context.py@@ -9,10 +9,12 @@ All importance signals are derived from:2. TOIN-learned patterns (field_semantics, retrieval_rate)3. Embedding similarity (optional)-Strategy Selection:+Strategy Selection (in order of preference):- NONE: Under budget, no action needed- COMPRESS_FIRST: When <compress_threshold over budget, try deeper compressionof tool outputs using ContentRouter before dropping messages+- SUMMARIZE: When <summarize_threshold over budget and summarization_enabled,+ create anchored summaries of older messages (requires summarize_fn callback)- DROP_BY_SCORE: When significantly over budget, drop lowest-scored messages"""@@ -32,6 +34,7 @@ from .scoring import MessageScore, MessageScorerif TYPE_CHECKING:from ..telemetry.toin import ToolIntelligenceNetworkfrom .content_router import ContentRouter+ from .progressive_summarizer import ProgressiveSummarizer, SummarizeFnlogger = logging.getLogger(__name__)@@ -41,6 +44,7 @@ class ContextStrategy(Enum):NONE = "none" # Under budget, do nothingCOMPRESS_FIRST = "compress" # Try deeper compression first+ SUMMARIZE = "summarize" # Create anchored summaries of older messagesDROP_BY_SCORE = "drop_scored" # Drop lowest-scored messagesHYBRID = "hybrid" # Combination of strategies@@ -72,6 +76,7 @@ class IntelligentContextManager(Transform):self,config: IntelligentContextConfig | None = None,toin: ToolIntelligenceNetwork | None = None,+ summarize_fn: SummarizeFn | None = None,):"""Initialize intelligent context manager.@@ -79,11 +84,15 @@ class IntelligentContextManager(Transform):Args:config: Configuration for context management.toin: Optional TOIN instance for learned patterns.+ summarize_fn: Optional callback for summarization.+ If provided and summarization_enabled=True, enables SUMMARIZE strategy.+ Signature: (messages: list[dict], context: str) -> str"""from ..config import IntelligentContextConfigself.config = config or IntelligentContextConfig()self.toin = toin+ self._summarize_fn = summarize_fn# Initialize scorer with TOIN if availableself.scorer = MessageScorer(@@ -95,6 +104,9 @@ class IntelligentContextManager(Transform):# Lazy-loaded content router for COMPRESS_FIRST strategyself._content_router: ContentRouter | None = None+ # Lazy-loaded progressive summarizer for SUMMARIZE strategy+ self._progressive_summarizer: ProgressiveSummarizer | None = None+def should_apply(self,messages: list[dict[str, Any]],@@ -187,16 +199,61 @@ class IntelligentContextManager(Transform):warnings=warnings,)- # Still over budget, fall through to DROP_BY_SCORE+ # Still over budget, fall through to SUMMARIZE or DROP_BY_SCORElogger.debug("IntelligentContextManager: COMPRESS_FIRST saved %d tokens but still "+ "over budget (%d > %d), checking next strategy",+ tokens_saved,+ current_tokens,+ available,+ )+ # Check if we should try summarization next+ over_ratio = (current_tokens - available) / available+ if self.config.summarization_enabled and over_ratio < self.config.summarize_threshold:+ strategy = ContextStrategy.SUMMARIZE+ else:+ strategy = ContextStrategy.DROP_BY_SCORE+ # Need to recalculate protected indices after compression+ protected = self._get_protected_indices(result_messages)++ # ========== SUMMARIZE STRATEGY ==========+ # Create anchored summaries of older messages+ if strategy == ContextStrategy.SUMMARIZE:+ result_messages, summarize_transforms, tokens_saved = self._apply_summarize(+ result_messages, tokenizer, protected, available+ )+ transforms_applied.extend(summarize_transforms)++ # Recheck token count after summarization+ current_tokens = tokenizer.count_messages(result_messages)++ # If now under budget, we're done!+ if current_tokens <= available:+ logger.info(+ "IntelligentContextManager: SUMMARIZE succeeded, saved %d tokens: %d -> %d",+ tokens_saved,+ tokens_before,+ current_tokens,+ )+ return TransformResult(+ messages=result_messages,+ tokens_before=tokens_before,+ tokens_after=current_tokens,+ transforms_applied=transforms_applied,+ markers_inserted=markers_inserted,+ warnings=warnings,+ )++ # Still over budget, fall through to DROP_BY_SCORE+ logger.debug(+ "IntelligentContextManager: SUMMARIZE saved %d tokens but still ""over budget (%d > %d), proceeding to DROP_BY_SCORE",tokens_saved,current_tokens,available,)strategy = ContextStrategy.DROP_BY_SCORE- # Need to recalculate protected indices after compression+ # Need to recalculate protected indices after summarizationprotected = self._get_protected_indices(result_messages)# ========== DROP_BY_SCORE STRATEGY ==========@@ -301,15 +358,28 @@ class IntelligentContextManager(Transform):)def _select_strategy(self, current_tokens: int, available: int) -> ContextStrategy:- """Select strategy based on how much over budget we are."""+ """Select strategy based on how much over budget we are.++ Strategy selection order:+ 1. NONE: Under budget+ 2. COMPRESS_FIRST: < compress_threshold (default 10%) over budget+ 3. SUMMARIZE: < summarize_threshold (default 25%) over budget AND enabled+ 4. DROP_BY_SCORE: >= summarize_threshold over budget+ """if current_tokens <= available:return ContextStrategy.NONEover_ratio = (current_tokens - available) / available+ # Tier 1: Try compression first for small overagesif over_ratio < self.config.compress_threshold:return ContextStrategy.COMPRESS_FIRST+ # Tier 2: Try summarization for moderate overages (if enabled)+ if self.config.summarization_enabled and over_ratio < self.config.summarize_threshold:+ return ContextStrategy.SUMMARIZE++ # Tier 3: Drop by score for large overagesreturn ContextStrategy.DROP_BY_SCOREdef _get_content_router(self) -> ContentRouter | None:@@ -684,3 +754,74 @@ class IntelligentContextManager(Transform):)return scores++ def _get_progressive_summarizer(self) -> ProgressiveSummarizer | None:+ """Get or create progressive summarizer for SUMMARIZE strategy (lazy load)."""+ if self._progressive_summarizer is None:+ try:+ from .progressive_summarizer import ProgressiveSummarizer++ self._progressive_summarizer = ProgressiveSummarizer(+ summarize_fn=self._summarize_fn,+ max_summary_tokens=self.config.summary_max_tokens,+ min_messages_to_summarize=3,+ store_for_retrieval=True,+ )+ except ImportError:+ logger.debug("ProgressiveSummarizer not available for SUMMARIZE")+ return self._progressive_summarizer++ def _apply_summarize(+ self,+ messages: list[dict[str, Any]],+ tokenizer: Tokenizer,+ protected: set[int],+ target_tokens: int,+ ) -> tuple[list[dict[str, Any]], list[str], int]:+ """Apply progressive summarization to older messages.++ This is the SUMMARIZE strategy: create anchored summaries of older+ messages to reduce token count while maintaining retrievability.++ Args:+ messages: List of messages to summarize.+ tokenizer: Tokenizer for counting.+ protected: Set of protected message indices.+ target_tokens: Target token budget.++ Returns:+ Tuple of (summarized_messages, transforms_applied, tokens_saved).+ """+ summarizer = self._get_progressive_summarizer()+ if summarizer is None:+ return messages, [], 0++ # Get recent messages for context+ context_messages = []+ for i in sorted(protected):+ if i < len(messages):+ context_messages.append(messages[i])++ try:+ result = summarizer.summarize_messages(+ messages=messages,+ tokenizer=tokenizer,+ protected_indices=protected,+ target_tokens=target_tokens,+ context_messages=context_messages[-5:], # Last 5 for context+ )++ tokens_saved = result.tokens_before - result.tokens_after++ if tokens_saved > 0:+ logger.info(+ "SUMMARIZE: created %d summaries, saved %d tokens",+ len(result.summaries_created),+ tokens_saved,+ )++ return result.messages, result.transforms_applied, tokens_saved++ except Exception as e:+ logger.warning("SUMMARIZE: summarization failed: %s", e)+ return messages, [], 0diff --git a/headroom/transforms/progressive_summarizer.py b/headroom/transforms/progressive_summarizer.pynew file mode 100644index 000000000..7d5d087a6--- /dev/null+++ b/headroom/transforms/progressive_summarizer.py@@ -0,0 +1,508 @@+"""Progressive summarization for Headroom SDK.++This module provides anchored summarization that progressively summarizes+older messages while maintaining retrieval capability via CCR.++Design principles:+1. CALLBACK PATTERN: Summarization is done via a callback, not internal LLM calls+2. ANCHORED: Summaries track which message positions they represent+3. REVERSIBLE: Original content stored in CompressionStore for CCR retrieval+4. INCREMENTAL: Only summarize newly dropped spans, then merge++Usage:+ from headroom.transforms import ProgressiveSummarizer++ # With custom summarizer callback+ def my_summarizer(messages: list[dict], context: str) -> str:+ # Your summarization logic (LLM call, extractive, etc.)+ return "Summary of messages..."++ summarizer = ProgressiveSummarizer(+ summarize_fn=my_summarizer,+ max_summary_tokens=500,+ )++ result = summarizer.summarize_messages(messages, tokenizer, protected)+"""++from __future__ import annotations++import hashlib+import json+import logging+import time+from dataclasses import dataclass, field+from typing import TYPE_CHECKING, Any, Protocol++if TYPE_CHECKING:+ from ..cache.compression_store import CompressionStore+ from ..tokenizer import Tokenizer++logger = logging.getLogger(__name__)+++class SummarizeFn(Protocol):+ """Protocol for summarization callback functions.++ The callback receives:+ - messages: List of messages to summarize+ - context: Optional context string (e.g., recent messages for relevance)++ Returns:+ - Summary string+ """++ def __call__(+ self,+ messages: list[dict[str, Any]],+ context: str = "",+ ) -> str: ...+++@dataclass+class AnchoredSummary:+ """A summary anchored to specific message positions.++ Tracks which messages were summarized for:+ - Retrieval: Can reconstruct original messages via CCR+ - Merging: Can merge with adjacent summaries+ - Positioning: Know where in conversation this summary belongs+ """++ summary_text: str+ start_index: int # First message index summarized+ end_index: int # Last message index summarized (inclusive)+ original_message_count: int+ original_tokens: int+ summary_tokens: int+ cache_hash: str | None = None # Hash for CCR retrieval+ tool_names: list[str] = field(default_factory=list)+ created_at: float = field(default_factory=time.time)++ @property+ def compression_ratio(self) -> float:+ """Ratio of summary tokens to original tokens (lower = more compression)."""+ if self.original_tokens == 0:+ return 1.0+ return self.summary_tokens / self.original_tokens++ @property+ def tokens_saved(self) -> int:+ """Number of tokens saved by summarization."""+ return max(0, self.original_tokens - self.summary_tokens)+++@dataclass+class SummarizationResult:+ """Result of a summarization operation."""++ messages: list[dict[str, Any]]+ summaries_created: list[AnchoredSummary]+ tokens_before: int+ tokens_after: int+ transforms_applied: list[str]++ @property+ def tokens_saved(self) -> int:+ """Total tokens saved."""+ return max(0, self.tokens_before - self.tokens_after)+++def extractive_summarizer(+ messages: list[dict[str, Any]],+ context: str = "",+ max_items_per_role: int = 2,+) -> str:+ """Default extractive summarizer (no LLM required).++ Creates a summary by extracting key content from messages:+ - First and last message of each role+ - Error indicators+ - Tool names and brief results++ This is a fallback when no LLM summarizer is provided.++ Args:+ messages: Messages to summarize.+ context: Optional context (unused in extractive mode).+ max_items_per_role: Max items to keep per role type.++ Returns:+ Extractive summary string.+ """+ if not messages:+ return "[No messages to summarize]"++ parts: list[str] = []+ parts.append(f"[Summary of {len(messages)} messages]")++ # Group by role+ by_role: dict[str, list[dict[str, Any]]] = {}+ for msg in messages:+ role = msg.get("role", "unknown")+ by_role.setdefault(role, []).append(msg)++ # Extract key content from each role+ for role, role_msgs in by_role.items():+ if role == "tool":+ # For tool messages, extract tool names and brief status+ tool_names = set()+ has_error = False+ for msg in role_msgs:+ content = msg.get("content", "")+ # Try to detect tool name from context+ tool_call_id = msg.get("tool_call_id", "")+ if tool_call_id:+ tool_names.add(f"tool:{tool_call_id[:8]}")++ # Check for errors+ content_lower = content.lower() if isinstance(content, str) else ""+ if any(err in content_lower for err in ["error", "failed", "exception"]):+ has_error = True++ status = "with errors" if has_error else "successful"+ parts.append(f"- {len(role_msgs)} tool outputs ({status})")++ elif role == "assistant":+ # Extract first and last assistant responses+ if len(role_msgs) == 1:+ content = role_msgs[0].get("content", "")+ if isinstance(content, str):+ preview = content[:100] + "..." if len(content) > 100 else content+ parts.append(f"- Assistant: {preview}")+ else:+ parts.append(f"- {len(role_msgs)} assistant messages")++ elif role == "user":+ # Count user messages+ parts.append(f"- {len(role_msgs)} user messages")++ elif role == "system":+ # Note system messages (shouldn't be summarized usually)+ parts.append(f"- {len(role_msgs)} system messages")++ return "\n".join(parts)+++class ProgressiveSummarizer:+ """Progressive summarization with anchoring and CCR integration.++ This class implements the SUMMARIZE strategy for IntelligentContextManager:+ 1. Identifies candidate messages (low-scored, non-protected)+ 2. Groups consecutive messages for summarization+ 3. Calls summarizer callback to create summaries+ 4. Stores originals in CompressionStore for CCR retrieval+ 5. Replaces messages with anchored summary message++ Key features:+ - Callback pattern: No LLM calls inside, summarization logic is external+ - Anchored: Summaries track original positions for context+ - Reversible: Originals cached for retrieval+ - Incremental: Can merge adjacent summaries+ """++ def __init__(+ self,+ summarize_fn: SummarizeFn | None = None,+ max_summary_tokens: int = 500,+ min_messages_to_summarize: int = 3,+ compression_store: CompressionStore | None = None,+ store_for_retrieval: bool = True,+ ):+ """Initialize the progressive summarizer.++ Args:+ summarize_fn: Callback function for summarization.+ If None, uses extractive_summarizer as fallback.+ max_summary_tokens: Target max tokens for each summary.+ min_messages_to_summarize: Minimum messages in a group to summarize.+ compression_store: Optional CompressionStore for CCR integration.+ store_for_retrieval: Whether to store originals for retrieval.+ """+ self.summarize_fn = summarize_fn or extractive_summarizer+ self.max_summary_tokens = max_summary_tokens+ self.min_messages_to_summarize = min_messages_to_summarize+ self._compression_store = compression_store+ self.store_for_retrieval = store_for_retrieval++ def _get_compression_store(self) -> CompressionStore | None:+ """Get or create compression store (lazy load)."""+ if self._compression_store is None and self.store_for_retrieval:+ try:+ from ..cache.compression_store import get_compression_store++ self._compression_store = get_compression_store()+ except ImportError:+ logger.debug("CompressionStore not available for CCR")+ return self._compression_store++ def summarize_messages(+ self,+ messages: list[dict[str, Any]],+ tokenizer: Tokenizer,+ protected_indices: set[int],+ target_tokens: int | None = None,+ context_messages: list[dict[str, Any]] | None = None,+ ) -> SummarizationResult:+ """Summarize messages to reduce token count.++ Args:+ messages: List of messages to process.+ tokenizer: Tokenizer for counting.+ protected_indices: Indices that cannot be summarized.+ target_tokens: Target token count (optional, summarizes all candidates if None).+ context_messages: Recent messages for context in summarization.++ Returns:+ SummarizationResult with summarized messages.+ """+ from ..utils import deep_copy_messages++ tokens_before = tokenizer.count_messages(messages)+ result_messages = deep_copy_messages(messages)+ transforms_applied: list[str] = []+ summaries_created: list[AnchoredSummary] = []++ # Find candidate groups for summarization+ candidate_groups = self._find_summarization_candidates(result_messages, protected_indices)++ if not candidate_groups:+ logger.debug("ProgressiveSummarizer: no candidates for summarization")+ return SummarizationResult(+ messages=result_messages,+ summaries_created=[],+ tokens_before=tokens_before,+ tokens_after=tokens_before,+ transforms_applied=[],+ )++ # Build context string from recent messages+ context_str = ""+ if context_messages:+ context_parts = []+ for msg in context_messages[-3:]: # Last 3 messages for context+ role = msg.get("role", "")+ content = msg.get("content", "")+ if isinstance(content, str) and content:+ preview = content[:200] if len(content) > 200 else content+ context_parts.append(f"{role}: {preview}")+ context_str = "\n".join(context_parts)++ # Process groups in reverse order (so indices stay valid)+ current_tokens = tokens_before++ for group in reversed(candidate_groups):+ # Check if we've reached target+ if target_tokens and current_tokens <= target_tokens:+ break++ start_idx, end_idx = group+ group_messages = result_messages[start_idx : end_idx + 1]++ # Skip if too few messages+ if len(group_messages) < self.min_messages_to_summarize:+ continue++ # Calculate group tokens+ group_tokens = sum(tokenizer.count_message(msg) for msg in group_messages)++ # Skip small groups+ if group_tokens < 100:+ continue++ # Create summary using callback+ try:+ summary_text = self.summarize_fn(group_messages, context_str)+ except Exception as e:+ logger.warning(+ "ProgressiveSummarizer: summarization failed for group %d-%d: %s",+ start_idx,+ end_idx,+ e,+ )+ continue++ summary_tokens = tokenizer.count_text(summary_text)++ # Only use summary if it saves tokens+ if summary_tokens >= group_tokens:+ logger.debug(+ "ProgressiveSummarizer: summary not smaller (%d >= %d), skipping",+ summary_tokens,+ group_tokens,+ )+ continue++ # Store original for CCR retrieval+ cache_hash = None+ if self.store_for_retrieval:+ cache_hash = self._store_for_retrieval(+ group_messages, summary_text, group_tokens, summary_tokens+ )++ # Extract tool names+ tool_names = []+ for msg in group_messages:+ if msg.get("role") == "tool":+ tool_call_id = msg.get("tool_call_id", "")+ if tool_call_id:+ tool_names.append(tool_call_id[:8])++ # Create anchored summary+ anchored = AnchoredSummary(+ summary_text=summary_text,+ start_index=start_idx,+ end_index=end_idx,+ original_message_count=len(group_messages),+ original_tokens=group_tokens,+ summary_tokens=summary_tokens,+ cache_hash=cache_hash,+ tool_names=tool_names,+ )+ summaries_created.append(anchored)++ # Create summary message with retrieval marker+ summary_content = summary_text+ if cache_hash:+ summary_content += f"\n[Retrieve full content: hash={cache_hash}]"++ summary_message = {+ "role": "user",+ "content": summary_content,+ }++ # Replace group with summary message+ result_messages = (+ result_messages[:start_idx] + [summary_message] + result_messages[end_idx + 1 :]+ )++ # Update token count+ tokens_saved = group_tokens - summary_tokens+ current_tokens -= tokens_saved++ transforms_applied.append(f"summarize:{start_idx}-{end_idx}:{len(group_messages)}")++ logger.debug(+ "ProgressiveSummarizer: summarized %d messages (%d-%d), saved %d tokens (%d -> %d)",+ len(group_messages),+ start_idx,+ end_idx,+ tokens_saved,+ group_tokens,+ summary_tokens,+ )++ # Update protected indices for subsequent groups+ # (indices shift after replacement)+ shift = len(group_messages) - 1 # We replaced N messages with 1+ protected_indices = {idx - shift if idx > end_idx else idx for idx in protected_indices}++ tokens_after = tokenizer.count_messages(result_messages)++ if summaries_created:+ logger.info(+ "ProgressiveSummarizer: created %d summaries, saved %d tokens (%d -> %d)",+ len(summaries_created),+ tokens_before - tokens_after,+ tokens_before,+ tokens_after,+ )++ return SummarizationResult(+ messages=result_messages,+ summaries_created=summaries_created,+ tokens_before=tokens_before,+ tokens_after=tokens_after,+ transforms_applied=transforms_applied,+ )++ def _find_summarization_candidates(+ self,+ messages: list[dict[str, Any]],+ protected: set[int],+ ) -> list[tuple[int, int]]:+ """Find groups of consecutive messages that can be summarized.++ Returns list of (start_index, end_index) tuples for candidate groups.+ Groups are consecutive non-protected messages.++ Args:+ messages: List of messages.+ protected: Set of protected indices.++ Returns:+ List of (start, end) tuples for candidate groups.+ """+ groups: list[tuple[int, int]] = []+ current_start: int | None = None++ for i, _msg in enumerate(messages):+ if i in protected:+ # End current group if exists+ if current_start is not None:+ if i - 1 >= current_start:+ groups.append((current_start, i - 1))+ current_start = None+ else:+ # Start or continue group+ if current_start is None:+ current_start = i++ # Handle final group+ if current_start is not None and len(messages) - 1 >= current_start:+ groups.append((current_start, len(messages) - 1))++ # Filter groups that are too small+ groups = [+ (start, end)+ for start, end in groups+ if end - start + 1 >= self.min_messages_to_summarize+ ]++ return groups++ def _store_for_retrieval(+ self,+ messages: list[dict[str, Any]],+ summary: str,+ original_tokens: int,+ summary_tokens: int,+ ) -> str | None:+ """Store original messages in CompressionStore for CCR retrieval.++ Args:+ messages: Original messages.+ summary: Summary text.+ original_tokens: Token count of originals.+ summary_tokens: Token count of summary.++ Returns:+ Cache hash for retrieval, or None if storage failed.+ """+ store = self._get_compression_store()+ if store is None:+ return None++ try:+ # Serialize messages for storage+ original_content = json.dumps(messages, ensure_ascii=False)++ # Generate hash+ content_hash = hashlib.sha256(original_content.encode()).hexdigest()[:24]++ # Store in compression store+ store.store(+ original=original_content,+ compressed=summary,+ original_tokens=original_tokens,+ compressed_tokens=summary_tokens,+ original_item_count=len(messages),+ compressed_item_count=1,+ tool_name="progressive_summarizer",+ )++ return content_hash++ except Exception as e:+ logger.debug("Failed to store for CCR retrieval: %s", e)+ return Nonediff --git a/tests/test_integrations/agno/test_model.py b/tests/test_integrations/agno/test_model.pyindex 3726710fd..9ddd3687c 100644--- a/tests/test_integrations/agno/test_model.py+++ b/tests/test_integrations/agno/test_model.py@@ -29,6 +29,8 @@ pytestmark = pytest.mark.skipif(not AGNO_AVAILABLE, reason="Agno not installed")@pytest.fixturedef mock_agno_model():"""Create a mock Agno model (OpenAIChat-like)."""+ from agno.models.response import ModelResponse+mock = MagicMock()mock.__class__.__name__ = "OpenAIChat"mock.__class__.__module__ = "agno.models.openai"@@ -46,12 +48,45 @@ def mock_agno_model():mock.response = MagicMock(side_effect=mock_response)+ # Mock invoke method (returns ModelResponse for Agno's response() loop)+ def mock_invoke(messages, **kwargs):+ from agno.models.metrics import Metrics++ # Create a proper ModelResponse that Agno's response() can process+ return ModelResponse(+ role="assistant",+ content="Hello! I'm a mock response.",+ response_usage=Metrics(+ input_tokens=10,+ output_tokens=5,+ total_tokens=15,+ ),+ )++ mock.invoke = MagicMock(side_effect=mock_invoke)+# Mock streaming responsedef mock_stream(messages, **kwargs):yield MagicMock(content="Streaming...")mock.response_stream = MagicMock(side_effect=mock_stream)+ # Mock invoke_stream for streaming+ def mock_invoke_stream(messages, **kwargs):+ from agno.models.metrics import Metrics++ yield ModelResponse(+ role="assistant",+ content="Streaming...",+ response_usage=Metrics(+ input_tokens=10,+ output_tokens=5,+ total_tokens=15,+ ),+ )++ mock.invoke_stream = MagicMock(side_effect=mock_invoke_stream)+return mockdiff --git a/tests/test_transforms/test_intelligent_context.py b/tests/test_transforms/test_intelligent_context.pyindex 781f49dd9..bcf87d944 100644--- a/tests/test_transforms/test_intelligent_context.py+++ b/tests/test_transforms/test_intelligent_context.py@@ -1279,3 +1279,540 @@ class TestCompressFirstEdgeCases:# The recent messages should be protected# With 6 messages and keep_last_turns=5, most should be protectedassert len(protected) > 0+++# ==============================================================================+# SUMMARIZE STRATEGY TESTS+# ==============================================================================+++class TestSummarizeStrategySelection:+ """Tests for SUMMARIZE strategy selection logic."""++ def test_summarize_strategy_selected_when_enabled(self, tokenizer: Tokenizer):+ """SUMMARIZE should be selected when enabled and in threshold range."""+ messages = [+ {"role": "system", "content": "System"},+ {"role": "user", "content": "Hello " * 100},+ {"role": "assistant", "content": "Response " * 100},+ {"role": "user", "content": "More " * 100},+ {"role": "assistant", "content": "More response " * 100},+ {"role": "user", "content": "Final"},+ ]++ config = IntelligentContextConfig(+ summarization_enabled=True,+ compress_threshold=0.05, # 5% triggers COMPRESS_FIRST+ summarize_threshold=0.30, # 30% is threshold for DROP_BY_SCORE+ keep_last_turns=1,+ )+ manager = IntelligentContextManager(config=config)++ tokens = tokenizer.count_messages(messages)+ # Set limit so we're ~15% over (between compress and summarize thresholds)+ available = int(tokens / 1.15)++ strategy = manager._select_strategy(tokens, available)+ assert strategy == ContextStrategy.SUMMARIZE++ def test_summarize_not_selected_when_disabled(self, tokenizer: Tokenizer):+ """SUMMARIZE should not be selected when disabled."""+ messages = [+ {"role": "system", "content": "System"},+ {"role": "user", "content": "Hello " * 100},+ {"role": "assistant", "content": "Response " * 100},+ {"role": "user", "content": "Final"},+ ]++ config = IntelligentContextConfig(+ summarization_enabled=False, # Disabled+ compress_threshold=0.05,+ summarize_threshold=0.30,+ )+ manager = IntelligentContextManager(config=config)++ tokens = tokenizer.count_messages(messages)+ available = int(tokens / 1.15) # 15% over++ strategy = manager._select_strategy(tokens, available)+ # Should skip SUMMARIZE and go to DROP_BY_SCORE+ assert strategy == ContextStrategy.DROP_BY_SCORE++ def test_drop_strategy_when_over_summarize_threshold(self, tokenizer: Tokenizer):+ """DROP_BY_SCORE when over summarize_threshold even if enabled."""+ messages = [+ {"role": "system", "content": "System"},+ {"role": "user", "content": "Hello " * 100},+ {"role": "assistant", "content": "Response " * 100},+ ]++ config = IntelligentContextConfig(+ summarization_enabled=True,+ compress_threshold=0.05,+ summarize_threshold=0.20,+ )+ manager = IntelligentContextManager(config=config)++ tokens = tokenizer.count_messages(messages)+ available = int(tokens / 1.50) # 50% over - way over threshold++ strategy = manager._select_strategy(tokens, available)+ assert strategy == ContextStrategy.DROP_BY_SCORE+++class TestSummarizeStrategy:+ """Tests for SUMMARIZE strategy execution."""++ def test_summarize_reduces_tokens(self, tokenizer: Tokenizer):+ """SUMMARIZE should reduce token count."""+ # Create conversation with many messages to summarize+ messages = [+ {"role": "system", "content": "You are a helpful assistant."},+ ]++ # Add many user/assistant turns+ for i in range(10):+ messages.append({"role": "user", "content": f"Question {i}: " + "explain this " * 20})+ messages.append(+ {"role": "assistant", "content": f"Answer {i}: " + "here is my response " * 30}+ )++ messages.append({"role": "user", "content": "Final question"})+ messages.append({"role": "assistant", "content": "Final answer"})++ config = IntelligentContextConfig(+ summarization_enabled=True,+ compress_threshold=0.05, # Low, so we skip COMPRESS_FIRST+ summarize_threshold=0.30,+ keep_last_turns=2, # Protect last 2 turns+ )+ manager = IntelligentContextManager(config=config)++ tokens_before = tokenizer.count_messages(messages)+ # Set limit to trigger SUMMARIZE (15% over)+ target_limit = int(tokens_before / 1.15)++ result = manager.apply(+ messages,+ tokenizer,+ model_limit=target_limit,+ output_buffer=50,+ )++ # Should have reduced tokens+ assert result.tokens_after < result.tokens_before++ def test_summarize_with_custom_summarizer(self, tokenizer: Tokenizer):+ """SUMMARIZE should use custom summarizer callback."""+ summarizer_called = []++ def custom_summarizer(messages: list[dict], context: str = "") -> str:+ summarizer_called.append(len(messages))+ return f"[Summary of {len(messages)} messages]"++ messages = [+ {"role": "system", "content": "System"},+ ]+ for i in range(8):+ messages.append({"role": "user", "content": f"Question {i} " * 30})+ messages.append({"role": "assistant", "content": f"Answer {i} " * 30})+ messages.append({"role": "user", "content": "Final"})++ config = IntelligentContextConfig(+ summarization_enabled=True,+ compress_threshold=0.05,+ summarize_threshold=0.30,+ keep_last_turns=1,+ )+ manager = IntelligentContextManager(+ config=config,+ summarize_fn=custom_summarizer,+ )++ tokens_before = tokenizer.count_messages(messages)+ target_limit = int(tokens_before / 1.15)++ result = manager.apply(+ messages,+ tokenizer,+ model_limit=target_limit,+ output_buffer=50,+ )++ # Summarizer should have been called+ assert len(summarizer_called) > 0+ # Should have reduced tokens+ assert result.tokens_after < result.tokens_before++ def test_summarize_fallback_to_drop_when_not_enough(self, tokenizer: Tokenizer):+ """SUMMARIZE should fall back to DROP_BY_SCORE when not enough."""++ # Custom summarizer that doesn't save much+ def ineffective_summarizer(messages: list[dict], context: str = "") -> str:+ # Return almost as long as original+ return "This is a very long summary " * 50++ messages = [+ {"role": "system", "content": "System"},+ ]+ for i in range(6):+ messages.append({"role": "user", "content": f"Q{i} " * 20})+ messages.append({"role": "assistant", "content": f"A{i} " * 20})+ messages.append({"role": "user", "content": "Final"})++ config = IntelligentContextConfig(+ summarization_enabled=True,+ compress_threshold=0.05,+ summarize_threshold=0.30,+ keep_last_turns=1,+ )+ manager = IntelligentContextManager(+ config=config,+ summarize_fn=ineffective_summarizer,+ )++ tokens_before = tokenizer.count_messages(messages)+ # Very aggressive limit+ target_limit = int(tokens_before / 2.0)++ result = manager.apply(+ messages,+ tokenizer,+ model_limit=target_limit,+ output_buffer=50,+ )++ # Should still reduce tokens (via DROP_BY_SCORE fallback)+ assert result.tokens_after < result.tokens_before++ def test_summarize_preserves_protected_messages(self, tokenizer: Tokenizer):+ """SUMMARIZE should never summarize protected messages."""+ messages = [+ {"role": "system", "content": "Important system prompt " * 20},+ {"role": "user", "content": "Old question " * 30},+ {"role": "assistant", "content": "Old answer " * 30},+ {"role": "user", "content": "Recent question " * 30},+ {"role": "assistant", "content": "Recent answer " * 30},+ {"role": "user", "content": "Final question"},+ ]++ config = IntelligentContextConfig(+ summarization_enabled=True,+ compress_threshold=0.05,+ summarize_threshold=0.30,+ keep_system=True,+ keep_last_turns=2, # Protect last 2 user turns+ )+ manager = IntelligentContextManager(config=config)++ tokens_before = tokenizer.count_messages(messages)+ target_limit = int(tokens_before / 1.15)++ result = manager.apply(+ messages,+ tokenizer,+ model_limit=target_limit,+ output_buffer=50,+ )++ # System message should still be present+ system_messages = [m for m in result.messages if m.get("role") == "system"]+ assert len(system_messages) >= 1+ assert "Important system prompt" in system_messages[0].get("content", "")+++class TestProgressiveSummarizer:+ """Tests for ProgressiveSummarizer component."""++ def test_extractive_summarizer_default(self, tokenizer: Tokenizer):+ """Default extractive summarizer should work."""+ from headroom.transforms.progressive_summarizer import (+ extractive_summarizer,+ )++ messages = [+ {"role": "user", "content": "Question 1 " * 20},+ {"role": "assistant", "content": "Answer 1 " * 30},+ {"role": "user", "content": "Question 2 " * 20},+ {"role": "assistant", "content": "Answer 2 " * 30},+ ]++ # Test extractive summarizer directly+ summary = extractive_summarizer(messages)+ assert "[Summary of" in summary+ assert "4 messages" in summary++ def test_progressive_summarizer_groups_messages(self, tokenizer: Tokenizer):+ """ProgressiveSummarizer should identify message groups correctly."""+ from headroom.transforms.progressive_summarizer import ProgressiveSummarizer++ summarizer = ProgressiveSummarizer(+ min_messages_to_summarize=2,+ store_for_retrieval=False,+ )++ messages = [+ {"role": "system", "content": "System"},+ {"role": "user", "content": "Q1 " * 30},+ {"role": "assistant", "content": "A1 " * 30},+ {"role": "user", "content": "Q2 " * 30},+ {"role": "assistant", "content": "A2 " * 30},+ {"role": "user", "content": "Final"},+ ]++ # Protect only system (0) and final (5)+ protected = {0, 5}++ groups = summarizer._find_summarization_candidates(messages, protected)++ # Should find the middle messages as a group+ assert len(groups) >= 1+ # Group should include indices 1-4+ found_middle_group = any(start <= 1 and end >= 4 for start, end in groups)+ assert found_middle_group++ def test_progressive_summarizer_respects_min_messages(self, tokenizer: Tokenizer):+ """ProgressiveSummarizer should respect min_messages_to_summarize."""+ from headroom.transforms.progressive_summarizer import ProgressiveSummarizer++ summarizer = ProgressiveSummarizer(+ min_messages_to_summarize=5, # High threshold+ store_for_retrieval=False,+ )++ messages = [+ {"role": "system", "content": "System"},+ {"role": "user", "content": "Q1"},+ {"role": "assistant", "content": "A1"},+ {"role": "user", "content": "Final"},+ ]++ protected = {0, 3}++ groups = summarizer._find_summarization_candidates(messages, protected)++ # Should not find any groups (only 2 unprotected messages)+ assert len(groups) == 0++ def test_progressive_summarizer_summarizes_messages(self, tokenizer: Tokenizer):+ """ProgressiveSummarizer should create summaries correctly."""+ from headroom.transforms.progressive_summarizer import ProgressiveSummarizer++ summarizer = ProgressiveSummarizer(+ min_messages_to_summarize=3,+ store_for_retrieval=False,+ )++ messages = [+ {"role": "system", "content": "System"},+ {"role": "user", "content": "Q1 " * 50},+ {"role": "assistant", "content": "A1 " * 50},+ {"role": "user", "content": "Q2 " * 50},+ {"role": "assistant", "content": "A2 " * 50},+ {"role": "user", "content": "Final question"},+ ]++ protected = {0, 5} # System and final++ result = summarizer.summarize_messages(+ messages=messages,+ tokenizer=tokenizer,+ protected_indices=protected,+ )++ # Should have reduced message count+ assert len(result.messages) < len(messages)+ # Should have created summaries+ assert len(result.summaries_created) > 0+ # Should have saved tokens+ assert result.tokens_after < result.tokens_before+++class TestAnchoredSummary:+ """Tests for AnchoredSummary data structure."""++ def test_anchored_summary_compression_ratio(self):+ """AnchoredSummary should calculate compression ratio correctly."""+ from headroom.transforms.progressive_summarizer import AnchoredSummary++ summary = AnchoredSummary(+ summary_text="Summary",+ start_index=0,+ end_index=5,+ original_message_count=6,+ original_tokens=1000,+ summary_tokens=100,+ )++ assert summary.compression_ratio == 0.1+ assert summary.tokens_saved == 900++ def test_anchored_summary_zero_original_tokens(self):+ """AnchoredSummary should handle zero original tokens."""+ from headroom.transforms.progressive_summarizer import AnchoredSummary++ summary = AnchoredSummary(+ summary_text="Summary",+ start_index=0,+ end_index=0,+ original_message_count=1,+ original_tokens=0,+ summary_tokens=10,+ )++ assert summary.compression_ratio == 1.0+ assert summary.tokens_saved == 0+++class TestSummarizeEdgeCases:+ """Edge case tests for SUMMARIZE strategy."""++ def test_summarize_empty_messages(self, tokenizer: Tokenizer):+ """SUMMARIZE should handle empty messages list."""+ from headroom.transforms.progressive_summarizer import ProgressiveSummarizer++ summarizer = ProgressiveSummarizer(store_for_retrieval=False)++ result = summarizer.summarize_messages(+ messages=[],+ tokenizer=tokenizer,+ protected_indices=set(),+ )++ assert result.messages == []+ assert len(result.summaries_created) == 0++ def test_summarize_all_protected(self, tokenizer: Tokenizer):+ """SUMMARIZE should handle when all messages are protected."""+ from headroom.transforms.progressive_summarizer import ProgressiveSummarizer++ summarizer = ProgressiveSummarizer(store_for_retrieval=False)++ messages = [+ {"role": "system", "content": "System"},+ {"role": "user", "content": "Question"},+ {"role": "assistant", "content": "Answer"},+ ]++ result = summarizer.summarize_messages(+ messages=messages,+ tokenizer=tokenizer,+ protected_indices={0, 1, 2}, # All protected+ )++ # Should return unchanged messages+ assert len(result.messages) == len(messages)+ assert len(result.summaries_created) == 0++ def test_summarize_with_tool_messages(self, tokenizer: Tokenizer):+ """SUMMARIZE should handle tool messages."""+ import json++ from headroom.transforms.progressive_summarizer import ProgressiveSummarizer++ summarizer = ProgressiveSummarizer(+ min_messages_to_summarize=3,+ store_for_retrieval=False,+ )++ messages = [+ {"role": "system", "content": "System"},+ {"role": "user", "content": "Search for data " * 20},+ {+ "role": "assistant",+ "content": "",+ "tool_calls": [+ {+ "id": "c1",+ "type": "function",+ "function": {"name": "search", "arguments": "{}"},+ }+ ],+ },+ {+ "role": "tool",+ "tool_call_id": "c1",+ "content": json.dumps([{"id": i, "data": f"result_{i}"} for i in range(20)]),+ },+ {"role": "assistant", "content": "Here are the results " * 20},+ {"role": "user", "content": "Final"},+ ]++ protected = {0, 5}++ result = summarizer.summarize_messages(+ messages=messages,+ tokenizer=tokenizer,+ protected_indices=protected,+ )++ # Should complete without error+ assert result.messages is not None+ # Protected messages should be preserved+ assert result.messages[0].get("role") == "system"++ def test_summarize_skips_small_token_groups(self, tokenizer: Tokenizer):+ """SUMMARIZE should skip groups with few tokens."""+ from headroom.transforms.progressive_summarizer import ProgressiveSummarizer++ summarizer = ProgressiveSummarizer(+ min_messages_to_summarize=3,+ store_for_retrieval=False,+ )++ # Very short messages+ messages = [+ {"role": "system", "content": "S"},+ {"role": "user", "content": "Q1"},+ {"role": "assistant", "content": "A1"},+ {"role": "user", "content": "Q2"},+ {"role": "assistant", "content": "A2"},+ {"role": "user", "content": "F"},+ ]++ protected = {0, 5}++ result = summarizer.summarize_messages(+ messages=messages,+ tokenizer=tokenizer,+ protected_indices=protected,+ )++ # Should not create summaries (groups too small token-wise)+ # The summarizer checks for group_tokens < 100+ assert len(result.summaries_created) == 0++ def test_summarize_callback_exception_handled(self, tokenizer: Tokenizer):+ """SUMMARIZE should handle callback exceptions gracefully."""+ from headroom.transforms.progressive_summarizer import ProgressiveSummarizer++ def failing_summarizer(messages: list[dict], context: str = "") -> str:+ raise ValueError("Summarization failed!")++ summarizer = ProgressiveSummarizer(+ summarize_fn=failing_summarizer,+ min_messages_to_summarize=3,+ store_for_retrieval=False,+ )++ messages = [+ {"role": "system", "content": "System"},+ {"role": "user", "content": "Q " * 50},+ {"role": "assistant", "content": "A " * 50},+ {"role": "user", "content": "Q2 " * 50},+ {"role": "assistant", "content": "A2 " * 50},+ {"role": "user", "content": "Final"},+ ]++ protected = {0, 5}++ # Should not raise, should return original messages+ result = summarizer.summarize_messages(+ messages=messages,+ tokenizer=tokenizer,+ protected_indices=protected,+ )++ assert result.messages is not None+ # No summaries created due to exception+ assert len(result.summaries_created) == 0