loom-agent 0.0.4__py3-none-any.whl → 0.0.5__py3-none-any.whl

loom/core/agent_executor.py

@@ -20,6 +20,7 @@ from loom.core.context_assembly import ComponentPriority, ContextAssembler
 from loom.core.events import AgentEvent, AgentEventType, ToolResult
 from loom.core.execution_context import ExecutionContext
 from loom.core.permissions import PermissionManager
+from loom.core.recursion_control import RecursionMonitor, RecursionState
 from loom.core.steering_control import SteeringControl
 from loom.core.tool_orchestrator import ToolOrchestrator
 from loom.core.tool_pipeline import ToolExecutionPipeline
@@ -127,6 +128,9 @@ class AgentExecutor:
         task_handlers: Optional[List[TaskHandler]] = None,
         unified_context: Optional["UnifiedExecutionContext"] = None,
         enable_unified_coordination: bool = True,
+        # Phase 2: Recursion Control
+        enable_recursion_control: bool = True,
+        recursion_monitor: Optional[RecursionMonitor] = None,
     ) -> None:
         self.llm = llm
         self.tools = tools or {}
@@ -144,11 +148,17 @@ class AgentExecutor:
         self.callbacks = callbacks or []
         self.enable_steering = enable_steering
         self.task_handlers = task_handlers or []
-        
+
         # Unified coordination
         self.unified_context = unified_context
         self.enable_unified_coordination = enable_unified_coordination
-        
+
+        # Phase 2: Recursion control
+        self.enable_recursion_control = enable_recursion_control
+        self.recursion_monitor = recursion_monitor or RecursionMonitor(
+            max_iterations=max_iterations
+        )
+
         # Initialize unified coordination if enabled
         if self.enable_unified_coordination and UnifiedExecutionContext and IntelligentCoordinator:
             self._setup_unified_coordination()
@@ -301,6 +311,56 @@ class AgentExecutor:
             metadata={"parent_turn_id": turn_state.parent_turn_id},
         )
 
