agentensemble 0.1.0__py3-none-any.whl

agentensemble/__init__.py

@@ -0,0 +1,76 @@
+"""
+AgentEnsemble - Orchestrate AI agents in perfect harmony
+
+A comprehensive framework for building, testing, and orchestrating multi-agent AI systems.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Irfan Ali"
+
+# Core imports
+from agentensemble.agents import (
+    ReActAgent,
+    StateGraphAgent,
+    RAGAgent,
+    HybridAgent,
+)
+
+# Structured output agent (optional, requires langchain>=1.1)
+try:
+    from agentensemble.agents import StructuredAgent
+    STRUCTURED_AVAILABLE = True
+except ImportError:
+    STRUCTURED_AVAILABLE = False
+    StructuredAgent = None
+
+from agentensemble.orchestration import (
+    Ensemble,
+    SupervisorOrchestrator,
+    SwarmOrchestrator,
+    PipelineOrchestrator,
+)
+
+from agentensemble.tools import (
+    ToolRegistry,
+    SearchTool,
+    ScraperTool,
+    RAGTool,
+    ValidationTool,
+)
+
+from agentensemble.testing import (
+    AgentComparison,
+    Benchmark,
+    Metrics,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    "__author__",
+    # Agents
+    "ReActAgent",
+    "StateGraphAgent",
+    "RAGAgent",
+    "HybridAgent",
+    # Orchestration
+    "Ensemble",
+    "SupervisorOrchestrator",
+    "SwarmOrchestrator",
+    "PipelineOrchestrator",
+    # Tools
+    "ToolRegistry",
+    "SearchTool",
+    "ScraperTool",
+    "RAGTool",
+    "ValidationTool",
+    # Testing
+    "AgentComparison",
+    "Benchmark",
+    "Metrics",
+]
+
+# Add StructuredAgent if available
+if STRUCTURED_AVAILABLE:
+    __all__.append("StructuredAgent")
+

agentensemble/agents/__init__.py

@@ -0,0 +1,32 @@
+"""
+Reference Agent Implementations
+
+Provides production-ready agent architectures:
+- ReActAgent: Simple reasoning + acting pattern
+- StateGraphAgent: Custom nodes with intelligent routing
+- RAGAgent: RAG-enhanced with fallback strategies
+- HybridAgent: Advanced iterative refinement
+- StructuredAgent: Structured output support (langchain>=1.1 or with_structured_output)
+"""
+
+from agentensemble.agents.react_agent import ReActAgent
+from agentensemble.agents.stategraph_agent import StateGraphAgent
+from agentensemble.agents.rag_agent import RAGAgent
+from agentensemble.agents.hybrid_agent import HybridAgent
+
+try:
+    from agentensemble.agents.structured_agent import StructuredAgent
+    STRUCTURED_AVAILABLE = True
+except ImportError:
+    STRUCTURED_AVAILABLE = False
+    StructuredAgent = None
+
+__all__ = [
+    "ReActAgent",
+    "StateGraphAgent",
+    "RAGAgent",
+    "HybridAgent",
+]
+
+if STRUCTURED_AVAILABLE:
+    __all__.append("StructuredAgent")

agentensemble/agents/base.py

@@ -0,0 +1,84 @@
+"""
+Base Agent Class
+
+Defines the interface and common functionality for all agents.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class AgentState(BaseModel):
+    """Base state model for agents"""
+    
+    query: str
+    context: Dict[str, Any] = Field(default_factory=dict)
+    iteration_count: int = 0
+    tool_calls: List[Dict[str, Any]] = Field(default_factory=list)
+    result: Optional[str] = None
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class BaseAgent(ABC):
+    """
+    Base class for all agents in AgentEnsemble.
+    
+    All agent implementations should inherit from this class.
+    """
+    
+    def __init__(
+        self,
+        name: str,
+        tools: Optional[List[Any]] = None,
+        max_iterations: int = 10,
+        **kwargs
+    ):
+        """
+        Initialize the agent.
+        
+        Args:
+            name: Name of the agent
+            tools: List of tools available to the agent
+            max_iterations: Maximum number of iterations
+            **kwargs: Additional configuration
+        """
+        self.name = name
+        self.tools = tools or []
+        self.max_iterations = max_iterations
+        self.config = kwargs
+    
+    @abstractmethod
+    def run(self, query: str, **kwargs) -> Dict[str, Any]:
+        """
+        Execute the agent with a given query.
+        
+        Args:
+            query: The input query
+            **kwargs: Additional parameters
+            
+        Returns:
+            Dictionary containing the result and metadata
+        """
+        pass
+    
+    def _validate_state(self, state: AgentState) -> bool:
+        """Validate agent state"""
+        return state.iteration_count < self.max_iterations
+    
+    def _update_state(
+        self,
+        state: AgentState,
+        result: Optional[str] = None,
+        tool_calls: Optional[List[Dict]] = None,
+        **metadata
+    ) -> AgentState:
+        """Update agent state"""
+        if result:
+            state.result = result
+        if tool_calls:
+            state.tool_calls.extend(tool_calls)
+        state.iteration_count += 1
+        state.metadata.update(metadata)
+        return state
+

