genxai-framework 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

genxai/flows/base.py

@@ -0,0 +1,134 @@
+"""Base orchestrator for composable flow patterns."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Iterable, List, Optional
+from abc import ABC, abstractmethod
+
+from genxai.core.agent.base import Agent
+from genxai.core.agent.registry import AgentRegistry
+from genxai.core.graph.engine import Graph
+from genxai.core.graph.nodes import AgentNode
+
+
+class FlowOrchestrator(ABC):
+    """Base class for flow orchestrators.
+
+    A flow orchestrator converts a list of agents into a Graph
+    and executes it using the existing graph engine.
+    """
+
+    def __init__(
+        self,
+        agents: Iterable[Agent],
+        name: str = "flow",
+        llm_provider: Any = None,
+        allow_empty_agents: bool = False,
+        timeout_seconds: float = 120.0,
+        retry_count: int = 3,
+        backoff_base: float = 1.0,
+        backoff_multiplier: float = 2.0,
+        cancel_on_failure: bool = True,
+    ) -> None:
+        self.agents = list(agents)
+        if not self.agents and not allow_empty_agents:
+            raise ValueError("FlowOrchestrator requires at least one agent")
+
+        self.name = name
+        self.llm_provider = llm_provider
+        self.timeout_seconds = timeout_seconds
+        self.retry_count = retry_count
+        self.backoff_base = backoff_base
+        self.backoff_multiplier = backoff_multiplier
+        self.cancel_on_failure = cancel_on_failure
+
+        for agent in self.agents:
+            AgentRegistry.register(agent)
+
+    @abstractmethod
+    def build_graph(self) -> Graph:
+        """Construct a Graph for this flow pattern."""
+
+    async def run(
+        self,
+        input_data: Any,
+        state: Optional[Dict[str, Any]] = None,
+        max_iterations: int = 100,
+    ) -> Dict[str, Any]:
+        """Execute the flow graph with the provided input."""
+        if state is None:
+            state = {}
+        state.setdefault(
+            "execution_config",
+            {
+                "timeout_seconds": self.timeout_seconds,
+                "retry_count": self.retry_count,
+                "backoff_base": self.backoff_base,
+                "backoff_multiplier": self.backoff_multiplier,
+                "cancel_on_failure": self.cancel_on_failure,
+            },
+        )
+        graph = self.build_graph()
+        return await graph.run(
+            input_data=input_data,
+            max_iterations=max_iterations,
+            state=state,
+            llm_provider=self.llm_provider,
+        )
+
+    def _agent_nodes(self) -> List[AgentNode]:
+        """Create AgentNode instances for each registered agent."""
+        return [AgentNode(id=agent.id, agent_id=agent.id) for agent in self.agents]
+
+    async def _execute_with_retry(
+        self,
+        runtime: Any,
+        task: str,
+        context: Dict[str, Any],
+    ) -> Any:
+        """Execute a runtime task with retries and timeout."""
+        delay = self.backoff_base
+        for attempt in range(self.retry_count + 1):
+            try:
+                coro = runtime.execute(task=task, context=context)
+                if self.timeout_seconds:
+                    return await asyncio.wait_for(coro, timeout=self.timeout_seconds)
+                return await coro
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                if attempt >= self.retry_count:
+                    raise
+                await asyncio.sleep(delay)
+                delay *= self.backoff_multiplier
+
+    async def _gather_tasks(self, coros: List[Any]) -> List[Any]:
+        """Run tasks concurrently, optionally canceling on first failure."""
+        tasks = [asyncio.create_task(coro) for coro in coros]
+        if not tasks:
+            return []
+
+        if not self.cancel_on_failure:
+            return await asyncio.gather(*tasks, return_exceptions=True)
+
+        results: List[Any] = [None] * len(tasks)
+        index_map = {task: idx for idx, task in enumerate(tasks)}
+        done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_EXCEPTION)
+
+        for task in done:
+            idx = index_map[task]
+            exc = task.exception()
+            if exc:
+                for pending_task in pending:
+                    pending_task.cancel()
+                await asyncio.gather(*pending, return_exceptions=True)
+                raise exc
+            results[idx] = task.result()
+
+        if pending:
+            pending_results = await asyncio.gather(*pending, return_exceptions=True)
+            for task, result in zip(pending, pending_results):
+                results[index_map[task]] = result
+
+        return results

genxai/flows/conditional.py

@@ -0,0 +1,45 @@
+"""Conditional flow orchestrator."""
+
+from typing import Callable, List
+
+from genxai.core.graph.engine import Graph
+from genxai.core.graph.edges import Edge
+from genxai.core.graph.nodes import AgentNode, InputNode, OutputNode
+from genxai.flows.base import FlowOrchestrator
+
+
+class ConditionalFlow(FlowOrchestrator):
+    """Route to a single agent based on a condition function."""
+
+    def __init__(
+        self,
+        agents: List,
+        condition: Callable[[dict], str],
+        name: str = "conditional_flow",
+        llm_provider=None,
+    ) -> None:
+        super().__init__(agents=agents, name=name, llm_provider=llm_provider)
+        self.condition = condition
+
+    def build_graph(self) -> Graph:
+        graph = Graph(name=self.name)
+        start = InputNode(id="input")
+        graph.add_node(start)
+
+        end = OutputNode(id="output")
+        graph.add_node(end)
+        nodes = self._agent_nodes()
+        for node in nodes:
+            graph.add_node(node)
+            graph.add_edge(
+                Edge(
+                    source=start.id,
+                    target=node.id,
+                    condition=lambda state, agent_id=node.id: self.condition(state) == agent_id,
+                )
+            )
+            graph.add_edge(Edge(source=node.id, target=end.id))
+
+        graph.add_edge(Edge(source=start.id, target=end.id))
+
+        return graph

genxai/flows/coordinator_worker.py

@@ -0,0 +1,62 @@
+"""Coordinator-worker flow orchestrator."""
+
+from typing import Any, Dict, List, Optional
+
+from genxai.core.agent.runtime import AgentRuntime
+from genxai.flows.base import FlowOrchestrator
+
+
+class CoordinatorWorkerFlow(FlowOrchestrator):
+    """Coordinator assigns tasks to worker agents."""
+
+    def __init__(
+        self,
+        agents: List[Any],
+        name: str = "coordinator_worker_flow",
+        llm_provider: Any = None,
+    ) -> None:
+        super().__init__(agents=agents, name=name, llm_provider=llm_provider)
+
+    async def run(
+        self,
+        input_data: Any,
+        state: Optional[Dict[str, Any]] = None,
+        max_iterations: int = 100,
+    ) -> Dict[str, Any]:
+        if state is None:
+            state = {}
+        state["input"] = input_data
+        state.setdefault("worker_results", [])
+
+        if len(self.agents) < 2:
+            raise ValueError("CoordinatorWorkerFlow requires at least two agents")
+
+        coordinator = self.agents[0]
+        workers = self.agents[1:]
+        coordinator_runtime = AgentRuntime(agent=coordinator, llm_provider=self.llm_provider)
+        worker_runtimes = {
+            agent.id: AgentRuntime(agent=agent, llm_provider=self.llm_provider)
+            for agent in workers
+        }
+
+        plan = await self._execute_with_retry(
+            coordinator_runtime,
+            task=state.get("task", "Break the task into worker assignments"),
+            context=state,
+        )
+        state["plan"] = plan
+
+        worker_task = state.get("worker_task", "Execute assigned task")
+        tasks = [
+            self._execute_with_retry(
+                worker_runtimes[worker.id],
+                task=worker_task,
+                context={**state, "worker_id": worker.id},
+            )
+            for worker in workers
+        ]
+        results = await self._gather_tasks(tasks)
+        for worker, result in zip(workers, results):
+            state["worker_results"].append({"worker_id": worker.id, "result": result})
+
+        return state

genxai/flows/critic_review.py

@@ -0,0 +1,62 @@
+"""Critic review flow orchestrator."""
+
+from typing import Any, Dict, List, Optional
+
+from genxai.core.agent.runtime import AgentRuntime
+from genxai.flows.base import FlowOrchestrator
+
+
+class CriticReviewFlow(FlowOrchestrator):
+    """Generator -> critic -> revise loop with bounded iterations."""
+
+    def __init__(
+        self,
+        agents: List[Any],
+        name: str = "critic_review_flow",
+        llm_provider: Any = None,
+        max_iterations: int = 3,
+    ) -> None:
+        super().__init__(agents=agents, name=name, llm_provider=llm_provider)
+        self.max_iterations = max_iterations
+
+    async def run(
+        self,
+        input_data: Any,
+        state: Optional[Dict[str, Any]] = None,
+        max_iterations: int = 100,
+    ) -> Dict[str, Any]:
+        if state is None:
+            state = {}
+        state["input"] = input_data
+        state.setdefault("drafts", [])
+
+        if len(self.agents) < 2:
+            raise ValueError("CriticReviewFlow requires at least two agents")
+
+        generator = self.agents[0]
+        critic = self.agents[1]
+        gen_runtime = AgentRuntime(agent=generator, llm_provider=self.llm_provider)
+        critic_runtime = AgentRuntime(agent=critic, llm_provider=self.llm_provider)
+
+        draft = None
+        for _ in range(self.max_iterations):
+            gen_result = await self._execute_with_retry(
+                gen_runtime,
+                task=state.get("task", "Generate a draft"),
+                context={**state, "draft": draft},
+            )
+            draft = gen_result.get("output")
+            state["drafts"].append(draft)
+
+            critique = await self._execute_with_retry(
+                critic_runtime,
+                task=state.get("critic_task", "Critique the draft"),
+                context={**state, "draft": draft},
+            )
+            state["last_critique"] = critique
+
+            if state.get("accept", False):
+                break
+
+        state["final"] = draft
+        return state

genxai/flows/ensemble_voting.py

@@ -0,0 +1,49 @@
+"""Ensemble voting flow orchestrator."""
+
+from typing import Any, Dict, List, Optional
+
+from genxai.core.agent.runtime import AgentRuntime
+from genxai.flows.base import FlowOrchestrator
+
+
+class EnsembleVotingFlow(FlowOrchestrator):
+    """Run all agents and aggregate outputs via simple voting."""
+
+    def __init__(
+        self,
+        agents: List[Any],
+        name: str = "ensemble_voting_flow",
+        llm_provider: Any = None,
+    ) -> None:
+        super().__init__(agents=agents, name=name, llm_provider=llm_provider)
+
+    async def run(
+        self,
+        input_data: Any,
+        state: Optional[Dict[str, Any]] = None,
+        max_iterations: int = 100,
+    ) -> Dict[str, Any]:
+        if state is None:
+            state = {}
+        state["input"] = input_data
+        state.setdefault("votes", {})
+
+        runtimes = {
+            agent.id: AgentRuntime(agent=agent, llm_provider=self.llm_provider)
+            for agent in self.agents
+        }
+
+        task = state.get("task", "Provide your answer")
+        tasks = [
+            self._execute_with_retry(runtimes[agent.id], task=task, context=state)
+            for agent in self.agents
+        ]
+        results = await self._gather_tasks(tasks)
+        for result in results:
+            output = str(getattr(result, "get", lambda *_: "")("output", "")).strip()
+            state["votes"].setdefault(output, 0)
+            state["votes"][output] += 1
+
+        if state["votes"]:
+            state["winner"] = max(state["votes"], key=state["votes"].get)
+        return state

genxai/flows/loop.py

@@ -0,0 +1,42 @@
+"""Loop flow orchestrator."""
+
+from typing import List
+
+from genxai.core.graph.engine import Graph
+from genxai.core.graph.edges import Edge
+from genxai.core.graph.nodes import AgentNode, InputNode, LoopNode, OutputNode
+from genxai.flows.base import FlowOrchestrator
+
+
+class LoopFlow(FlowOrchestrator):
+    """Execute an agent inside a loop with a termination condition."""
+
+    def __init__(
+        self,
+        agents: List,
+        condition_key: str,
+        max_iterations: int = 5,
+        name: str = "loop_flow",
+        llm_provider=None,
+    ) -> None:
+        super().__init__(agents=agents, name=name, llm_provider=llm_provider)
+        self.condition_key = condition_key
+        self.loop_iterations = max_iterations
+
+    def build_graph(self) -> Graph:
+        graph = Graph(name=self.name)
+        start = InputNode(id="input")
+        loop = LoopNode(id="loop", condition=self.condition_key, max_iterations=self.loop_iterations)
+        agent = self._agent_nodes()[0]
+        end = OutputNode(id="output")
+
+        graph.add_node(start)
+        graph.add_node(loop)
+        graph.add_node(agent)
+        graph.add_node(end)
+
+        graph.add_edge(Edge(source=start.id, target=loop.id))
+        graph.add_edge(Edge(source=loop.id, target=agent.id))
+        graph.add_edge(Edge(source=agent.id, target=end.id))
+
+        return graph

genxai/flows/map_reduce.py

@@ -0,0 +1,61 @@
+"""MapReduce flow orchestrator."""
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+from genxai.core.agent.runtime import AgentRuntime
+from genxai.flows.base import FlowOrchestrator
+
+
+class MapReduceFlow(FlowOrchestrator):
+    """Run multiple agents in map phase, then summarize with reducer."""
+
+    def __init__(
+        self,
+        agents: List[Any],
+        name: str = "map_reduce_flow",
+        llm_provider: Any = None,
+    ) -> None:
+        super().__init__(agents=agents, name=name, llm_provider=llm_provider)
+
+    async def run(
+        self,
+        input_data: Any,
+        state: Optional[Dict[str, Any]] = None,
+        max_iterations: int = 100,
+    ) -> Dict[str, Any]:
+        if state is None:
+            state = {}
+        state["input"] = input_data
+        state.setdefault("map_results", [])
+
+        if len(self.agents) < 2:
+            raise ValueError("MapReduceFlow requires at least two agents")
+
+        *mappers, reducer = self.agents
+        mapper_runtimes = {
+            agent.id: AgentRuntime(agent=agent, llm_provider=self.llm_provider)
+            for agent in mappers
+        }
+        reducer_runtime = AgentRuntime(agent=reducer, llm_provider=self.llm_provider)
+
+        map_task = state.get("map_task", "Process shard")
+        tasks = [
+            self._execute_with_retry(
+                mapper_runtimes[mapper.id],
+                task=map_task,
+                context={**state, "mapper_id": mapper.id},
+            )
+            for mapper in mappers
+        ]
+        results = await self._gather_tasks(tasks)
+        for mapper, result in zip(mappers, results):
+            state["map_results"].append({"mapper_id": mapper.id, "result": result})
+
+        reduce_result = await self._execute_with_retry(
+            reducer_runtime,
+            task=state.get("reduce_task", "Summarize map results"),
+            context={**state, "map_results": state["map_results"]},
+        )
+        state["reduce_result"] = reduce_result
+        return state

genxai/flows/p2p.py

@@ -0,0 +1,146 @@
+"""Peer-to-peer flow orchestrator."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from datetime import datetime
+
+from genxai.core.agent.runtime import AgentRuntime
+from genxai.flows.base import FlowOrchestrator
+
+
+class P2PFlow(FlowOrchestrator):
+    """Run a peer-to-peer agent loop with lightweight consensus stopping.
+
+    This flow doesn't use the graph engine for routing; it mirrors the
+    P2P pattern where agents communicate directly and decide when to stop.
+    """
+
+    def __init__(
+        self,
+        agents: List[Any],
+        name: str = "p2p_flow",
+        llm_provider: Any = None,
+        max_rounds: int = 5,
+        timeout_seconds: float = 300,
+        consensus_threshold: float = 0.6,
+        convergence_window: int = 3,
+        quality_threshold: float = 0.85,
+    ) -> None:
+        super().__init__(agents=agents, name=name, llm_provider=llm_provider)
+        self.max_rounds = max_rounds
+        self.timeout_seconds = timeout_seconds
+        self.consensus_threshold = consensus_threshold
+        self.convergence_window = convergence_window
+        self.quality_threshold = quality_threshold
+        self._start_time = datetime.now()
+
+    async def run(
+        self,
+        input_data: Any,
+        state: Optional[Dict[str, Any]] = None,
+        max_iterations: int = 100,
+    ) -> Dict[str, Any]:
+        if state is None:
+            state = {}
+
+        state["input"] = input_data
+        state.setdefault("messages", [])
+        state.setdefault("solution_quality", 0.0)
+        state.setdefault("goal_achieved", False)
+
+        runtimes = {
+            agent.id: AgentRuntime(agent=agent, llm_provider=self.llm_provider)
+            for agent in self.agents
+        }
+
+        for round_idx in range(self.max_rounds):
+            for agent in self.agents:
+                result = await runtimes[agent.id].execute(
+                    task=state.get("task", "Collaborate with peers"),
+                    context=state,
+                )
+                state["messages"].append({
+                    "round": round_idx + 1,
+                    "agent_id": agent.id,
+                    "result": result,
+                })
+
+            state["solution_quality"] = self._estimate_quality(state)
+            if state["solution_quality"] >= self.quality_threshold:
+                state["goal_achieved"] = True
+
+            should_stop, reason = self._should_terminate(state, round_idx + 1)
+            if should_stop:
+                state["termination_reason"] = reason
+                break
+
+            if state.get("iterations", 0) >= max_iterations:
+                state["termination_reason"] = "Max iterations reached"
+                break
+
+        return state
+
+    def _should_terminate(self, state: Dict[str, Any], iteration: int) -> tuple[bool, Optional[str]]:
+        if iteration >= self.max_rounds:
+            return True, f"Max rounds reached ({self.max_rounds})"
+
+        elapsed = (datetime.now() - self._start_time).total_seconds()
+        if elapsed >= self.timeout_seconds:
+            return True, f"Timeout reached ({self.timeout_seconds}s)"
+
+        if state.get("goal_achieved"):
+            return True, "Goal achieved"
+
+        if self._consensus_reached(state):
+            return True, "Consensus to terminate"
+
+        if self._detect_convergence(state):
+            return True, "Conversation converged"
+
+        if self._detect_deadlock(state):
+            return True, "Deadlock detected"
+
+        return False, None
+
+    def _consensus_reached(self, state: Dict[str, Any]) -> bool:
+        messages = state.get("messages", [])
+        if not messages:
+            return False
+        votes = 0
+        for msg in messages[-len(self.agents):]:
+            result = msg.get("result", {})
+            if isinstance(result, dict) and str(result.get("status", "")).lower() == "completed":
+                votes += 1
+        return (votes / max(1, len(self.agents))) >= self.consensus_threshold
+
+    def _detect_convergence(self, state: Dict[str, Any]) -> bool:
+        messages = state.get("messages", [])
+        if len(messages) < self.convergence_window:
+            return False
+
+        recent = messages[-self.convergence_window:]
+        summaries = set(
+            str(msg.get("result", {}).get("output", ""))[:100] for msg in recent
+        )
+        return len(summaries) <= 2
+
+    def _detect_deadlock(self, state: Dict[str, Any]) -> bool:
+        messages = state.get("messages", [])
+        if len(messages) < 6:
+            return False
+        recent = messages[-6:]
+        senders = [msg.get("agent_id", "") for msg in recent]
+        return len(senders) >= 6 and senders[:3] == senders[3:6]
+
+    def _estimate_quality(self, state: Dict[str, Any]) -> float:
+        messages = state.get("messages", [])
+        if not messages:
+            return 0.0
+        recent = messages[-len(self.agents):]
+        scores = []
+        for msg in recent:
+            result = msg.get("result", {})
+            output = result.get("output") if isinstance(result, dict) else ""
+            scores.append(min(1.0, len(str(output)) / 500))
+        return sum(scores) / max(1, len(scores))

