pyagent-patterns 0.1.0__py3-none-any.whl

pyagent_patterns/orchestration/orchestrator_workers.py

@@ -0,0 +1,97 @@
+"""Orchestrator-Workers pattern: central LLM dynamically delegates tasks to workers.
+
+Unlike Supervisor (static routes) or Hierarchical (fixed teams), the Orchestrator
+dynamically decides how many workers to spawn and what each should do.
+
+LLM calls: 1 planning + N workers (dynamic) + 1 synthesis
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class OrchestratorWorkers(Pattern):
+    """Dynamic task delegation: orchestrator plans → workers execute → synthesize.
+
+    Args:
+        orchestrator: Agent that plans the work and synthesizes results.
+        workers: Pool of available worker agents. The orchestrator selects from these.
+    """
+
+    def __init__(self, orchestrator: Agent, workers: list[Agent]) -> None:
+        self._orchestrator = orchestrator
+        self._workers = {w.name: w for w in workers}
+
+    @property
+    def pattern_type(self) -> str:
+        return "orchestrator_workers"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+        worker_names = list(self._workers.keys())
+
+        # Step 1: Orchestrator plans the work
+        plan_prompt = Message.user(
+            f"You have these workers available: {', '.join(worker_names)}.\n"
+            f"Plan how to accomplish this task by assigning subtasks to workers.\n"
+            f"Respond as JSON: {{\"assignments\": [{{\"worker\": \"name\", \"subtask\": \"description\"}}]}}\n\n"
+            f"Task: {ctx.task}"
+        )
+        plan_msg = await self._orchestrator.run([plan_prompt])
+        messages.append(plan_msg)
+
+        # Step 2: Parse assignments and dispatch
+        assignments = self._parse_assignments(plan_msg.content)
+        worker_results: list[tuple[str, str]] = []
+
+        async def _run_assignment(worker_name: str, subtask: str) -> tuple[str, str]:
+            worker = self._workers.get(worker_name)
+            if worker is None:
+                # Fallback to first available worker
+                worker = next(iter(self._workers.values()))
+            result = await worker.run([Message.user(subtask)])
+            return worker.name, result.content
+
+        tasks = [_run_assignment(a["worker"], a["subtask"]) for a in assignments]
+        results = await asyncio.gather(*tasks)
+        for name, content in results:
+            messages.append(Message.assistant(content, name=name))
+            worker_results.append((name, content))
+
+        # Step 3: Orchestrator synthesizes
+        results_summary = "\n\n".join(
+            f"--- {name} ---\n{content}" for name, content in worker_results
+        )
+        synthesis_prompt = Message.user(
+            f"Synthesize these worker results into a final response:\n\n{results_summary}"
+        )
+        final = await self._orchestrator.run([synthesis_prompt])
+        messages.append(final)
+
+        return Result(
+            output=final.content,
+            messages=messages,
+            metadata={
+                "assignments": assignments,
+                "workers_used": len(assignments),
+            },
+        )
+
+    @staticmethod
+    def _parse_assignments(content: str) -> list[dict[str, str]]:
+        """Parse orchestrator's JSON assignment plan. Falls back gracefully."""
+        try:
+            # Try to extract JSON from the response
+            start = content.find("{")
+            end = content.rfind("}") + 1
+            if start >= 0 and end > start:
+                data = json.loads(content[start:end])
+                return data.get("assignments", [])
+        except (json.JSONDecodeError, KeyError):
+            pass
+        # Fallback: single assignment to first worker
+        return [{"worker": "default", "subtask": content}]

pyagent_patterns/orchestration/pipeline.py

@@ -0,0 +1,57 @@
+"""Pipeline pattern: sequential chain of agents where each stage's output feeds the next.
+
+Each agent processes the output of the previous stage.
+Ideal for document processing, ETL, and multi-step transformations.
+
+LLM calls: N (one per stage)
+"""
+
+from __future__ import annotations
+
+from typing import AsyncIterator
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class Pipeline(Pattern):
+    """Sequential stage chain — output of stage N becomes input of stage N+1.
+
+    Args:
+        stages: Ordered list of agents, each processing the previous output.
+    """
+
+    def __init__(self, stages: list[Agent]) -> None:
+        if not stages:
+            raise ValueError("Pipeline requires at least one stage")
+        self._stages = stages
+
+    @property
+    def pattern_type(self) -> str:
+        return "pipeline"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+        current_input = ctx.task
+
+        for i, stage in enumerate(self._stages):
+            stage_msg = Message.user(current_input)
+            response = await stage.run([stage_msg])
+            messages.append(response)
+            current_input = response.content
+
+        return Result(
+            output=current_input,
+            messages=messages,
+            metadata={"stages": len(self._stages), "stage_names": [s.name for s in self._stages]},
+        )
+
+    async def stream(self, task: str, context: Context | None = None) -> AsyncIterator[str]:
+        """Stream stage completions as they finish."""
+        ctx = context or Context(task=task)
+        current_input = task
+
+        for i, stage in enumerate(self._stages):
+            stage_msg = Message.user(current_input)
+            response = await stage.run([stage_msg])
+            current_input = response.content
+            yield f"[Stage {i + 1}/{len(self._stages)} — {stage.name}] {current_input}"

