agentensemble 0.1.0__py3-none-any.whl

agentensemble/testing/metrics.py

@@ -0,0 +1,81 @@
+"""
+Metrics
+
+Performance metrics for agent evaluation.
+"""
+
+from typing import Any, Dict, List
+
+
+class Metrics:
+    """
+    Metrics calculator for agent performance.
+    
+    Tracks success rate, execution time, cost, etc.
+    """
+    
+    @staticmethod
+    def success_rate(results: List[Dict[str, Any]]) -> float:
+        """
+        Calculate success rate.
+        
+        Args:
+            results: List of result dictionaries
+            
+        Returns:
+            Success rate (0.0 to 1.0)
+        """
+        if not results:
+            return 0.0
+        
+        successful = sum(1 for r in results if r.get("success", False))
+        return successful / len(results)
+    
+    @staticmethod
+    def average_execution_time(results: List[Dict[str, Any]]) -> float:
+        """
+        Calculate average execution time.
+        
+        Args:
+            results: List of result dictionaries
+            
+        Returns:
+            Average execution time in seconds
+        """
+        if not results:
+            return 0.0
+        
+        times = [r.get("execution_time", 0) for r in results]
+        return sum(times) / len(times)
+    
+    @staticmethod
+    def total_cost(results: List[Dict[str, Any]]) -> float:
+        """
+        Calculate total cost.
+        
+        Args:
+            results: List of result dictionaries
+            
+        Returns:
+            Total cost in dollars
+        """
+        return sum(r.get("cost", 0) for r in results)
+    
+    @staticmethod
+    def calculate_all(results: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Calculate all metrics.
+        
+        Args:
+            results: List of result dictionaries
+            
+        Returns:
+            Dictionary with all metrics
+        """
+        return {
+            "success_rate": Metrics.success_rate(results),
+            "average_execution_time": Metrics.average_execution_time(results),
+            "total_cost": Metrics.total_cost(results),
+            "total_tests": len(results),
+        }
+

agentensemble/tools/__init__.py

@@ -0,0 +1,20 @@
+"""
+Tool Ecosystem
+
+Provides built-in tools and tool registry for agent use.
+All tools integrate with LangChain community tools.
+"""
+
+from agentensemble.tools.registry import ToolRegistry
+from agentensemble.tools.search import SearchTool
+from agentensemble.tools.scraper import ScraperTool
+from agentensemble.tools.rag import RAGTool
+from agentensemble.tools.validator import ValidationTool
+
+__all__ = [
+    "ToolRegistry",
+    "SearchTool",
+    "ScraperTool",
+    "RAGTool",
+    "ValidationTool",
+]

agentensemble/tools/rag.py

@@ -0,0 +1,226 @@
+"""
+RAG Tool
+
+Retrieval-Augmented Generation tool following LangChain RAG patterns.
+Based on: https://docs.langchain.com/oss/python/langchain/rag
+
+Supports:
+- Agentic RAG: Tool-based retrieval for iterative queries
+- RAG Chain: Two-step chain with single LLM call
+"""
+
+from typing import Any, List, Optional, Tuple
+
+import os
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+try:
+    from langchain_community.document_loaders import WebBaseLoader
+    from langchain_community.vectorstores import Chroma
+    from langchain_core.vectorstores import InMemoryVectorStore
+    from langchain_mistralai import MistralAIEmbeddings
+    from langchain_core.documents import Document
+    from langchain_text_splitters import RecursiveCharacterTextSplitter
+    from langchain_core.tools import tool
+
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+    LANGCHAIN_AVAILABLE = False
+    WebBaseLoader = None
+    Chroma = None
+    InMemoryVectorStore = None
+    MistralAIEmbeddings = None
+    Document = None
+    RecursiveCharacterTextSplitter = None
+    tool = None
+
+
+class RAGTool:
+    """
+    RAG tool following LangChain RAG patterns.
+
+    Implements both:
+    1. Agentic RAG: Tool-based retrieval (as per LangChain tutorial)
+    2. RAG Chain: Two-step chain with single LLM call
+
+    Based on: https://docs.langchain.com/oss/python/langchain/rag
+    """
+
+    def __init__(
+        self,
+        vector_store: Optional[Any] = None,
+        embeddings: Optional[Any] = None,
+        chunk_size: int = 1000,
+        chunk_overlap: int = 200,
+        fallback_strategies: int = 3,
+        **kwargs,
+    ):
+        """
+        Initialize RAG tool.
+
+        Args:
+            vector_store: Pre-initialized vector store (or None to create one)
+            embeddings: Pre-initialized embeddings model (or None to use Mistral)
+            chunk_size: Size of text chunks for splitting
+            chunk_overlap: Overlap between chunks
+            fallback_strategies: Number of fallback query variations
+            **kwargs: Additional configuration
+        """
+        self.name = "rag"
+        self.vector_store = vector_store
+        self.embeddings = embeddings
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.fallback_strategies = fallback_strategies
+        self.config = kwargs
+        self._text_splitter: Optional[Any] = None
+
+    def _initialize_components(self) -> None:
+        """Initialize text splitter and ensure embeddings/vector store exist"""
+        if not LANGCHAIN_AVAILABLE:
+            raise ImportError(
+                "langchain-community, langchain-mistralai, and langchain-text-splitters "
+                "are required for RAGTool. Install with: "
+                "pip install langchain-community langchain-mistralai langchain-text-splitters"
+            )
+
+        # Initialize text splitter (as per LangChain RAG tutorial)
+        if not self._text_splitter and RecursiveCharacterTextSplitter:
+            self._text_splitter = RecursiveCharacterTextSplitter(
+                chunk_size=self.chunk_size, chunk_overlap=self.chunk_overlap
+            )
+
+        # Initialize embeddings if not provided (using Mistral)
+        if not self.embeddings and MistralAIEmbeddings:
+            from agentensemble.utils.llm import get_mistral_embeddings
+
+            self.embeddings = get_mistral_embeddings()
+
+        # Initialize vector store if not provided
+        if not self.vector_store:
+            if InMemoryVectorStore and self.embeddings:
+                self.vector_store = InMemoryVectorStore(self.embeddings)
+
+    def index_documents(self, urls: List[str]) -> None:
+        """
+        Index documents from URLs (following LangChain RAG tutorial pattern).
+
+        This implements the indexing pipeline:
+        1. Load documents with WebBaseLoader
+        2. Split with RecursiveCharacterTextSplitter
+        3. Store in vector store
+
+        Args:
+            urls: List of URLs to load and index
+        """
+        if not LANGCHAIN_AVAILABLE or not WebBaseLoader:
+            raise ImportError("langchain-community required for indexing")
+
+        self._initialize_components()
+
+        # Load documents (as per LangChain tutorial)
+        documents = []
+        for url in urls:
+            try:
+                loader = WebBaseLoader(web_paths=(url,))
+                docs = loader.load()
+                documents.extend(docs)
+            except Exception as e:
+                print(f"Warning: Failed to load {url}: {e}")
+
+        if not documents:
+            return
+
+        # Split documents (as per LangChain tutorial)
+        if self._text_splitter:
+            all_splits = self._text_splitter.split_documents(documents)
+        else:
+            all_splits = documents
+
+        # Store in vector store (as per LangChain tutorial)
+        if self.vector_store:
+            self.vector_store.add_documents(documents=all_splits)
+
+    def create_retrieval_tool(self):
+        """
+        Create a LangChain tool for retrieval (following LangChain RAG tutorial).
+
+        Returns a tool decorated with @tool that can be used with create_agent.
+
+        Returns:
+            LangChain tool instance
+        """
+        if not LANGCHAIN_AVAILABLE or not tool:
+            raise ImportError("langchain required for tool creation")
+
+        if not self.vector_store:
+            raise ValueError("Vector store must be initialized. Call index_documents() first.")
+
+        # Create retrieval tool following LangChain RAG tutorial pattern
+        @tool(response_format="content_and_artifact")
+        def retrieve_context(query: str):
+            """Retrieve information to help answer a query."""
+            retrieved_docs = self.vector_store.similarity_search(query, k=2)
+            serialized = "\n\n".join(
+                (f"Source: {doc.metadata}\nContent: {doc.page_content}") for doc in retrieved_docs
+            )
+            return serialized, retrieved_docs
+
+        return retrieve_context
+
+    def retrieve(self, query: str, k: int = 2) -> Tuple[str, List[Document]]:
+        """
+        Retrieve context for a query (following LangChain RAG tutorial pattern).
+
+        Args:
+            query: Search query
+            k: Number of documents to retrieve
+
+        Returns:
+            Tuple of (serialized context, retrieved documents)
+        """
+        if not self.vector_store:
+            raise ValueError("Vector store not initialized. Call index_documents() first.")
+
+        retrieved_docs = self.vector_store.similarity_search(query, k=k)
+        serialized = "\n\n".join(
+            (f"Source: {doc.metadata}\nContent: {doc.page_content}") for doc in retrieved_docs
+        )
+        return serialized, retrieved_docs
+
+    def run(self, question: str, urls: Optional[List[str]] = None, **kwargs) -> str:
+        """
+        Execute RAG query (simple interface for backward compatibility).
+
+        For full LangChain RAG patterns, use:
+        - create_retrieval_tool() for agentic RAG
+        - retrieve() for direct retrieval
+
+        Args:
+            question: Question to answer
+            urls: Optional URLs to index first
+            **kwargs: Additional parameters
+
+        Returns:
+            Retrieved context
+        """
+        if not LANGCHAIN_AVAILABLE:
+            return f"RAG answer to '{question}' [langchain-community required]"
+
+        # If URLs provided, index them first
+        if urls:
+            self.index_documents(urls)
+
+        # Retrieve context
+        if self.vector_store:
+            context, docs = self.retrieve(question, k=3)
+            return context
+
+        return f"RAG answer to '{question}' [index documents first with index_documents()]"
+
+    def __call__(self, question: str, urls: Optional[List[str]] = None, **kwargs) -> str:
+        """Make tool callable"""
+        return self.run(question, urls, **kwargs)

agentensemble/tools/registry.py

@@ -0,0 +1,83 @@
+"""
+Tool Registry
+
+Centralized tool management for agents.
+"""
+
+from typing import Any, Dict, List, Optional
+
+
+class ToolRegistry:
+    """
+    Registry for managing and organizing tools.
+    
+    Provides centralized tool discovery and management.
+    """
+    
+    def __init__(self):
+        """Initialize tool registry"""
+        self._tools: Dict[str, Any] = {}
+    
+    def register(self, tool: Any, name: Optional[str] = None) -> None:
+        """
+        Register a tool.
+        
+        Args:
+            tool: Tool instance
+            name: Optional name (uses tool.name if available)
+        """
+        tool_name = name or getattr(tool, "name", f"tool_{len(self._tools)}")
+        self._tools[tool_name] = tool
+    
+    def register_many(self, tools: List[Any]) -> None:
+        """
+        Register multiple tools.
+        
+        Args:
+            tools: List of tool instances
+        """
+        for tool in tools:
+            self.register(tool)
+    
+    def get_tool(self, name: str) -> Any:
+        """
+        Get a tool by name.
+        
+        Args:
+            name: Tool name
+            
+        Returns:
+            Tool instance
+        """
+        if name not in self._tools:
+            raise ValueError(f"Tool '{name}' not found in registry")
+        return self._tools[name]
+    
+    def get_tools(self) -> List[Any]:
+        """
+        Get all registered tools.
+        
+        Returns:
+            List of all tools
+        """
+        return list(self._tools.values())
+    
+    def list_tools(self) -> List[str]:
+        """
+        List all tool names.
+        
+        Returns:
+            List of tool names
+        """
+        return list(self._tools.keys())
+    
+    def unregister(self, name: str) -> None:
+        """
+        Unregister a tool.
+        
+        Args:
+            name: Tool name
+        """
+        if name in self._tools:
+            del self._tools[name]
+

agentensemble/tools/scraper.py

@@ -0,0 +1,123 @@
+"""
+Scraper Tool
+
+Web scraping functionality for agents using LangChain community tools.
+"""
+
+from typing import Any, Optional
+
+try:
+    from langchain_community.tools import (
+        DuckDuckGoSearchRun,
+    )
+    from langchain_community.tools.playwright import (
+        ClickTool,
+        ExtractHyperlinksTool,
+        GetElementsTool,
+        NavigateTool,
+        NavigateBackTool,
+    )
+    from langchain_core.tools import BaseTool
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+    LANGCHAIN_AVAILABLE = False
+    BaseTool = object
+
+
+class ScraperTool:
+    """
+    Web scraping tool for agents using LangChain community tools.
+
+    Supports:
+    - Playwright-based scraping (requires playwright)
+    - Simple URL fetching
+    """
+
+    def __init__(
+        self,
+        provider: str = "simple",
+        api_key: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Initialize scraper tool.
+
+        Args:
+            provider: Scraping provider ("simple", "playwright")
+            api_key: API key (not currently used, reserved for future)
+            **kwargs: Additional configuration
+        """
+        self.name = "scraper"
+        self.provider = provider
+        self.api_key = api_key
+        self._navigate_tool: Optional[BaseTool] = None
+        self._initialize_tool()
+
+    def _initialize_tool(self) -> None:
+        """Initialize the underlying LangChain tool"""
+        if not LANGCHAIN_AVAILABLE:
+            raise ImportError(
+                "langchain-community is required for ScraperTool. "
+                "Install with: pip install langchain-community"
+            )
+
+        if self.provider == "playwright":
+            try:
+                self._navigate_tool = NavigateTool()
+            except Exception as e:
+                raise ImportError(
+                    "Playwright tools require playwright. "
+                    "Install with: pip install playwright && playwright install"
+                ) from e
+        elif self.provider == "simple":
+            # Simple HTTP-based scraping (placeholder for now)
+            # In production, integrate with requests/httpx
+            self._navigate_tool = None
+        else:
+            raise ValueError(
+                f"Unknown provider: {self.provider}. "
+                "Supported: 'simple', 'playwright'"
+            )
+
+    def run(self, url: str, question: Optional[str] = None, **kwargs) -> str:
+        """
+        Scrape a URL and optionally answer a question.
+
+        Args:
+            url: URL to scrape
+            question: Optional question to answer from scraped content
+            **kwargs: Additional parameters
+
+        Returns:
+            Scraped content or answer
+        """
+        if self.provider == "playwright" and self._navigate_tool:
+            # Use Playwright navigation tool
+            try:
+                result = self._navigate_tool.invoke({"url": url})
+                content = str(result)
+                if question:
+                    # In production, use LLM to answer question from content
+                    return f"Answer to '{question}' from {url}: {content[:500]}..."
+                return content
+            except Exception as e:
+                return f"Error scraping {url}: {str(e)}"
+        else:
+            # Simple placeholder - in production, use httpx/requests
+            if question:
+                return f"Answer to '{question}' from {url}: [scraped content - install playwright for full functionality]"
+            return f"Scraped content from {url} [install playwright for full functionality]"
+
+    def __call__(self, url: str, question: Optional[str] = None, **kwargs) -> str:
+        """Make tool callable"""
+        return self.run(url, question, **kwargs)
+
+    def as_langchain_tool(self) -> Optional[BaseTool]:
+        """
+        Return the underlying LangChain tool for direct use.
+
+        Returns:
+            LangChain BaseTool instance or None
+        """
+        return self._navigate_tool
+

agentensemble/tools/search.py

@@ -0,0 +1,155 @@
+"""
+Search Tool
+
+Web search functionality for agents using LangChain community tools.
+Defaults to Serper API if API key is available, otherwise falls back to DuckDuckGo.
+"""
+
+import os
+from typing import Any, Optional
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+try:
+    from langchain_community.tools import (
+        DuckDuckGoSearchRun,
+        DuckDuckGoSearchResults,
+    )
+
+    # Optional: Serper API (requires API key) - only import if needed
+    try:
+        from langchain_community.utilities import GoogleSerperAPIWrapper
+        from langchain_core.tools import Tool
+
+        SERPER_AVAILABLE = True
+    except ImportError:
+        SERPER_AVAILABLE = False
+        GoogleSerperAPIWrapper = None
+        Tool = None
+    from langchain_core.tools import BaseTool
+
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+    LANGCHAIN_AVAILABLE = False
+    BaseTool = object
+    SERPER_AVAILABLE = False
+    GoogleSerperAPIWrapper = None
+    Tool = None
+
+
+class SearchTool:
+    """
+    Web search tool for agents using LangChain community tools.
+
+    **Default: Serper API** (if SERPER_API_KEY is in .env)
+    **Fallback: DuckDuckGo** (free, open-source, no API key required)
+
+    Supports multiple providers:
+    - Serper API (default if API key available, requires SERPER_API_KEY in .env)
+    - DuckDuckGo (fallback, free, open-source, no API key required) ⭐
+    - DuckDuckGo Results (structured results, free)
+    """
+
+    def __init__(self, provider: Optional[str] = None, api_key: Optional[str] = None, **kwargs):
+        """
+        Initialize search tool.
+
+        Args:
+            provider: Search provider
+                - None (auto-detect: Serper if API key available, else DuckDuckGo)
+                - "serper" (requires SERPER_API_KEY in .env or api_key parameter)
+                - "duckduckgo" (free, open-source) ⭐
+                - "duckduckgo_results" (structured results, free)
+            api_key: API key for Serper (defaults to SERPER_API_KEY from .env)
+            **kwargs: Additional configuration
+        """
+        self.name = "search"
+
+        # Auto-detect provider if not specified
+        if provider is None:
+            serper_key = api_key or os.getenv("SERPER_API_KEY")
+            if serper_key and SERPER_AVAILABLE:
+                provider = "serper"
+            else:
+                provider = "duckduckgo"
+
+        self.provider = provider
+        # Use provided api_key or get from environment
+        self.api_key = api_key or os.getenv("SERPER_API_KEY")
+        self._tool: Optional[BaseTool] = None
+        self._initialize_tool()
+
+    def _initialize_tool(self) -> None:
+        """Initialize the underlying LangChain tool"""
+        if not LANGCHAIN_AVAILABLE:
+            raise ImportError(
+                "langchain-community is required for SearchTool. "
+                "Install with: pip install langchain-community"
+            )
+
+        if self.provider == "serper":
+            if not SERPER_AVAILABLE or not GoogleSerperAPIWrapper:
+                # Fallback to DuckDuckGo if Serper not available
+                print("Warning: Serper API not available, falling back to DuckDuckGo")
+                self.provider = "duckduckgo"
+                self._tool = DuckDuckGoSearchRun()
+                return
+
+            if not self.api_key:
+                # Fallback to DuckDuckGo if no API key
+                print("Warning: SERPER_API_KEY not found, falling back to DuckDuckGo")
+                self.provider = "duckduckgo"
+                self._tool = DuckDuckGoSearchRun()
+                return
+
+            # Create Serper API tool
+            serper = GoogleSerperAPIWrapper(serper_api_key=self.api_key)
+            self._tool = Tool(
+                name="serper_search", description="Search the web using Serper API", func=serper.run
+            )
+        elif self.provider == "duckduckgo":
+            self._tool = DuckDuckGoSearchRun()
+        elif self.provider == "duckduckgo_results":
+            self._tool = DuckDuckGoSearchResults()
+        else:
+            raise ValueError(
+                f"Unknown provider: {self.provider}. "
+                "Supported: 'serper' (default if API key available), 'duckduckgo' (free, fallback), 'duckduckgo_results' (free)"
+            )
+
+    def run(self, query: str, **kwargs) -> str:
+        """
+        Execute search.
+
+        Args:
+            query: Search query
+            **kwargs: Additional parameters
+
+        Returns:
+            Search results
+        """
+        if not self._tool:
+            self._initialize_tool()
+
+        if self._tool:
+            # Use LangChain tool's invoke method
+            result = self._tool.invoke(query)
+            return str(result)
+        return f"Search results for: {query}"
+
+    def __call__(self, query: str, **kwargs) -> str:
+        """Make tool callable"""
+        return self.run(query, **kwargs)
+
+    def as_langchain_tool(self) -> BaseTool:
+        """
+        Return the underlying LangChain tool for direct use.
+
+        Returns:
+            LangChain BaseTool instance
+        """
+        if not self._tool:
+            self._initialize_tool()
+        return self._tool