agentensemble/agents/hybrid_agent.py

@@ -0,0 +1,147 @@
+"""
+Hybrid Agent Implementation
+
+Advanced agent with iterative refinement and early stopping.
+"""
+
+from typing import Any, Dict, Optional
+from agentensemble.agents.base import BaseAgent, AgentState
+
+
+class HybridAgent(BaseAgent):
+    """
+    Hybrid Agent with intelligent routing and iterative refinement.
+    
+    Combines multiple strategies: analysis → search → RAG → validation
+    """
+    
+    def __init__(
+        self,
+        name: str = "hybrid_agent",
+        tools: Optional[list] = None,
+        max_iterations: int = 15,
+        early_stopping: bool = True,
+        **kwargs
+    ):
+        """
+        Initialize Hybrid agent.
+        
+        Args:
+            name: Agent name
+            tools: Available tools
+            max_iterations: Maximum iterations
+            early_stopping: Enable early stopping when answer found
+            **kwargs: Additional configuration
+        """
+        super().__init__(name, tools, max_iterations, **kwargs)
+        self.early_stopping = early_stopping
+    
+    def run(self, query: str, **kwargs) -> Dict[str, Any]:
+        """
+        Execute Hybrid agent with intelligent routing.
+        
+        Args:
+            query: Input query
+            **kwargs: Additional parameters
+            
+        Returns:
+            Result dictionary
+        """
+        state = AgentState(query=query, context=kwargs.get("context", {}))
+        
+        # Hybrid workflow: Analyze → Search → RAG → Validate
+        for iteration in range(self.max_iterations):
+            if not self._validate_state(state):
+                break
+            
+            # Determine next action
+            action = self._decide_action(state)
+            
+            if action == "ANSWER":
+                if self.early_stopping:
+                    break
+            elif action == "SEARCH":
+                result = self._search(state)
+                state.context["search_results"] = result
+            elif action == "RAG":
+                result = self._rag(state)
+                state.context["rag_results"] = result
+            elif action == "VALIDATE":
+                validation = self._validate(state)
+                state.context["validation"] = validation
+            else:
+                break
+            
+            state = self._update_state(state, iteration=iteration)
+        
+        # Final answer synthesis
+        if not state.result:
+            state.result = self._synthesize_answer(state)
+        
+        return {
+            "result": state.result or "No result generated",
+            "metadata": {
+                "iterations": state.iteration_count,
+                "actions_taken": state.context.get("actions", []),
+                "agent": self.name,
+            }
+        }
+    
+    def _decide_action(self, state: AgentState) -> str:
+        """
+        Intelligent action decision.
+        
+        Returns:
+            Next action: "SEARCH", "RAG", "VALIDATE", "ANSWER"
+        """
+        # Simplified logic - in production, use LLM for routing
+        if state.result:
+            return "ANSWER"
+        if state.iteration_count == 0:
+            return "SEARCH"
+        if state.iteration_count == 1:
+            return "RAG"
+        if state.iteration_count == 2:
+            return "VALIDATE"
+        return "ANSWER"
+    
+    def _search(self, state: AgentState) -> str:
+        """Execute search"""
+        search_tool = next((t for t in self.tools if hasattr(t, "name") and t.name == "search"), None)
+        if search_tool:
+            return search_tool.run(state.query)
+        return "Search tool not available"
+    
+    def _rag(self, state: AgentState) -> str:
+        """Execute RAG"""
+        rag_tool = next((t for t in self.tools if hasattr(t, "name") and t.name == "rag"), None)
+        if rag_tool:
+            # Handle search_results as either string or dict
+            search_results = state.context.get("search_results", "")
+            if isinstance(search_results, dict):
+                urls = search_results.get("urls", [])
+            else:
+                urls = []  # No URLs from search
+            return rag_tool.run(state.query, urls=urls)
+        return "RAG tool not available"
+    
+    def _validate(self, state: AgentState) -> Dict[str, Any]:
+        """Execute validation"""
+        validator = next((t for t in self.tools if hasattr(t, "name") and t.name == "validator"), None)
+        if validator:
+            result = state.context.get("rag_results", "")
+            return validator.run(result, context=state.context)
+        return {"valid": True, "confidence": 0.8}
+    
+    def _synthesize_answer(self, state: AgentState) -> str:
+        """Synthesize final answer from all results"""
+        # Combine search and RAG results
+        search_result = state.context.get("search_results", "")
+        rag_result = state.context.get("rag_results", "")
+        
+        if rag_result and rag_result != "RAG tool not available":
+            return rag_result
+        if search_result and search_result != "Search tool not available":
+            return search_result
+        return "Unable to generate answer"
+