pyagent_patterns/orchestration/supervisor.py

@@ -0,0 +1,88 @@
+"""Supervisor pattern: classify input → route to specialist agent → collect result.
+
+The Supervisor inspects the incoming task, classifies it into a category,
+dispatches to the appropriate specialist agent, and optionally formats
+the final response.
+
+LLM calls: 2-3 (classify + specialist + optional format)
+"""
+
+from __future__ import annotations
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class Supervisor(Pattern):
+    """Classify → route → collect orchestration pattern.
+
+    Args:
+        classifier: Agent that classifies the task into a route key.
+        routes: Mapping of route keys to specialist agents.
+        formatter: Optional agent that formats the final response.
+        default_route: Key to use when classification doesn't match any route.
+    """
+
+    def __init__(
+        self,
+        classifier: Agent,
+        routes: dict[str, Agent],
+        formatter: Agent | None = None,
+        default_route: str | None = None,
+    ) -> None:
+        self._classifier = classifier
+        self._routes = routes
+        self._formatter = formatter
+        self._default_route = default_route
+
+    @property
+    def pattern_type(self) -> str:
+        return "supervisor"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+
+        # Step 1: Classify the task
+        classify_prompt = (
+            f"Classify the following task into exactly one of these categories: "
+            f"{', '.join(self._routes.keys())}.\n"
+            f"Respond with ONLY the category name, nothing else.\n\n"
+            f"Task: {ctx.task}"
+        )
+        classify_msg = Message.user(classify_prompt)
+        classification = await self._classifier.run([classify_msg])
+        messages.append(classification)
+
+        # Step 2: Route to specialist
+        route_key = classification.content.strip().lower()
+        agent = self._routes.get(route_key)
+        if agent is None and self._default_route:
+            agent = self._routes.get(self._default_route)
+            route_key = self._default_route
+        if agent is None:
+            # Fallback: use first available route
+            route_key = next(iter(self._routes))
+            agent = self._routes[route_key]
+
+        specialist_msg = await agent.run(ctx.messages)
+        messages.append(specialist_msg)
+
+        # Step 3: Optional formatting
+        output = specialist_msg.content
+        if self._formatter:
+            format_msgs = [
+                Message.user(
+                    f"Format the following response for the user:\n\n{specialist_msg.content}"
+                )
+            ]
+            formatted = await self._formatter.run(format_msgs)
+            messages.append(formatted)
+            output = formatted.content
+
+        return Result(
+            output=output,
+            messages=messages,
+            metadata={
+                "route_key": route_key,
+                "classifier_output": classification.content,
+            },
+        )

pyagent_patterns/recovery.py

