pygeai-orchestration 0.1.0b2__py3-none-any.whl

pygeai_orchestration/patterns/multi_agent.py

@@ -0,0 +1,237 @@
+from typing import Any, Dict, List, Optional
+from ..core.base import BasePattern, PatternConfig, PatternResult, PatternType
+from ..core.common import Message, MessageRole, Conversation, State, StateStatus
+from ..core.utils import get_logger
+
+logger = get_logger()
+
+
+class AgentRole:
+    """
+    Represents an agent with a specific role in multi-agent collaboration.
+
+    :param name: str - The unique name/identifier for this agent role.
+    :param agent: BaseAgent - The agent instance performing this role.
+    :param role_description: str - Description of this agent's responsibilities and expertise.
+    """
+
+    def __init__(self, name: str, agent, role_description: str):
+        self.name = name
+        self.agent = agent
+        self.role_description = role_description
+        self.contributions: List[str] = []
+
+    def __repr__(self) -> str:
+        return f"AgentRole({self.name}: {self.role_description})"
+
+
+class MultiAgentPattern(BasePattern):
+    """
+    Multi-agent pattern for collaborative problem-solving with specialized agents.
+
+    This pattern orchestrates multiple agents with different roles and expertise
+    to collaboratively solve complex tasks. A coordinator agent manages the workflow,
+    distributes work, and synthesizes contributions into a final answer.
+
+    The multi-agent pattern is ideal for:
+    - Tasks requiring diverse expertise (e.g., research, analysis, writing)
+    - Complex problems benefiting from different perspectives
+    - Scenarios where specialized agents outperform generalists
+    - Workflow requiring coordination and synthesis of multiple outputs
+
+    The pattern follows this workflow:
+    1. **Coordination**: Coordinator agent analyzes task and creates distribution plan
+    2. **Parallel/Sequential Execution**: Each specialized agent contributes based on role
+    3. **Synthesis**: Coordinator integrates all contributions into coherent final answer
+
+    This approach enables division of labor, specialization, and richer solutions
+    than single-agent approaches.
+    """
+
+    def __init__(
+        self, agents: List[AgentRole], coordinator_agent, config: Optional[PatternConfig] = None
+    ):
+        """
+        Initialize the Multi-Agent pattern.
+
+        :param agents: List[AgentRole] - List of agent roles participating in collaboration.
+        :param coordinator_agent: BaseAgent - The coordinator agent managing workflow and synthesis.
+        :param config: Optional[PatternConfig] - Pattern configuration. If None, uses default with max_iterations=15.
+        """
+        if config is None:
+            config = PatternConfig(
+                name="multi_agent", pattern_type=PatternType.MULTI_AGENT, max_iterations=15
+            )
+        super().__init__(config)
+        self.agent_roles = {role.name: role for role in agents}
+        self.coordinator = coordinator_agent
+        self._conversation = Conversation(id=f"multi-agent-{id(self)}")
+        self._state = State()
+
+    async def execute(self, task: str, context: Optional[Dict[str, Any]] = None) -> PatternResult:
+        """
+        Execute the multi-agent pattern on the given task.
+
+        The method coordinates multiple specialized agents to collaboratively solve
+        the task. The coordinator first creates a distribution plan, then each agent
+        contributes based on its role, and finally the coordinator synthesizes all
+        contributions into a unified answer.
+
+        :param task: str - The task requiring collaborative multi-agent effort.
+        :param context: Optional[Dict[str, Any]] - Additional context for execution. Defaults to None.
+        :return: PatternResult - Contains success status, synthesized answer, and agent contributions.
+        :raises PatternExecutionError: If the multi-agent pattern execution fails.
+
+        Example:
+            >>> roles = [
+            ...     AgentRole("researcher", research_agent, "Research and gather facts"),
+            ...     AgentRole("analyst", analysis_agent, "Analyze data and identify patterns"),
+            ...     AgentRole("writer", writing_agent, "Create clear written summaries")
+            ... ]
+            >>> pattern = MultiAgentPattern(agents=roles, coordinator_agent=coordinator)
+            >>> result = await pattern.execute("Analyze the impact of AI on healthcare")
+            >>> print(f"Final answer: {result.result}")
+            >>> print(f"Contributions: {result.metadata['contributions']}")
+        """
+        self.reset()
+        for role in self.agent_roles.values():
+            role.contributions.clear()
+        self._state.update_status(StateStatus.RUNNING)
+
+        logger.info(
+            f"Starting multi-agent pattern with {len(self.agent_roles)} agents for task: {task[:50]}..."
+        )
+
+        try:
+            coordination_plan = await self._coordinate_task(task)
+            logger.info(f"Coordination plan: {coordination_plan[:100]}...")
+
+            all_contributions = {}
+
+            for agent_name, role in self.agent_roles.items():
+                if self.current_iteration >= self.config.max_iterations:
+                    break
+
+                self.increment_iteration()
+                logger.debug(f"Agent '{agent_name}' processing task")
+
+                state_data = {
+                    "iteration": self.current_iteration,
+                    "agent_name": agent_name,
+                    "role": role.role_description,
+                    "task": task,
+                    "coordination_plan": coordination_plan,
+                    "previous_contributions": all_contributions,
+                }
+
+                step_result = await self.step(state_data)
+                contribution = step_result.get("contribution")
+                role.contributions.append(contribution)
+                all_contributions[agent_name] = contribution
+
+            final_result = await self._synthesize_contributions(task, all_contributions)
+
+            self._state.update_status(StateStatus.COMPLETED)
+
+            return PatternResult(
+                success=True,
+                result=final_result,
+                iterations=self.current_iteration,
+                metadata={
+                    "agents": list(self.agent_roles.keys()),
+                    "contributions": all_contributions,
+                    "coordination_plan": coordination_plan,
+                },
+            )
+
+        except Exception as e:
+            logger.error(f"Multi-agent pattern failed: {str(e)}")
+            self._state.update_status(StateStatus.FAILED)
+            return PatternResult(
+                success=False, result=None, iterations=self.current_iteration, error=str(e)
+            )
+
+    async def step(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        agent_name = state.get("agent_name")
+        role_desc = state.get("role")
+        task = state.get("task")
+        coordination_plan = state.get("coordination_plan", "")
+        previous_contributions = state.get("previous_contributions", {})
+
+        role = self.agent_roles[agent_name]
+
+        context_str = ""
+        if previous_contributions:
+            context_str = "\n\nContributions from other agents:\n"
+            for name, contrib in previous_contributions.items():
+                context_str += f"- {name}: {contrib[:200]}...\n"
+
+        agent_prompt = (
+            f"You are acting as: {role_desc}\n\n"
+            f"Task: {task}\n\n"
+            f"Coordination plan: {coordination_plan}\n"
+            f"{context_str}\n"
+            f"Provide your contribution based on your role:"
+        )
+
+        contribution = await role.agent.generate(agent_prompt)
+
+        self._conversation.add_message(
+            Message(
+                role=MessageRole.ASSISTANT,
+                content=contribution,
+                metadata={"agent": agent_name, "role": role_desc},
+            )
+        )
+
+        return {"contribution": contribution, "agent": agent_name}
+
+    async def _coordinate_task(self, task: str) -> str:
+        agents_desc = "\n".join(
+            [f"- {name}: {role.role_description}" for name, role in self.agent_roles.items()]
+        )
+
+        coordination_prompt = (
+            f"Task: {task}\n\n"
+            f"Available agents:\n{agents_desc}\n\n"
+            "Create a coordination plan describing how these agents should work together "
+            "to accomplish the task. Be specific about what each agent should focus on."
+        )
+
+        plan = await self.coordinator.generate(coordination_prompt)
+        self._conversation.add_message(
+            Message(role=MessageRole.SYSTEM, content=plan, metadata={"type": "coordination_plan"})
+        )
+
+        return plan
+
+    async def _synthesize_contributions(self, task: str, contributions: Dict[str, str]) -> str:
+        synthesis_prompt = f"Original task: {task}\n\nContributions from each agent:\n"
+
+        for agent_name, contribution in contributions.items():
+            role_desc = self.agent_roles[agent_name].role_description
+            synthesis_prompt += f"\n{agent_name} ({role_desc}):\n{contribution}\n"
+
+        synthesis_prompt += (
+            "\nSynthesize these contributions into a comprehensive final answer. "
+            "Integrate insights from all agents and resolve any conflicts or overlaps."
+        )
+
+        final_answer = await self.coordinator.generate(synthesis_prompt)
+
+        self._conversation.add_message(
+            Message(
+                role=MessageRole.ASSISTANT,
+                content=final_answer,
+                metadata={"type": "final_synthesis"},
+            )
+        )
+
+        return final_answer
+
+    def get_agent_contributions(self, agent_name: str) -> List[str]:
+        role = self.agent_roles.get(agent_name)
+        return role.contributions.copy() if role else []
+
+    def get_conversation(self) -> Conversation:
+        return self._conversation

pygeai_orchestration/patterns/planning.py

@@ -0,0 +1,219 @@
+from typing import Any, Dict, List, Optional
+from ..core.base import BasePattern, PatternConfig, PatternResult, PatternType
+from ..core.common import Message, MessageRole, Conversation, State, StateStatus
+from ..core.utils import get_logger
+
+logger = get_logger()
+
+
+class PlanStep:
+    """
+    Represents a single step in a planning execution.
+
+    :param step_num: int - The step number in the overall plan.
+    :param description: str - Description of what this step accomplishes.
+    :param status: str - Current status: 'pending', 'completed', or 'failed'. Defaults to 'pending'.
+    """
+
+    def __init__(self, step_num: int, description: str, status: str = "pending"):
+        self.step_num = step_num
+        self.description = description
+        self.status = status
+        self.result: Optional[str] = None
+
+    def __repr__(self) -> str:
+        return f"Step {self.step_num}: {self.description} [{self.status}]"
+
+
+class PlanningPattern(BasePattern):
+    """
+    Planning pattern for decomposing complex tasks into executable steps.
+
+    This pattern implements a plan-and-execute approach where the agent first
+    generates a structured plan breaking down the task into discrete steps,
+    then executes each step sequentially, and finally synthesizes the results.
+
+    The planning pattern is ideal for:
+    - Complex multi-step tasks requiring coordination
+    - Tasks benefiting from upfront decomposition and strategy
+    - Long-running workflows where progress tracking is important
+    - Tasks where step dependencies need explicit management
+
+    The pattern follows this workflow:
+    1. **Plan Generation**: Agent creates a structured plan with numbered steps
+    2. **Sequential Execution**: Each step is executed in order
+    3. **Result Synthesis**: Final answer integrates all step results
+
+    This approach provides transparency, debuggability, and the ability to
+    resume or modify execution mid-workflow.
+    """
+
+    def __init__(self, agent, config: Optional[PatternConfig] = None):
+        """
+        Initialize the Planning pattern.
+
+        :param agent: BaseAgent - The agent to use for plan generation and step execution.
+        :param config: Optional[PatternConfig] - Pattern configuration. If None, uses default with max_iterations=20.
+        """
+        if config is None:
+            config = PatternConfig(
+                name="planning", pattern_type=PatternType.PLANNING, max_iterations=20
+            )
+        super().__init__(config)
+        self.agent = agent
+        self._conversation = Conversation(id=f"planning-{id(self)}")
+        self._state = State()
+        self._plan: List[PlanStep] = []
+
+    async def execute(self, task: str, context: Optional[Dict[str, Any]] = None) -> PatternResult:
+        """
+        Execute the planning pattern on the given task.
+
+        The method first generates a plan by decomposing the task, then executes
+        each step sequentially, and finally synthesizes all step results into a
+        coherent final answer.
+
+        :param task: str - The complex task to decompose and execute.
+        :param context: Optional[Dict[str, Any]] - Additional context for execution. Defaults to None.
+        :return: PatternResult - Contains success status, final answer, plan steps, and execution metadata.
+        :raises PatternExecutionError: If the planning pattern execution fails.
+
+        Example:
+            >>> pattern = PlanningPattern(agent=my_agent)
+            >>> result = await pattern.execute("Research and summarize the history of AI from 1950 to 2020")
+            >>> print(f"Answer: {result.result}")
+            >>> print(f"Plan steps: {result.metadata['plan']}")
+        """
+        self.reset()
+        self._plan.clear()
+        self._state.update_status(StateStatus.RUNNING)
+
+        logger.info(f"Starting planning pattern for task: {task[:50]}...")
+
+        try:
+            plan = await self._create_plan(task)
+            self._plan = plan
+            logger.info(f"Created plan with {len(plan)} steps")
+
+            results = []
+            for step in plan:
+                if self.current_iteration >= self.config.max_iterations:
+                    logger.warning("Reached max iterations during plan execution")
+                    break
+
+                self.increment_iteration()
+                logger.debug(f"Executing step {step.step_num}: {step.description}")
+
+                state_data = {
+                    "iteration": self.current_iteration,
+                    "current_step": step.step_num,
+                    "step_description": step.description,
+                    "previous_results": results,
+                }
+
+                step_result = await self.step(state_data)
+                step.result = step_result.get("result")
+                step.status = "completed" if step_result.get("success") else "failed"
+                results.append(step.result)
+
+                if not step_result.get("success"):
+                    logger.error(f"Step {step.step_num} failed: {step.result}")
+                    break
+
+            final_result = await self._synthesize_results(task, results)
+
+            self._state.update_status(StateStatus.COMPLETED)
+
+            return PatternResult(
+                success=True,
+                result=final_result,
+                iterations=self.current_iteration,
+                metadata={
+                    "plan": [str(s) for s in self._plan],
+                    "step_results": results,
+                    "completed_steps": sum(1 for s in self._plan if s.status == "completed"),
+                },
+            )
+
+        except Exception as e:
+            logger.error(f"Planning pattern failed: {str(e)}")
+            self._state.update_status(StateStatus.FAILED)
+            return PatternResult(
+                success=False, result=None, iterations=self.current_iteration, error=str(e)
+            )
+
+    async def step(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        step_num = state.get("current_step")
+        description = state.get("step_description")
+        previous_results = state.get("previous_results", [])
+
+        context_str = ""
+        if previous_results:
+            context_str = "\n\nPrevious results:\n"
+            for i, res in enumerate(previous_results, 1):
+                context_str += f"Step {i}: {res}\n"
+
+        prompt = f"Execute the following step:\n{description}{context_str}"
+
+        try:
+            result = await self.agent.generate(prompt)
+            self._conversation.add_message(
+                Message(role=MessageRole.ASSISTANT, content=result, metadata={"step": step_num})
+            )
+            return {"success": True, "result": result}
+        except Exception as e:
+            return {"success": False, "result": str(e)}
+
+    async def _create_plan(self, task: str) -> List[PlanStep]:
+        planning_prompt = (
+            f"Create a detailed step-by-step plan to accomplish this task:\n{task}\n\n"
+            "Provide your plan as a numbered list. Each step should be clear and actionable.\n"
+            "Format:\n1. <step description>\n2. <step description>\netc."
+        )
+
+        self._conversation.add_message(Message(role=MessageRole.USER, content=planning_prompt))
+        plan_response = await self.agent.generate(planning_prompt)
+        self._conversation.add_message(Message(role=MessageRole.ASSISTANT, content=plan_response))
+
+        plan = self._parse_plan(plan_response)
+        return plan
+
+    def _parse_plan(self, plan_text: str) -> List[PlanStep]:
+        steps = []
+        lines = plan_text.strip().split("\n")
+
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+
+            if line[0].isdigit() and ("." in line or ")" in line):
+                parts = line.split(".", 1) if "." in line else line.split(")", 1)
+                if len(parts) == 2:
+                    try:
+                        step_num = int(parts[0].strip())
+                        description = parts[1].strip()
+                        steps.append(PlanStep(step_num, description))
+                    except ValueError:
+                        continue
+
+        if not steps:
+            steps.append(PlanStep(1, plan_text))
+
+        return steps
+
+    async def _synthesize_results(self, task: str, results: List[str]) -> str:
+        synthesis_prompt = f"Original task: {task}\n\nResults from each step:\n"
+        for i, result in enumerate(results, 1):
+            synthesis_prompt += f"\nStep {i}: {result}\n"
+
+        synthesis_prompt += "\nProvide a final synthesized answer based on all the steps:"
+
+        final_answer = await self.agent.generate(synthesis_prompt)
+        return final_answer
+
+    def get_plan(self) -> List[PlanStep]:
+        return self._plan.copy()
+
+    def get_conversation(self) -> Conversation:
+        return self._conversation

pygeai_orchestration/patterns/react.py

@@ -0,0 +1,221 @@
+from typing import Any, Dict, List, Optional
+from ..core.base import BasePattern, BaseTool, PatternConfig, PatternResult, PatternType
+from ..core.common import Message, MessageRole, Conversation, State, StateStatus
+from ..core.utils import get_logger
+
+logger = get_logger()
+
+
+class ReActPattern(BasePattern):
+    """
+    ReAct (Reasoning and Acting) pattern for structured agent decision-making.
+
+    This pattern implements the ReAct framework that interleaves reasoning traces
+    and task-specific actions in a structured loop. The agent follows a think-act-observe
+    cycle to solve complex tasks requiring iterative reasoning and tool use.
+
+    The ReAct pattern is particularly effective for:
+    - Multi-step reasoning tasks requiring careful thought
+    - Tasks requiring dynamic tool selection based on intermediate results
+    - Debugging and transparency (reasoning traces provide explainability)
+    - Complex problem-solving requiring iterative refinement
+
+    The pattern follows this cycle:
+    1. **Thought**: Agent reasons about the current state and next steps
+    2. **Action**: Agent selects and executes a tool or provides final answer
+    3. **Observation**: Results are integrated and inform next thought
+
+    Reference: Yao et al. (2022) "ReAct: Synergizing Reasoning and Acting in Language Models"
+    """
+
+    def __init__(
+        self, agent, tools: Optional[List[BaseTool]] = None, config: Optional[PatternConfig] = None
+    ):
+        """
+        Initialize the ReAct pattern.
+
+        :param agent: BaseAgent - The agent to use for reasoning and action generation.
+        :param tools: Optional[List[BaseTool]] - List of tools available to the agent. Defaults to None.
+        :param config: Optional[PatternConfig] - Pattern configuration. If None, uses default with max_iterations=10.
+        """
+        if config is None:
+            config = PatternConfig(name="react", pattern_type=PatternType.REACT, max_iterations=10)
+        super().__init__(config)
+        self.agent = agent
+        self.tools = {tool.name: tool for tool in (tools or [])}
+        self._conversation = Conversation(id=f"react-{id(self)}")
+        self._state = State()
+        self._thought_history: List[str] = []
+        self._action_history: List[str] = []
+        self._observation_history: List[str] = []
+
+    async def execute(self, task: str, context: Optional[Dict[str, Any]] = None) -> PatternResult:
+        """
+        Execute the ReAct pattern on the given task.
+
+        The method orchestrates the think-act-observe cycle where the agent iteratively
+        reasons about the task, selects actions (tool calls), observes results, and
+        refines its approach until reaching a final answer.
+
+        :param task: str - The task or question to solve using ReAct reasoning.
+        :param context: Optional[Dict[str, Any]] - Additional context for execution. Defaults to None.
+        :return: PatternResult - Contains success status, final answer, and complete reasoning trace.
+        :raises PatternExecutionError: If the ReAct pattern execution fails.
+
+        Example:
+            >>> tools = [SearchTool(), CalculatorTool()]
+            >>> pattern = ReActPattern(agent=my_agent, tools=tools)
+            >>> result = await pattern.execute("What's the population of Tokyo times 2?")
+            >>> print(f"Answer: {result.result}")
+            >>> print(f"Reasoning trace: {result.metadata['thoughts']}")
+        """
+        self.reset()
+        self._thought_history.clear()
+        self._action_history.clear()
+        self._observation_history.clear()
+        self._state.update_status(StateStatus.RUNNING)
+
+        logger.info(f"Starting ReAct pattern for task: {task[:50]}...")
+
+        try:
+            system_prompt = self._build_system_prompt()
+            self._conversation.add_message(Message(role=MessageRole.SYSTEM, content=system_prompt))
+            self._conversation.add_message(Message(role=MessageRole.USER, content=f"Task: {task}"))
+
+            final_answer = None
+
+            while self.current_iteration < self.config.max_iterations:
+                self.increment_iteration()
+                logger.debug(
+                    f"ReAct iteration {self.current_iteration}/{self.config.max_iterations}"
+                )
+
+                state_data = {
+                    "iteration": self.current_iteration,
+                    "task": task,
+                    "history": {
+                        "thoughts": self._thought_history,
+                        "actions": self._action_history,
+                        "observations": self._observation_history,
+                    },
+                }
+
+                step_result = await self.step(state_data)
+
+                if step_result.get("is_final"):
+                    final_answer = step_result.get("answer")
+                    logger.info(f"ReAct completed at iteration {self.current_iteration}")
+                    break
+
+            self._state.update_status(StateStatus.COMPLETED)
+
+            return PatternResult(
+                success=True,
+                result=final_answer or "No final answer reached",
+                iterations=self.current_iteration,
+                metadata={
+                    "thoughts": self._thought_history,
+                    "actions": self._action_history,
+                    "observations": self._observation_history,
+                },
+            )
+
+        except Exception as e:
+            logger.error(f"ReAct pattern failed: {str(e)}")
+            self._state.update_status(StateStatus.FAILED)
+            return PatternResult(
+                success=False, result=None, iterations=self.current_iteration, error=str(e)
+            )
+
+    async def step(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        history = state.get("history", {})
+
+        prompt = self._build_step_prompt(history)
+        response = await self.agent.generate(prompt)
+
+        thought, action, observation, is_final, answer = self._parse_response(response)
+
+        if thought:
+            self._thought_history.append(thought)
+            logger.debug(f"Thought: {thought[:100]}...")
+
+        if action:
+            self._action_history.append(action)
+            logger.debug(f"Action: {action[:100]}...")
+
+            if not is_final:
+                obs = await self._execute_action(action)
+                self._observation_history.append(obs)
+                logger.debug(f"Observation: {obs[:100]}...")
+
+        return {
+            "is_final": is_final,
+            "answer": answer,
+            "thought": thought,
+            "action": action,
+            "observation": observation,
+        }
+
+    def _build_system_prompt(self) -> str:
+        tools_desc = self._get_tools_description() if self.tools else "No tools available."
+        return (
+            "You are a reasoning agent following the ReAct pattern.\n"
+            "For each step, provide your response in this format:\n\n"
+            "Thought: <your reasoning about what to do next>\n"
+            "Action: <the action to take or ANSWER if you have the final answer>\n"
+            "Observation: <what you learned from the action>\n\n"
+            f"Available tools:\n{tools_desc}\n\n"
+            "When you have the final answer, use: Action: ANSWER <your answer>"
+        )
+
+    def _build_step_prompt(self, history: Dict[str, Any]) -> str:
+        thoughts = history.get("thoughts", [])
+        actions = history.get("actions", [])
+        observations = history.get("observations", [])
+
+        history_str = ""
+        for i, (t, a, o) in enumerate(zip(thoughts, actions, observations)):
+            history_str += f"\nStep {i + 1}:\nThought: {t}\nAction: {a}\nObservation: {o}\n"
+
+        return f"Previous steps:{history_str}\n\nProvide the next step:"
+
+    def _parse_response(self, response: str) -> tuple:
+        thought = ""
+        action = ""
+        observation = ""
+        is_final = False
+        answer = None
+
+        lines = response.strip().split("\n")
+        for line in lines:
+            if line.startswith("Thought:"):
+                thought = line[len("Thought:") :].strip()
+            elif line.startswith("Action:"):
+                action = line[len("Action:") :].strip()
+                if action.startswith("ANSWER"):
+                    is_final = True
+                    answer = action[len("ANSWER") :].strip()
+            elif line.startswith("Observation:"):
+                observation = line[len("Observation:") :].strip()
+
+        return thought, action, observation, is_final, answer
+
+    async def _execute_action(self, action: str) -> str:
+        parts = action.split(maxsplit=1)
+        tool_name = parts[0]
+        tool_input = parts[1] if len(parts) > 1 else ""
+
+        if tool_name in self.tools:
+            result = await self.tools[tool_name].execute(input=tool_input)
+            return str(result.result) if result.success else f"Error: {result.error}"
+        else:
+            return f"Tool '{tool_name}' not found"
+
+    def _get_tools_description(self) -> str:
+        if not self.tools:
+            return "None"
+        descriptions = [f"- {tool.name}: {tool.description}" for tool in self.tools.values()]
+        return "\n".join(descriptions)
+
+    def get_conversation(self) -> Conversation:
+        return self._conversation