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

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

loom/core/turn_state.py

@@ -8,7 +8,7 @@ Inspired by Claude Code's recursive conversation management.
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Dict, Any, Optional
+from typing import Dict, Any, Optional, List
 from uuid import uuid4
 
 
@@ -32,6 +32,9 @@ class TurnState:
         compacted: Whether conversation history was compacted this turn
         parent_turn_id: ID of the parent turn (None for initial turn)
         metadata: Additional turn-specific data
+        tool_call_history: History of tool names called (for recursion control)
+        error_count: Number of errors encountered (for recursion control)
+        last_outputs: Recent outputs for loop detection (for recursion control)
 
     Example:
         ```python
@@ -54,6 +57,16 @@ class TurnState:
     parent_turn_id: Optional[str] = None
     metadata: Dict[str, Any] = field(default_factory=dict)
 
+    # Phase 2: Recursion control tracking
+    tool_call_history: List[str] = field(default_factory=list)
+    """History of tool names called (for recursion control)"""
+
+    error_count: int = 0
+    """Number of errors encountered during execution"""
+
+    last_outputs: List[str] = field(default_factory=list)
+    """Recent outputs for loop detection (limited to last 10)"""
+
     @staticmethod
     def initial(max_iterations: int = 10, **metadata) -> TurnState:
         """
@@ -75,7 +88,14 @@ class TurnState:
             metadata=metadata
         )
 
-    def next_turn(self, compacted: bool = False, **metadata_updates) -> TurnState:
+    def next_turn(
+        self,
+        compacted: bool = False,
+        tool_calls: Optional[List[str]] = None,
+        had_error: bool = False,
+        output: Optional[str] = None,
+        **metadata_updates
+    ) -> TurnState:
         """
         Create next turn state (immutable update).
 
@@ -84,6 +104,9 @@ class TurnState:
 
         Args:
             compacted: Whether history was compacted in the next turn
+            tool_calls: New tool calls to add to history
+            had_error: Whether an error occurred in this turn
+            output: Output content to add for loop detection
             **metadata_updates: Updates to metadata (merged with existing)
 
         Returns:
@@ -98,13 +121,33 @@ class TurnState:
         """
         new_metadata = {**self.metadata, **metadata_updates}
 
+        # Update tool call history
+        new_tool_history = list(self.tool_call_history)
+        if tool_calls:
+            new_tool_history.extend(tool_calls)
+        # Keep only last 20 tool calls
+        new_tool_history = new_tool_history[-20:]
+
+        # Update error count
+        new_error_count = self.error_count + (1 if had_error else 0)
+
+        # Update output history for loop detection
+        new_outputs = list(self.last_outputs)
+        if output:
+            new_outputs.append(output)
+        # Keep only last 10 outputs
+        new_outputs = new_outputs[-10:]
+
         return TurnState(
             turn_counter=self.turn_counter + 1,
             turn_id=str(uuid4()),  # New unique ID
             max_iterations=self.max_iterations,
             compacted=compacted,
             parent_turn_id=self.turn_id,  # Link to parent
-            metadata=new_metadata
+            metadata=new_metadata,
+            tool_call_history=new_tool_history,
+            error_count=new_error_count,
+            last_outputs=new_outputs
         )
 
     def with_metadata(self, **kwargs) -> TurnState:
@@ -125,7 +168,10 @@ class TurnState:
             max_iterations=self.max_iterations,
             compacted=self.compacted,
             parent_turn_id=self.parent_turn_id,
-            metadata=new_metadata
+            metadata=new_metadata,
+            tool_call_history=self.tool_call_history,
+            error_count=self.error_count,
+            last_outputs=self.last_outputs
         )
 
     @property
@@ -156,7 +202,10 @@ class TurnState:
             "max_iterations": self.max_iterations,
             "compacted": self.compacted,
             "parent_turn_id": self.parent_turn_id,
-            "metadata": self.metadata
+            "metadata": self.metadata,
+            "tool_call_history": self.tool_call_history,
+            "error_count": self.error_count,
+            "last_outputs": self.last_outputs
         }
 
     @staticmethod
@@ -176,7 +225,10 @@ class TurnState:
             max_iterations=data.get("max_iterations", 10),
             compacted=data.get("compacted", False),
             parent_turn_id=data.get("parent_turn_id"),
-            metadata=data.get("metadata", {})
+            metadata=data.get("metadata", {}),
+            tool_call_history=data.get("tool_call_history", []),
+            error_count=data.get("error_count", 0),
+            last_outputs=data.get("last_outputs", [])
         )
 
     def __repr__(self) -> str:

loom/retrieval/__init__.py

@@ -0,0 +1,61 @@
+"""
+Loom Retrieval Module
+
+Provides embedding-based semantic retrieval with lazy loading and caching.
+
+Key components:
+- EmbeddingRetriever: Core retrieval system using embeddings
+- DomainAdapter: Interface for adapting domain-specific data
+- IndexStrategy: Indexing strategies (EAGER/LAZY/INCREMENTAL)
+- RetrievalConfig: Configuration for retrieval behavior
+
+Example:
+    from loom.retrieval import (
+        EmbeddingRetriever,
+        DomainAdapter,
+        IndexStrategy,
+        RetrievalConfig
+    )
+    from loom.builtin.embeddings import OpenAIEmbedding
+    from loom.builtin.retriever import FAISSVectorStore
+
+    # Create retriever
+    retriever = EmbeddingRetriever(
+        embedding=OpenAIEmbedding(model="text-embedding-3-small"),
+        vector_store=FAISSVectorStore(dimension=1536),
+        domain_adapter=my_adapter,
+        config=RetrievalConfig(
+            index_strategy=IndexStrategy.LAZY,
+            top_k=5
+        )
+    )
+
+    # Initialize
+    await retriever.initialize()
+
+    # Retrieve
+    results = await retriever.retrieve("user query", top_k=5)
+"""
+
+from loom.retrieval.embedding_retriever import (
+    EmbeddingRetriever,
+    IndexStrategy,
+    RetrievalConfig
+)
+from loom.retrieval.domain_adapter import (
+    DomainAdapter,
+    SimpleDomainAdapter
+)
+
+__all__ = [
+    # Core classes
+    "EmbeddingRetriever",
+    "DomainAdapter",
+    "SimpleDomainAdapter",
+
+    # Enums
+    "IndexStrategy",
+
+    # Config
+    "RetrievalConfig",
+]

loom/retrieval/domain_adapter.py

@@ -0,0 +1,195 @@
+"""
+Domain Adapter Interface
+
+Defines the interface for adapting domain-specific data to the retrieval system.
+Users implement this interface to support their specific domains (Schema, Code, Docs, etc.)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, List, Optional
+
+from loom.interfaces.retriever import Document
+
+
+class DomainAdapter(ABC):
+    """
+    Domain Adapter Interface
+
+    Adapts domain-specific data to the generic Document format for retrieval.
+    Users implement this interface to support any domain:
+    - SQL Schema
+    - Code repositories
+    - Documentation
+    - API specifications
+    - etc.
+
+    Example:
+        class MySchemaDomainAdapter(DomainAdapter):
+            async def extract_documents(self, source, **kwargs):
+                tables = await self._get_tables()
+                return [
+                    Document(
+                        doc_id=f"table_{table}",
+                        content=f"Table: {table}",
+                        metadata={"table": table}
+                    )
+                    for table in tables
+                ]
+
+            async def load_document_details(self, document_id):
+                table_name = document_id.replace("table_", "")
+                schema = await self._get_table_schema(table_name)
+                return Document(
+                    doc_id=document_id,
+                    content=schema,
+                    metadata={"table": table_name}
+                )
+    """
+
+    @abstractmethod
+    async def extract_documents(
+        self,
+        source: Any = None,
+        metadata_only: bool = False,
+        **kwargs
+    ) -> List[Document]:
+        """
+        Extract documents from the data source
+
+        Args:
+            source: Data source (database connection, file path, etc.)
+            metadata_only: If True, only extract lightweight metadata for lazy loading
+            **kwargs: Domain-specific parameters
+
+        Returns:
+            List of documents
+
+        Example:
+            # Full documents
+            docs = await adapter.extract_documents(source=db_connection)
+
+            # Lightweight metadata only (for lazy loading)
+            docs = await adapter.extract_documents(
+                source=db_connection,
+                metadata_only=True
+            )
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def load_document_details(
+        self,
+        document_id: str,
+        **kwargs
+    ) -> Document:
+        """
+        Lazy load full document details
+
+        Called when lazy loading is enabled and the full document is needed.
+
+        Args:
+            document_id: Document identifier
+            **kwargs: Domain-specific parameters
+
+        Returns:
+            Full document with details
+
+        Example:
+            doc = await adapter.load_document_details("table_users")
+        """
+        raise NotImplementedError
+
+    def format_for_embedding(self, document: Document) -> str:
+        """
+        Format document for embedding generation
+
+        Override this method to customize how documents are formatted
+        for embedding generation.
+
+        Args:
+            document: Document to format
+
+        Returns:
+            Formatted text for embedding
+
+        Default implementation uses document.content
+        """
+        return document.content
+
+    def should_index(self, document: Document) -> bool:
+        """
+        Determine if a document should be indexed
+
+        Override this method to filter documents during indexing.
+
+        Args:
+            document: Document to check
+
+        Returns:
+            True if document should be indexed
+
+        Default implementation indexes all documents
+        """
+        return True
+
+
+class SimpleDomainAdapter(DomainAdapter):
+    """
+    Simple in-memory domain adapter
+
+    Useful for testing and simple use cases where documents are
+    already in memory.
+
+    Example:
+        documents = [
+            Document(doc_id="1", content="Document 1"),
+            Document(doc_id="2", content="Document 2"),
+        ]
+
+        adapter = SimpleDomainAdapter(documents)
+        retriever = EmbeddingRetriever(
+            embedding=...,
+            vector_store=...,
+            domain_adapter=adapter
+        )
+    """
+
+    def __init__(self, documents: List[Document]):
+        """
+        Args:
+            documents: List of documents to index
+        """
+        self.documents = {doc.doc_id: doc for doc in documents}
+
+    async def extract_documents(
+        self,
+        source: Any = None,
+        metadata_only: bool = False,
+        **kwargs
+    ) -> List[Document]:
+        """Extract all documents"""
+        if metadata_only:
+            # Return lightweight versions
+            return [
+                Document(
+                    doc_id=doc.doc_id,
+                    content=doc.content[:100] + "..." if len(doc.content) > 100 else doc.content,
+                    metadata=doc.metadata
+                )
+                for doc in self.documents.values()
+            ]
+        else:
+            return list(self.documents.values())
+
+    async def load_document_details(
+        self,
+        document_id: str,
+        **kwargs
+    ) -> Document:
+        """Load full document"""
+        if document_id not in self.documents:
+            raise ValueError(f"Document not found: {document_id}")
+
+        return self.documents[document_id]