@@ -0,0 +1,175 @@
+"""Error Recovery: BoundedExecution and CircuitBreaker for multi-agent patterns.
+
+BoundedExecution: wrap any pattern with max iterations, token, and timeout limits.
+CircuitBreaker: stop cascading failures with failure threshold + reset timeout.
+
+Based on: arxiv:2604.11378 "three-level recovery protocol"
+          Augment 2026 "Bounded Execution" emergent pattern
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from pyagent_patterns.base import Context, Pattern, Result
+
+
+class CircuitState(str, Enum):
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"  # Failing, rejecting requests
+    HALF_OPEN = "half_open"  # Testing if recovered
+
+
+@dataclass
+class BoundedExecution:
+    """Wrap a pattern with resource limits.
+
+    Three-level recovery:
+    1. Retry with same pattern
+    2. Fallback to a cheaper/simpler pattern
+    3. Graceful degradation (return partial result)
+
+    Args:
+        pattern: The primary pattern to execute.
+        fallback: Optional simpler pattern to use on failure.
+        max_retries: Maximum retry attempts before escalating.
+        timeout_seconds: Maximum wall-clock time for the entire execution.
+        max_tokens: Maximum total tokens before stopping.
+    """
+
+    pattern: Pattern
+    fallback: Pattern | None = None
+    max_retries: int = 2
+    timeout_seconds: float = 300.0
+    max_tokens: int = 100_000
+
+    async def run(self, task: str, context: Context | None = None) -> Result:
+        """Execute with bounded resources and three-level recovery."""
+        start = time.perf_counter()
+
+        # Level 1: Try primary pattern with retries
+        last_error: Exception | None = None
+        for attempt in range(1, self.max_retries + 1):
+            elapsed = time.perf_counter() - start
+            if elapsed > self.timeout_seconds:
+                break
+
+            try:
+                remaining = self.timeout_seconds - elapsed
+                result = await asyncio.wait_for(
+                    self.pattern.run(task, context),
+                    timeout=remaining,
+                )
+                if result.token_estimate <= self.max_tokens:
+                    result.metadata["recovery_level"] = 0
+                    result.metadata["attempts"] = attempt
+                    return result
+                # Token limit exceeded — try next level
+                last_error = Exception(f"Token limit exceeded: {result.token_estimate}/{self.max_tokens}")
+                break
+            except asyncio.TimeoutError:
+                last_error = asyncio.TimeoutError(f"Timeout after {self.timeout_seconds}s")
+                break
+            except Exception as e:
+                last_error = e
+                continue
+
+        # Level 2: Fallback pattern
+        if self.fallback:
+            try:
+                remaining = max(0.0, self.timeout_seconds - (time.perf_counter() - start))
+                result = await asyncio.wait_for(
+                    self.fallback.run(task, context),
+                    timeout=remaining if remaining > 0 else 30.0,
+                )
+                result.metadata["recovery_level"] = 1
+                result.metadata["fallback_reason"] = str(last_error)
+                return result
+            except Exception:
+                pass
+
+        # Level 3: Graceful degradation
+        return Result(
+            output=f"[Degraded] Unable to complete task after {self.max_retries} attempts. Last error: {last_error}",
+            metadata={
+                "recovery_level": 2,
+                "degraded": True,
+                "last_error": str(last_error),
+            },
+        )
+
+
+class CircuitBreaker:
+    """Prevent cascading failures in multi-agent systems.
+
+    When a pattern fails repeatedly, the circuit opens and rejects
+    requests immediately. After a reset timeout, it enters half-open
+    state and allows one test request through.
+
+    Args:
+        failure_threshold: Number of consecutive failures before opening.
+        reset_timeout_seconds: Seconds before transitioning from open to half-open.
+        fallback_result: Result to return when circuit is open.
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 3,
+        reset_timeout_seconds: float = 60.0,
+        fallback_result: str = "[Circuit Open] Service temporarily unavailable.",
+    ) -> None:
+        self._threshold = failure_threshold
+        self._reset_timeout = reset_timeout_seconds
+        self._fallback_result = fallback_result
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._last_failure_time = 0.0
+
+    @property
+    def state(self) -> CircuitState:
+        if self._state == CircuitState.OPEN:
+            if time.time() - self._last_failure_time > self._reset_timeout:
+                self._state = CircuitState.HALF_OPEN
+        return self._state
+
+    async def execute(self, pattern: Pattern, task: str, context: Context | None = None) -> Result:
+        """Execute a pattern through the circuit breaker."""
+        current_state = self.state
+
+        if current_state == CircuitState.OPEN:
+            return Result(
+                output=self._fallback_result,
+                metadata={"circuit_state": "open", "failure_count": self._failure_count},
+            )
+
+        try:
+            result = await pattern.run(task, context)
+            self._on_success()
+            result.metadata["circuit_state"] = self._state.value
+            return result
+        except Exception as e:
+            self._on_failure()
+            if self._state == CircuitState.OPEN:
+                return Result(
+                    output=self._fallback_result,
+                    metadata={
+                        "circuit_state": "open",
+                        "failure_count": self._failure_count,
+                        "last_error": str(e),
+                    },
+                )
+            raise
+
+    def _on_success(self) -> None:
+        self._failure_count = 0
+        self._state = CircuitState.CLOSED
+
+    def _on_failure(self) -> None:
+        self._failure_count += 1
+        self._last_failure_time = time.time()
+        if self._failure_count >= self._threshold:
+            self._state = CircuitState.OPEN

pyagent_patterns/registry.py