+        # Phase 2: Advanced recursion control (optional)
+        if self.enable_recursion_control:
+            # Build recursion state from turn state
+            recursion_state = RecursionState(
+                iteration=turn_state.turn_counter,
+                tool_call_history=turn_state.tool_call_history,
+                error_count=turn_state.error_count,
+                last_outputs=turn_state.last_outputs
+            )
+
+            # Check for termination conditions
+            termination_reason = self.recursion_monitor.check_termination(
+                recursion_state
+            )
+
+            if termination_reason:
+                # Emit termination event
+                yield AgentEvent(
+                    type=AgentEventType.RECURSION_TERMINATED,
+                    metadata={
+                        "reason": termination_reason.value,
+                        "iteration": turn_state.turn_counter,
+                        "tool_call_history": turn_state.tool_call_history[-5:],
+                        "error_count": turn_state.error_count
+                    }
+                )
+
+                # Add termination message to prompt LLM to finish
+                termination_msg = self.recursion_monitor.build_termination_message(
+                    termination_reason
+                )
+
+                # Add termination guidance as system message
+                messages = messages + [
+                    Message(role="system", content=termination_msg)
+                ]
+
+                # Note: We continue execution but with termination guidance
+                # The LLM will receive the termination message and should wrap up
+
+            # Check for early warnings (not terminating yet, just warning)
+            elif warning_msg := self.recursion_monitor.should_add_warning(
+                recursion_state,
+                warning_threshold=0.8
+            ):
+                # Add warning as system message
+                messages = messages + [
+                    Message(role="system", content=warning_msg)
+                ]
+
         # Base case 1: Maximum recursion depth reached
         if turn_state.is_final:
             yield AgentEvent(
@@ -581,22 +641,37 @@ class AgentExecutor:
         # Phase 5: Recursive Call (Tail Recursion)
         # ==========================================
 
-        # Prepare next turn state
-        next_state = turn_state.next_turn(compacted=compacted_this_turn)
+        # Phase 2: Track tool calls and errors for recursion control
+        tool_names_called = [tc.name for tc in tc_models]
+        had_tool_errors = any(r.is_error for r in tool_results)
+
+        # Extract output for loop detection (use first tool result or content)
+        output_sample = None
+        if tool_results:
+            output_sample = tool_results[0].content[:200]  # First 200 chars
+        elif content:
+            output_sample = content[:200]
+
+        # Prepare next turn state with recursion tracking
+        next_state = turn_state.next_turn(
+            compacted=compacted_this_turn,
+            tool_calls=tool_names_called,
+            had_error=had_tool_errors,
+            output=output_sample
+        )
 
-        # Prepare next turn messages with intelligent context guidance
-        next_messages = self._prepare_recursive_messages(
+        # Phase 3: Prepare next turn messages with intelligent context guidance
+        # This now includes tool results, compression, and recursion hints
+        next_messages = await self._prepare_recursive_messages(
             messages, tool_results, turn_state, context
         )
-        
-        # Add tool results
-        for r in tool_results:
-            next_messages.append(
-                Message(
-                    role="tool",
-                    content=r.content,
-                    tool_call_id=r.tool_call_id,
-                )
+
+        # Check if compression was applied and emit event
+        if "last_compression" in context.metadata:
+            comp_info = context.metadata.pop("last_compression")
+            yield AgentEvent(
+                type=AgentEventType.COMPRESSION_APPLIED,
+                metadata=comp_info
             )
 
         # Emit recursion event
@@ -606,6 +681,8 @@ class AgentExecutor:
                 "from_turn": turn_state.turn_id,
                 "to_turn": next_state.turn_id,
                 "depth": next_state.turn_counter,
+                "tools_called": tool_names_called,
+                "message_count": len(next_messages),
             },
         )
 
@@ -617,7 +694,7 @@ class AgentExecutor:
     # Intelligent Recursion Methods
     # ==========================================
 
-    def _prepare_recursive_messages(
+    async def _prepare_recursive_messages(
         self,
         messages: List[Message],
         tool_results: List[ToolResult],
@@ -625,22 +702,131 @@ class AgentExecutor:
         context: ExecutionContext,
     ) -> List[Message]:
         """
-        智能准备递归调用的消息
-        
-        基于工具结果类型、任务上下文和递归深度，生成合适的用户指导消息
+        Phase 3: 智能准备递归调用的消息
+
+        确保工具结果正确传递到下一轮，并进行必要的上下文优化
+
+        Args:
+            messages: 当前轮次的消息
+            tool_results: 工具执行结果
+            turn_state: 当前轮次状态
+            context: 执行上下文
+
+        Returns:
+            准备好的下一轮消息列表
         """
-        # 分析工具结果
+        # 1. 分析工具结果（用于生成智能指导）
         result_analysis = self._analyze_tool_results(tool_results)
-        
-        # 获取原始任务
         original_task = self._extract_original_task(messages)
-        
-        # 生成智能指导消息
+
+        # 2. 生成智能指导消息
         guidance_message = self._generate_recursion_guidance(
             original_task, result_analysis, turn_state.turn_counter
         )
-        
-        return [Message(role="user", content=guidance_message)]
+
+        # 3. 构建下一轮消息：用户指导
+        next_messages = [Message(role="user", content=guidance_message)]
+
+        # 4. 添加工具结果消息（关键：确保工具结果被传递）
+        for result in tool_results:
+            next_messages.append(Message(
+                role="tool",
+                content=result.content,
+                tool_call_id=result.tool_call_id,
+                metadata=result.metadata or {}
+            ))
+
+        # 5. Phase 3: 检查上下文长度
+        estimated_tokens = self._estimate_tokens(next_messages)
+        compression_applied = False
+
+        if estimated_tokens > self.max_context_tokens:
+            # 触发压缩（如果有 compressor）
+            if self.compressor:
+                tokens_before = estimated_tokens
+                next_messages = await self._compress_messages(next_messages)
+                tokens_after = self._estimate_tokens(next_messages)
+                compression_applied = True
+
+                # Store compression info for later emission
+                context.metadata["last_compression"] = {
+                    "tokens_before": tokens_before,
+                    "tokens_after": tokens_after,
+                    "trigger": "recursive_message_preparation"
+                }
+
+        # 6. Phase 3: 添加递归深度提示（深度递归时）
+        if turn_state.turn_counter > 3:
+            hint_content = self._build_recursion_hint(
+                turn_state.turn_counter,
+                turn_state.max_iterations
+            )
+
+            hint = Message(
+                role="system",
+                content=hint_content
+            )
+            next_messages.append(hint)
+
+        return next_messages
+
+    def _estimate_tokens(self, messages: List[Message]) -> int:
+        """
+        估算消息列表的 token 数量
+
+        使用简单的启发式方法：字符数 / 4
+        生产环境中应使用具体模型的 tokenizer
+        """
+        return count_messages_tokens(messages)
+
+    async def _compress_messages(
+        self,
+        messages: List[Message]
+    ) -> List[Message]:
+        """
+        压缩消息列表（如果有 compressor）
+
+        这个方法会调用配置的 compressor 来减少上下文长度
+        """
+        if not self.compressor:
+            return messages
+
+        try:
+            compressed, metadata = await self.compressor.compress(messages)
+
+            # Update compression metrics
+            self.metrics.metrics.compressions = (
+                getattr(self.metrics.metrics, "compressions", 0) + 1
+            )
+
+            return compressed
+        except Exception as e:
+            # If compression fails, return original messages
+            self.metrics.metrics.total_errors += 1
+            await self._emit(
+                "error",
+                {"stage": "message_compression", "message": str(e)}
+            )
+            return messages
+
+    def _build_recursion_hint(self, current_depth: int, max_depth: int) -> str:
+        """
+        构建递归深度提示消息
+
+        在深度递归时提醒 LLM 注意进度和避免重复
+        """
+        remaining = max_depth - current_depth
+        progress = (current_depth / max_depth) * 100
+
+        hint = f"""🔄 Recursion Status:
+- Depth: {current_depth}/{max_depth} ({progress:.0f}% of maximum)
+- Remaining iterations: {remaining}
+
+Please review the tool results above and make meaningful progress towards completing the task.
+Avoid calling the same tool repeatedly with the same arguments unless necessary.
+If you have enough information, please provide your final answer."""
+
+        return hint
 
     def _analyze_tool_results(self, tool_results: List[ToolResult]) -> Dict[str, Any]:
         """分析工具结果类型和质量"""

loom/core/events.py

@@ -114,6 +114,9 @@ class AgentEventType(Enum):
     RECURSION = "recursion"
     """Recursive call initiated (tt mode)"""
 
+    RECURSION_TERMINATED = "recursion_terminated"
+    """Recursion terminated due to loop detection or limits (Phase 2 optimization)"""
+
     AGENT_FINISH = "agent_finish"
     """Agent execution finished successfully"""
 

loom/core/recursion_control.py

@@ -0,0 +1,298 @@
+"""
+Recursion Control for Agent Executor
+
+Provides generic recursion termination detection to prevent infinite loops
+in agent execution. This is a framework-level capability that doesn't depend
+on specific business logic.
+
+New in Loom 0.0.4: Phase 2 - Execution Layer Optimization
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional, Any
+
+
+class TerminationReason(str, Enum):
+    """Reasons for terminating recursive execution"""
+
+    MAX_ITERATIONS = "max_iterations"
+    """Maximum iteration limit reached"""
+
+    DUPLICATE_TOOLS = "duplicate_tools"
+    """Detected repeated tool calls (same tool called multiple times in a row)"""
+
+    LOOP_DETECTED = "loop_detected"
+    """Detected a pattern loop in outputs"""
+
+    ERROR_THRESHOLD = "error_threshold"
+    """Error rate exceeded acceptable threshold"""
+
+
+@dataclass
+class RecursionState:
+    """
+    State information for recursion monitoring.
+
+    This is a separate state object from TurnState to avoid coupling
+    the recursion control logic with the turn management logic.
+
+    Attributes:
+        iteration: Current iteration count (0-based)
+        tool_call_history: List of tool names called in recent iterations
+        error_count: Number of errors encountered so far
+        last_outputs: Recent output samples for loop detection
+    """
+
+    iteration: int
+    """Current iteration count (0-based)"""
+
+    tool_call_history: List[str]
+    """History of tool names called (for duplicate detection)"""
+
+    error_count: int
+    """Number of errors encountered during execution"""
+
+    last_outputs: List[Any]
+    """Recent outputs for loop pattern detection"""
+
+
+class RecursionMonitor:
+    """
+    Generic recursion monitoring and termination detection.
+
+    This monitor provides framework-level recursion control without
+    depending on any specific business logic. It detects common
+    infinite loop patterns:
+
+    1. Maximum iteration limit
+    2. Repeated tool calls (same tool called N times in a row)
+    3. Loop patterns in outputs
+    4. High error rates
+
+    Example:
+        ```python
+        # Create monitor with custom thresholds
+        monitor = RecursionMonitor(
+            max_iterations=50,
+            duplicate_threshold=3,
+            loop_detection_window=5,
+            error_threshold=0.5
+        )
+
+        # Check if should terminate
+        state = RecursionState(
+            iteration=10,
+            tool_call_history=["search", "search", "search"],
+            error_count=2,
+            last_outputs=[]
+        )
+
+        reason = monitor.check_termination(state)
+        if reason:
+            message = monitor.build_termination_message(reason)
+            print(f"Terminating: {message}")
+        ```
+    """
+
+    def __init__(
+        self,
+        max_iterations: int = 50,
+        duplicate_threshold: int = 3,
+        loop_detection_window: int = 5,
+        error_threshold: float = 0.5
+    ):
+        """
+        Initialize recursion monitor.
+
+        Args:
+            max_iterations: Maximum number of recursive iterations allowed
+            duplicate_threshold: Number of consecutive duplicate tool calls before terminating
+            loop_detection_window: Window size for loop pattern detection
+            error_threshold: Maximum error rate (errors/iterations) before terminating
+        """
+        self.max_iterations = max_iterations
+        self.duplicate_threshold = duplicate_threshold
+        self.loop_detection_window = loop_detection_window
+        self.error_threshold = error_threshold
+
+    def check_termination(
+        self,
+        state: RecursionState
+    ) -> Optional[TerminationReason]:
+        """
+        Check if recursive execution should terminate.
+
+        This method runs multiple checks in priority order:
+        1. Max iterations (highest priority - hard limit)
+        2. Duplicate tool calls (likely stuck)
+        3. Loop patterns (repeating behavior)
+        4. Error threshold (too many failures)
+
+        Args:
+            state: Current recursion state
+
+        Returns:
+            TerminationReason if should terminate, None to continue
+        """
+        # Check 1: Maximum iterations (hard limit)
+        if state.iteration >= self.max_iterations:
+            return TerminationReason.MAX_ITERATIONS
+
+        # Check 2: Duplicate tool calls (likely stuck)
+        if self._detect_duplicate_tools(state.tool_call_history):
+            return TerminationReason.DUPLICATE_TOOLS
+
+        # Check 3: Loop patterns in outputs
+        if self._detect_loop_pattern(state.last_outputs):
+            return TerminationReason.LOOP_DETECTED
+
+        # Check 4: Error rate threshold
+        if self._check_error_threshold(state):
+            return TerminationReason.ERROR_THRESHOLD
+
+        return None
+
+    def _detect_duplicate_tools(self, tool_history: List[str]) -> bool:
+        """
+        Detect if the same tool has been called too many times in a row.
+
+        This indicates the agent is stuck in a loop, repeatedly trying
+        the same tool without making progress.
+
+        Args:
+            tool_history: List of tool names (most recent last)
+
+        Returns:
+            True if duplicate pattern detected
+        """
+        if len(tool_history) < self.duplicate_threshold:
+            return False
+
+        # Check last N tool calls
+        recent = tool_history[-self.duplicate_threshold:]
+
+        # All the same? -> Stuck in loop
+        return len(set(recent)) == 1
+
+    def _detect_loop_pattern(self, outputs: List[Any]) -> bool:
+        """
+        Detect if outputs are repeating in a pattern.
+
+        This checks if the agent is generating the same outputs
+        repeatedly, indicating a stuck state.
+
+        Args:
+            outputs: Recent output values
+
+        Returns:
+            True if loop pattern detected
+        """
+        if len(outputs) < self.loop_detection_window * 2:
+            return False
+
+        window_size = self.loop_detection_window
+        recent = outputs[-window_size * 2:]
+
+        # Split into two halves and compare
+        first_half = recent[:window_size]
+        second_half = recent[window_size:]
+
+        # If both halves are identical, we have a loop
+        return first_half == second_half
+
+    def _check_error_threshold(self, state: RecursionState) -> bool:
+        """
+        Check if error rate exceeds acceptable threshold.
+
+        Too many errors indicate the agent cannot complete the task
+        and should stop trying.
+
+        Args:
+            state: Current recursion state
+
+        Returns:
+            True if error rate exceeds threshold
+        """
+        if state.iteration == 0:
+            return False
+
+        error_rate = state.error_count / state.iteration
+        return error_rate > self.error_threshold
+
+    def build_termination_message(
+        self,
+        reason: TerminationReason
+    ) -> str:
+        """
+        Build a user-friendly termination message.
+
+        This message is injected into the conversation to prompt
+        the LLM to complete the task with available information.
+
+        Args:
+            reason: The termination reason
+
+        Returns:
+            Formatted termination message
+        """
+        messages = {
+            TerminationReason.DUPLICATE_TOOLS: (
+                "⚠️ Detected repeated tool calls. "
+                "Please proceed with available information."
+            ),
+            TerminationReason.LOOP_DETECTED: (
+                "⚠️ Detected execution loop. "
+                "Please break the pattern and complete the task."
+            ),
+            TerminationReason.MAX_ITERATIONS: (
+                "⚠️ Maximum iterations reached. "
+                "Please provide the best answer with current information."
+            ),
+            TerminationReason.ERROR_THRESHOLD: (
+                "⚠️ Too many errors occurred. "
+                "Please complete the task with current information."
+            )
+        }
+
+        return messages.get(reason, "Please complete the task now.")
+
+    def should_add_warning(
+        self,
+        state: RecursionState,
+        warning_threshold: float = 0.8
+    ) -> Optional[str]:
+        """
+        Check if a warning should be added before termination.
+
+        This provides early warning when approaching limits,
+        giving the agent a chance to wrap up gracefully.
+
+        Args:
+            state: Current recursion state
+            warning_threshold: Fraction of limit at which to warn (0.0-1.0)
+
+        Returns:
+            Warning message if applicable, None otherwise
+        """
+        # Check if approaching max iterations
+        progress = state.iteration / self.max_iterations
+        if progress >= warning_threshold:
+            remaining = self.max_iterations - state.iteration
+            return (
+                f"⚠️ Approaching iteration limit ({remaining} remaining). "
+                f"Please work towards completing the task."
+            )
+
+        # Check if tool calls are becoming repetitive
+        if len(state.tool_call_history) >= self.duplicate_threshold - 1:
+            recent = state.tool_call_history[-(self.duplicate_threshold - 1):]
+            if len(set(recent)) == 1:
+                return (
+                    f"⚠️ You've called '{recent[0]}' multiple times. "
+                    f"Consider trying a different approach or completing the task."
+                )
+
+        return None