genxai/flows/parallel.py

@@ -0,0 +1,27 @@
+"""Parallel flow orchestrator."""
+
+from typing import List
+
+from genxai.core.graph.engine import Graph
+from genxai.core.graph.edges import Edge, ParallelEdge
+from genxai.core.graph.nodes import AgentNode, InputNode, OutputNode
+from genxai.flows.base import FlowOrchestrator
+
+
+class ParallelFlow(FlowOrchestrator):
+    """Execute all agents in parallel from a shared input node."""
+
+    def build_graph(self) -> Graph:
+        graph = Graph(name=self.name)
+        start = InputNode(id="input")
+        end = OutputNode(id="output")
+        graph.add_node(start)
+        graph.add_node(end)
+
+        nodes: List[AgentNode] = self._agent_nodes()
+        for node in nodes:
+            graph.add_node(node)
+            graph.add_edge(ParallelEdge(source=start.id, target=node.id))
+            graph.add_edge(Edge(source=node.id, target=end.id))
+
+        return graph

genxai/flows/round_robin.py

@@ -0,0 +1,24 @@
+"""Round-robin flow orchestrator."""
+
+from typing import List
+
+from genxai.core.graph.engine import Graph
+from genxai.core.graph.edges import Edge
+from genxai.core.graph.nodes import AgentNode
+from genxai.flows.base import FlowOrchestrator
+
+
+class RoundRobinFlow(FlowOrchestrator):
+    """Execute agents in a fixed, round-robin sequence."""
+
+    def build_graph(self) -> Graph:
+        graph = Graph(name=self.name)
+        nodes: List[AgentNode] = self._agent_nodes()
+
+        for node in nodes:
+            graph.add_node(node)
+
+        for idx in range(len(nodes) - 1):
+            graph.add_edge(Edge(source=nodes[idx].id, target=nodes[idx + 1].id))
+
+        return graph