@@ -0,0 +1,71 @@
+"""Pattern registry: discover and instantiate patterns by name."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyagent_patterns.base import Pattern
+
+_REGISTRY: dict[str, type[Pattern]] = {}
+
+
+def register_pattern(name: str, cls: type[Pattern]) -> None:
+    """Register a pattern class under a name."""
+    _REGISTRY[name] = cls
+
+
+def get_pattern_class(name: str) -> type[Pattern] | None:
+    """Look up a pattern class by name."""
+    return _REGISTRY.get(name)
+
+
+def list_patterns() -> list[str]:
+    """Return all registered pattern names."""
+    return sorted(_REGISTRY.keys())
+
+
+def _auto_register() -> None:
+    """Auto-register all built-in patterns."""
+    from pyagent_patterns.advanced.human_in_the_loop import HumanInTheLoop
+    from pyagent_patterns.advanced.react import ReAct
+    from pyagent_patterns.advanced.swarm import Swarm
+    from pyagent_patterns.advanced.talker_reasoner import TalkerReasoner
+    from pyagent_patterns.orchestration.fan_out_fan_in import FanOutFanIn
+    from pyagent_patterns.orchestration.hierarchical import Hierarchical
+    from pyagent_patterns.orchestration.orchestrator_workers import OrchestratorWorkers
+    from pyagent_patterns.orchestration.pipeline import Pipeline
+    from pyagent_patterns.orchestration.supervisor import Supervisor
+    from pyagent_patterns.resolution.cross_reflection import CrossReflection
+    from pyagent_patterns.resolution.debate import Debate
+    from pyagent_patterns.resolution.evaluator_optimizer import EvaluatorOptimizer
+    from pyagent_patterns.resolution.self_reflection import SelfReflection
+    from pyagent_patterns.resolution.voting import Voting
+    from pyagent_patterns.structural.blackboard import Blackboard
+    from pyagent_patterns.structural.layered import Layered
+    from pyagent_patterns.structural.role_based import RoleBased
+    from pyagent_patterns.structural.topology import Topology
+
+    for name, cls in [
+        ("supervisor", Supervisor),
+        ("pipeline", Pipeline),
+        ("fan_out_fan_in", FanOutFanIn),
+        ("hierarchical", Hierarchical),
+        ("orchestrator_workers", OrchestratorWorkers),
+        ("self_reflection", SelfReflection),
+        ("cross_reflection", CrossReflection),
+        ("debate", Debate),
+        ("voting", Voting),
+        ("evaluator_optimizer", EvaluatorOptimizer),
+        ("role_based", RoleBased),
+        ("layered", Layered),
+        ("topology", Topology),
+        ("blackboard", Blackboard),
+        ("talker_reasoner", TalkerReasoner),
+        ("swarm", Swarm),
+        ("human_in_the_loop", HumanInTheLoop),
+        ("react", ReAct),
+    ]:
+        register_pattern(name, cls)
+
+
+_auto_register()

pyagent_patterns/resolution/__init__.py

@@ -0,0 +1,9 @@
+"""Tier 2: Resolution patterns — Reflection, CrossReflection, Debate, Voting, EvaluatorOptimizer."""
+
+from pyagent_patterns.resolution.cross_reflection import CrossReflection
+from pyagent_patterns.resolution.debate import Debate
+from pyagent_patterns.resolution.evaluator_optimizer import EvaluatorOptimizer
+from pyagent_patterns.resolution.self_reflection import SelfReflection
+from pyagent_patterns.resolution.voting import Voting
+
+__all__ = ["SelfReflection", "CrossReflection", "Debate", "Voting", "EvaluatorOptimizer"]

pyagent_patterns/resolution/cross_reflection.py

@@ -0,0 +1,79 @@
+"""Cross-Reflection pattern: Agent A generates → Agent B reviews → Agent A revises.
+
+Unlike Self-Reflection where one agent critiques itself, Cross-Reflection
+uses a separate peer agent to provide independent feedback, reducing bias.
+
+LLM calls: 3 minimum (generate + review + revise)
+"""
+
+from __future__ import annotations
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class CrossReflection(Pattern):
+    """Peer review: one agent generates, another reviews, generator revises.
+
+    Args:
+        generator: Agent that produces the initial output and revisions.
+        reviewer: Agent that reviews and provides feedback.
+        max_rounds: Maximum number of generate-review-revise cycles.
+        stop_phrase: If reviewer says this, stop early.
+    """
+
+    def __init__(
+        self,
+        generator: Agent,
+        reviewer: Agent,
+        max_rounds: int = 2,
+        stop_phrase: str = "APPROVED",
+    ) -> None:
+        self._generator = generator
+        self._reviewer = reviewer
+        self._max_rounds = max_rounds
+        self._stop_phrase = stop_phrase
+
+    @property
+    def pattern_type(self) -> str:
+        return "cross_reflection"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+        current_output = ""
+
+        for round_num in range(1, self._max_rounds + 1):
+            # Generate or revise
+            if round_num == 1:
+                gen_prompt = Message.user(ctx.task)
+            else:
+                gen_prompt = Message.user(
+                    f"Revise based on peer feedback:\n\n"
+                    f"Your output:\n{current_output}\n\n"
+                    f"Peer feedback:\n{review_text}"
+                )
+            gen_result = await self._generator.run([gen_prompt])
+            messages.append(gen_result)
+            current_output = gen_result.content
+
+            # Peer review
+            review_prompt = Message.user(
+                f"Review this output from your peer. Provide constructive feedback. "
+                f"If the output is satisfactory, respond with '{self._stop_phrase}'.\n\n"
+                f"{current_output}"
+            )
+            review_result = await self._reviewer.run([review_prompt])
+            messages.append(review_result)
+            review_text = review_result.content
+
+            if self._stop_phrase in review_result.content:
+                break
+
+        return Result(
+            output=current_output,
+            messages=messages,
+            metadata={
+                "rounds": round_num,
+                "generator": self._generator.name,
+                "reviewer": self._reviewer.name,
+            },
+        )

pyagent_patterns/resolution/debate.py

@@ -0,0 +1,103 @@
+"""Debate pattern: adversarial multi-round argumentation with a judge.
+
+Multiple debater agents argue different positions over several rounds.
+A judge agent evaluates arguments and renders a final decision.
+
+LLM calls: D debaters × R rounds + 1 judge = D*R + 1
+"""
+
+from __future__ import annotations
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class Debate(Pattern):
+    """Structured adversarial debate with judge resolution.
+
+    Args:
+        debaters: List of agents, each arguing a different position.
+        judge: Agent that evaluates arguments and renders final decision.
+        rounds: Number of argumentation rounds.
+        positions: Optional list of position labels (e.g., ["BUY", "SELL"]).
+            If not provided, positions are assigned as "Position 1", "Position 2", etc.
+    """
+
+    def __init__(
+        self,
+        debaters: list[Agent],
+        judge: Agent,
+        rounds: int = 3,
+        positions: list[str] | None = None,
+    ) -> None:
+        if len(debaters) < 2:
+            raise ValueError("Debate requires at least 2 debaters")
+        self._debaters = debaters
+        self._judge = judge
+        self._rounds = rounds
+        self._positions = positions or [f"Position {i + 1}" for i in range(len(debaters))]
+
+    @property
+    def pattern_type(self) -> str:
+        return "debate"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+        debate_log: list[dict[str, str]] = []
+
+        for round_num in range(1, self._rounds + 1):
+            round_args: list[str] = []
+
+            for i, debater in enumerate(self._debaters):
+                position = self._positions[i]
+                if round_num == 1:
+                    prompt = Message.user(
+                        f"You are arguing for '{position}' on this topic: {ctx.task}\n"
+                        f"Present your opening argument."
+                    )
+                else:
+                    opponent_args = "\n".join(
+                        f"- {self._positions[j]}: {a}"
+                        for j, a in enumerate(round_args_prev)
+                        if j != i
+                    )
+                    prompt = Message.user(
+                        f"You are arguing for '{position}'. Round {round_num}.\n"
+                        f"Counter these arguments:\n{opponent_args}\n\n"
+                        f"Strengthen your position."
+                    )
+
+                arg_result = await debater.run([prompt])
+                messages.append(arg_result)
+                round_args.append(arg_result.content)
+                debate_log.append({
+                    "round": round_num,
+                    "debater": debater.name,
+                    "position": position,
+                    "argument": arg_result.content,
+                })
+
+            round_args_prev = round_args
+
+        # Judge evaluates all arguments
+        full_debate = "\n\n".join(
+            f"[Round {entry['round']}] {entry['position']} ({entry['debater']}):\n{entry['argument']}"
+            for entry in debate_log
+        )
+        judge_prompt = Message.user(
+            f"You are the judge. Evaluate these arguments and render a final decision.\n"
+            f"Topic: {ctx.task}\n\n{full_debate}\n\n"
+            f"State your decision and reasoning."
+        )
+        verdict = await self._judge.run([judge_prompt])
+        messages.append(verdict)
+
+        return Result(
+            output=verdict.content,
+            messages=messages,
+            metadata={
+                "rounds": self._rounds,
+                "debaters": [d.name for d in self._debaters],
+                "positions": self._positions,
+                "debate_log": debate_log,
+            },
+        )