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

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]