agentensemble/agents/rag_agent.py

@@ -0,0 +1,92 @@
+"""
+RAG-Enhanced Agent
+
+Agent with RAG capabilities and fallback strategies.
+"""
+
+from typing import Any, Dict, List, Optional
+from agentensemble.agents.base import BaseAgent, AgentState
+
+
+class RAGAgent(BaseAgent):
+    """
+    RAG-Enhanced Agent with fallback strategies.
+    
+    Implements scraping → embedding → retrieval with query variations.
+    """
+    
+    def __init__(
+        self,
+        name: str = "rag_agent",
+        tools: Optional[list] = None,
+        max_iterations: int = 10,
+        fallback_strategies: int = 3,
+        **kwargs
+    ):
+        """
+        Initialize RAG agent.
+        
+        Args:
+            name: Agent name
+            tools: Available tools (should include RAG tool)
+            max_iterations: Maximum iterations
+            fallback_strategies: Number of fallback query variations
+            **kwargs: Additional configuration
+        """
+        super().__init__(name, tools, max_iterations, **kwargs)
+        self.fallback_strategies = fallback_strategies
+    
+    def run(self, query: str, urls: Optional[List[str]] = None, **kwargs) -> Dict[str, Any]:
+        """
+        Execute RAG agent with fallback strategies.
+        
+        Args:
+            query: Input query
+            urls: Optional URLs to use for RAG
+            **kwargs: Additional parameters
+            
+        Returns:
+            Result dictionary
+        """
+        state = AgentState(query=query, context=kwargs.get("context", {}))
+        
+        # Try primary query
+        result = self._query_rag(state.query, urls)
+        
+        if result and result != "not found":
+            state.result = result
+        else:
+            # Try fallback strategies
+            for i in range(self.fallback_strategies):
+                fallback_query = self._generate_fallback_query(state.query, i)
+                result = self._query_rag(fallback_query, urls)
+                if result and result != "not found":
+                    state.result = result
+                    break
+        
+        return {
+            "result": state.result or "No result found",
+            "metadata": {
+                "fallback_attempts": min(self.fallback_strategies, state.iteration_count),
+                "agent": self.name,
+            }
+        }
+    
+    def _query_rag(self, query: str, urls: Optional[List[str]]) -> str:
+        """Query RAG system"""
+        # Find RAG tool
+        rag_tool = next((t for t in self.tools if hasattr(t, "name") and t.name == "rag"), None)
+        if rag_tool:
+            return rag_tool.run(query, urls=urls)
+        return "RAG tool not available"
+    
+    def _generate_fallback_query(self, original_query: str, attempt: int) -> str:
+        """Generate fallback query variation"""
+        # Simplified - in production, use LLM to rephrase
+        variations = [
+            f"More details about: {original_query}",
+            f"Alternative phrasing: {original_query}",
+            f"Related information: {original_query}",
+        ]
+        return variations[attempt % len(variations)]
+

agentensemble/agents/react_agent.py

@@ -0,0 +1,118 @@
+"""
+ReAct Agent Implementation
+
+Simple reasoning + acting pattern with tool calling.
+"""
+
+from typing import Any, Dict, List, Optional
+from agentensemble.agents.base import BaseAgent, AgentState
+
+
+class ReActAgent(BaseAgent):
+    """
+    ReAct (Reasoning + Acting) Agent
+    
+    A simple agent that reasons about actions and uses tools to accomplish tasks.
+    """
+    
+    def __init__(
+        self,
+        name: str = "react_agent",
+        tools: Optional[List[Any]] = None,
+        max_iterations: int = 10,
+        **kwargs
+    ):
+        """
+        Initialize ReAct agent.
+        
+        Args:
+            name: Agent name
+            tools: Available tools
+            max_iterations: Maximum reasoning/acting cycles
+            **kwargs: Additional configuration
+        """
+        super().__init__(name, tools, max_iterations, **kwargs)
+    
+    def run(self, query: str, **kwargs) -> Dict[str, Any]:
+        """
+        Execute ReAct agent.
+        
+        Args:
+            query: Input query
+            **kwargs: Additional parameters
+            
+        Returns:
+            Result dictionary with answer and metadata
+        """
+        state = AgentState(query=query, context=kwargs.get("context", {}))
+        
+        # Simple ReAct loop: Think -> Act -> Observe
+        for iteration in range(self.max_iterations):
+            if not self._validate_state(state):
+                break
+            
+            # Think: Reason about what to do
+            action = self._think(state)
+            
+            if action == "ANSWER":
+                break
+            
+            # Act: Use a tool
+            if action == "TOOL":
+                tool_result = self._act(state)
+                state.context["last_tool_result"] = tool_result
+                
+                # If we got a good result, use it as the answer
+                if tool_result and tool_result != "No tools available" and tool_result != "Tool execution failed":
+                    state.result = tool_result
+                
+                state = self._update_state(
+                    state,
+                    tool_calls=[{"iteration": iteration, "result": tool_result}]
+                )
+            else:
+                break
+        
+        # If no result yet, try to synthesize from context
+        if not state.result and state.context.get("last_tool_result"):
+            state.result = state.context["last_tool_result"]
+        
+        return {
+            "result": state.result or state.context.get("last_tool_result", "No result generated"),
+            "metadata": {
+                "iterations": state.iteration_count,
+                "tool_calls": len(state.tool_calls),
+                "agent": self.name,
+            }
+        }
+    
+    def _think(self, state: AgentState) -> str:
+        """
+        Reasoning step: Decide what action to take.
+        
+        Returns:
+            "TOOL" to use a tool, "ANSWER" to provide final answer
+        """
+        # Simplified logic - in production, this would use an LLM
+        if state.result:
+            return "ANSWER"
+        if state.iteration_count < 3 and self.tools:
+            return "TOOL"
+        return "ANSWER"
+    
+    def _act(self, state: AgentState) -> str:
+        """
+        Acting step: Execute a tool.
+        
+        Returns:
+            Tool result
+        """
+        if not self.tools:
+            return "No tools available"
+        
+        # Use first available tool (simplified)
+        tool = self.tools[0]
+        if hasattr(tool, "run"):
+            return tool.run(state.query)
+        return "Tool execution failed"
+

agentensemble/agents/stategraph_agent.py

@@ -0,0 +1,97 @@
+"""
+StateGraph Agent Implementation
+
+Custom StateGraph with intelligent routing between nodes.
+"""
+
+from typing import Any, Dict, Optional
+from agentensemble.agents.base import BaseAgent, AgentState
+
+
+class StateGraphAgent(BaseAgent):
+    """
+    StateGraph Agent with custom nodes and routing.
+    
+    Implements a graph-based workflow with intelligent routing.
+    """
+    
+    def __init__(
+        self,
+        name: str = "stategraph_agent",
+        nodes: Optional[Dict[str, Any]] = None,
+        tools: Optional[list] = None,
+        max_iterations: int = 15,
+        **kwargs
+    ):
+        """
+        Initialize StateGraph agent.
+        
+        Args:
+            name: Agent name
+            nodes: Dictionary of node name -> node function
+            tools: Available tools
+            max_iterations: Maximum graph iterations
+            **kwargs: Additional configuration
+        """
+        super().__init__(name, tools, max_iterations, **kwargs)
+        self.nodes = nodes or {}
+    
+    def run(self, query: str, **kwargs) -> Dict[str, Any]:
+        """
+        Execute StateGraph agent.
+        
+        Args:
+            query: Input query
+            **kwargs: Additional parameters
+            
+        Returns:
+            Result dictionary
+        """
+        state = AgentState(query=query, context=kwargs.get("context", {}))
+        
+        # Simplified StateGraph execution
+        current_node = "start"
+        
+        for iteration in range(self.max_iterations):
+            if not self._validate_state(state):
+                break
+            
+            # Execute current node
+            if current_node in self.nodes:
+                node_result = self.nodes[current_node](state)
+                state = self._update_state(state, **node_result)
+                
+                # Route to next node
+                current_node = self._route(state, current_node)
+                if current_node == "end":
+                    break
+            else:
+                break
+        
+        return {
+            "result": state.result or "No result generated",
+            "metadata": {
+                "iterations": state.iteration_count,
+                "nodes_visited": list(self.nodes.keys()),
+                "agent": self.name,
+            }
+        }
+    
+    def _route(self, state: AgentState, current_node: str) -> str:
+        """
+        Intelligent routing logic.
+        
+        Args:
+            state: Current state
+            current_node: Current node name
+            
+        Returns:
+            Next node name or "end"
+        """
+        # Simplified routing - in production, this would use LLM or rules
+        if state.result:
+            return "end"
+        if current_node == "start":
+            return "analyze" if "analyze" in self.nodes else "end"
+        return "end"
+