pyagent-patterns 0.1.0__py3-none-any.whl

pyagent_patterns/resolution/evaluator_optimizer.py

@@ -0,0 +1,108 @@
+"""Evaluator-Optimizer pattern: one agent generates, another evaluates against criteria.
+
+The generator produces output, the evaluator scores it against predefined criteria.
+If the score is below threshold, the generator revises based on evaluator feedback.
+
+LLM calls: 2 per round (generate + evaluate) × rounds
+"""
+
+from __future__ import annotations
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class EvaluatorOptimizer(Pattern):
+    """Generate → evaluate → revise loop with explicit evaluation criteria.
+
+    Args:
+        generator: Agent that produces and revises output.
+        evaluator: Agent that scores output against criteria.
+        criteria: List of evaluation criteria the evaluator checks.
+        max_rounds: Maximum optimization rounds.
+        pass_threshold: Score (1-10) at which the output is considered acceptable.
+    """
+
+    def __init__(
+        self,
+        generator: Agent,
+        evaluator: Agent,
+        criteria: list[str] | None = None,
+        max_rounds: int = 3,
+        pass_threshold: int = 7,
+    ) -> None:
+        self._generator = generator
+        self._evaluator = evaluator
+        self._criteria = criteria or ["correctness", "clarity", "completeness"]
+        self._max_rounds = max_rounds
+        self._pass_threshold = pass_threshold
+
+    @property
+    def pattern_type(self) -> str:
+        return "evaluator_optimizer"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+        current_output = ""
+        scores: list[int] = []
+
+        criteria_text = "\n".join(f"- {c}" for c in self._criteria)
+
+        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 your output based on evaluator feedback:\n\n"
+                    f"Previous output:\n{current_output}\n\n"
+                    f"Feedback:\n{eval_text}"
+                )
+            gen_result = await self._generator.run([gen_prompt])
+            messages.append(gen_result)
+            current_output = gen_result.content
+
+            # Evaluate
+            eval_prompt = Message.user(
+                f"Evaluate this output against these criteria:\n{criteria_text}\n\n"
+                f"Output to evaluate:\n{current_output}\n\n"
+                f"Provide a score (1-10) and specific feedback for improvement. "
+                f"Format: SCORE: N\nFEEDBACK: ..."
+            )
+            eval_result = await self._evaluator.run([eval_prompt])
+            messages.append(eval_result)
+            eval_text = eval_result.content
+
+            # Parse score
+            score = self._parse_score(eval_result.content)
+            scores.append(score)
+
+            if score >= self._pass_threshold:
+                break
+
+        return Result(
+            output=current_output,
+            messages=messages,
+            metadata={
+                "rounds": round_num,
+                "scores": scores,
+                "final_score": scores[-1] if scores else 0,
+                "passed": scores[-1] >= self._pass_threshold if scores else False,
+                "criteria": self._criteria,
+            },
+        )
+
+    @staticmethod
+    def _parse_score(content: str) -> int:
+        """Extract numeric score from evaluator response."""
+        for line in content.split("\n"):
+            line = line.strip().upper()
+            if line.startswith("SCORE:"):
+                try:
+                    return int(line.split(":")[1].strip().split()[0])
+                except (ValueError, IndexError):
+                    pass
+        # Fallback: look for any number between 1-10
+        import re
+
+        numbers = re.findall(r"\b([1-9]|10)\b", content)
+        return int(numbers[0]) if numbers else 5

pyagent_patterns/resolution/self_reflection.py

@@ -0,0 +1,80 @@
+"""Self-Reflection pattern: generate → self-critique → refine loop.
+
+The agent generates an initial output, critiques it for errors,
+then produces a revised output. Repeats until max rounds or confidence met.
+
+LLM calls: 2 per round × 1-N rounds = 2-2N
+"""
+
+from __future__ import annotations
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class SelfReflection(Pattern):
+    """Generate → critique → refine iterative loop.
+
+    Args:
+        agent: The agent that generates and refines output.
+        critic: Optional separate critic agent. If None, the same agent self-critiques.
+        max_rounds: Maximum number of generate-critique rounds.
+        stop_phrase: If the critic's response contains this phrase, stop early.
+    """
+
+    def __init__(
+        self,
+        agent: Agent,
+        critic: Agent | None = None,
+        max_rounds: int = 3,
+        stop_phrase: str = "APPROVED",
+    ) -> None:
+        self._agent = agent
+        self._critic = critic or agent
+        self._max_rounds = max_rounds
+        self._stop_phrase = stop_phrase
+
+    @property
+    def pattern_type(self) -> str:
+        return "self_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 refine)
+            if round_num == 1:
+                gen_prompt = Message.user(ctx.task)
+            else:
+                gen_prompt = Message.user(
+                    f"Revise your previous output based on this feedback:\n\n"
+                    f"Previous output:\n{current_output}\n\n"
+                    f"Feedback:\n{critique_text}"
+                )
+            gen_result = await self._agent.run([gen_prompt])
+            messages.append(gen_result)
+            current_output = gen_result.content
+
+            # Critique
+            critique_prompt = Message.user(
+                f"Review the following output for errors, gaps, or improvements. "
+                f"If the output is satisfactory, respond with '{self._stop_phrase}'. "
+                f"Otherwise, provide specific feedback.\n\n"
+                f"Output to review:\n{current_output}"
+            )
+            critique_result = await self._critic.run([critique_prompt])
+            messages.append(critique_result)
+            critique_text = critique_result.content
+
+            if self._stop_phrase in critique_result.content:
+                break
+
+        return Result(
+            output=current_output,
+            messages=messages,
+            metadata={
+                "rounds": round_num,
+                "max_rounds": self._max_rounds,
+                "early_stop": self._stop_phrase in messages[-1].content,
+            },
+        )

pyagent_patterns/resolution/voting.py

@@ -0,0 +1,93 @@
+"""Voting pattern: multiple agents vote independently, majority wins.
+
+Each agent produces an answer independently (can run in parallel).
+Supports majority voting, weighted voting, and ranked-choice.
+
+LLM calls: N agents (parallel)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import Counter
+from enum import Enum
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class VotingStrategy(str, Enum):
+    MAJORITY = "majority"
+    WEIGHTED = "weighted"
+
+
+class Voting(Pattern):
+    """Independent voting with configurable aggregation strategy.
+
+    Args:
+        voters: List of agents that each cast a vote.
+        strategy: Voting strategy (majority or weighted).
+        weights: Optional per-agent weights for weighted voting.
+            Must match length of voters. Defaults to equal weights.
+        normalize: If True, ask each voter to respond with a concise answer
+            suitable for comparison.
+    """
+
+    def __init__(
+        self,
+        voters: list[Agent],
+        strategy: VotingStrategy = VotingStrategy.MAJORITY,
+        weights: list[float] | None = None,
+        normalize: bool = True,
+    ) -> None:
+        if len(voters) < 2:
+            raise ValueError("Voting requires at least 2 voters")
+        self._voters = voters
+        self._strategy = strategy
+        self._weights = weights or [1.0] * len(voters)
+        self._normalize = normalize
+
+    @property
+    def pattern_type(self) -> str:
+        return "voting"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+
+        suffix = ""
+        if self._normalize:
+            suffix = "\n\nRespond with a concise answer (one word or short phrase) first, then explain."
+
+        # All voters run in parallel
+        tasks = [
+            voter.run([Message.user(ctx.task + suffix)]) for voter in self._voters
+        ]
+        votes = await asyncio.gather(*tasks)
+        messages.extend(votes)
+
+        # Extract vote labels (first line of each response)
+        vote_labels = [v.content.strip().split("\n")[0].strip() for v in votes]
+
+        # Tally
+        if self._strategy == VotingStrategy.MAJORITY:
+            counter = Counter(vote_labels)
+            winner = counter.most_common(1)[0][0]
+            tally = dict(counter)
+        else:
+            # Weighted voting
+            weighted_counts: dict[str, float] = {}
+            for label, weight in zip(vote_labels, self._weights):
+                weighted_counts[label] = weighted_counts.get(label, 0.0) + weight
+            winner = max(weighted_counts, key=weighted_counts.get)  # type: ignore[arg-type]
+            tally = weighted_counts
+
+        return Result(
+            output=winner,
+            messages=messages,
+            metadata={
+                "strategy": self._strategy.value,
+                "votes": vote_labels,
+                "tally": tally,
+                "winner": winner,
+                "voter_names": [v.name for v in self._voters],
+            },
+        )

pyagent_patterns/streaming.py

@@ -0,0 +1,119 @@
+"""Streaming support for patterns.
+
+Allows patterns to yield intermediate results as they execute, rather than
+waiting for the full result. Useful for real-time UIs and long-running workflows.
+
+Usage:
+    async for chunk in stream_pattern(pattern, "task"):
+        print(chunk.content, end="", flush=True)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator
+
+from pyagent_patterns.base import Pattern, Result
+
+
+@dataclass
+class StreamChunk:
+    """A single chunk of streaming output."""
+
+    content: str
+    agent_name: str = ""
+    chunk_type: str = "text"  # "text", "stage_complete", "round_complete", "final"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+async def stream_pattern(pattern: Pattern, task: str) -> AsyncIterator[StreamChunk]:
+    """Stream a pattern's execution, yielding chunks as they complete.
+
+    For patterns that don't natively support streaming, this wraps the
+    full execution and yields the result as a single final chunk.
+
+    For Pipeline patterns, yields after each stage completes.
+    For Fan-Out, yields as each parallel agent completes.
+    """
+    from pyagent_patterns.orchestration.pipeline import Pipeline
+    from pyagent_patterns.orchestration.fan_out_fan_in import FanOutFanIn
+
+    if isinstance(pattern, Pipeline):
+        async for chunk in _stream_pipeline(pattern, task):
+            yield chunk
+    elif isinstance(pattern, FanOutFanIn):
+        async for chunk in _stream_fanout(pattern, task):
+            yield chunk
+    else:
+        # Fallback: run full pattern and yield result as single chunk
+        result = await pattern.run(task)
+        yield StreamChunk(
+            content=result.output,
+            chunk_type="final",
+            metadata=result.metadata,
+        )
+
+
+async def _stream_pipeline(pipeline: Pattern, task: str) -> AsyncIterator[StreamChunk]:
+    """Stream a pipeline stage by stage."""
+    from pyagent_patterns.base import Message, Role
+
+    current_input = task
+    for i, stage in enumerate(pipeline._stages):
+        messages = [Message(role=Role.USER, content=current_input)]
+        if stage.system_prompt:
+            messages.insert(0, Message(role=Role.SYSTEM, content=stage.system_prompt))
+        response = await stage.llm.generate(messages)
+        current_input = response
+
+        is_last = i == len(pipeline._stages) - 1
+        yield StreamChunk(
+            content=response,
+            agent_name=stage.name,
+            chunk_type="final" if is_last else "stage_complete",
+            metadata={"stage": i, "stage_name": stage.name},
+        )
+
+
+async def _stream_fanout(fanout: Pattern, task: str) -> AsyncIterator[StreamChunk]:
+    """Stream fan-out as each parallel agent completes."""
+    from pyagent_patterns.base import Message, Role
+
+    queue: asyncio.Queue[StreamChunk | None] = asyncio.Queue()
+
+    async def run_agent(agent, idx: int) -> None:
+        messages = [Message(role=Role.USER, content=task)]
+        if agent.system_prompt:
+            messages.insert(0, Message(role=Role.SYSTEM, content=agent.system_prompt))
+        response = await agent.llm.generate(messages)
+        await queue.put(StreamChunk(
+            content=response,
+            agent_name=agent.name,
+            chunk_type="stage_complete",
+            metadata={"agent_index": idx},
+        ))
+
+    tasks = [asyncio.create_task(run_agent(a, i)) for i, a in enumerate(fanout._agents)]
+    done_count = 0
+    total = len(tasks)
+
+    while done_count < total:
+        chunk = await queue.get()
+        if chunk is not None:
+            done_count += 1
+            yield chunk
+
+    await asyncio.gather(*tasks)
+
+    # Aggregate
+    aggregated_input = "\n".join(
+        f"[{a.name}]: (see prior chunks)" for a in fanout._agents
+    )
+    result = await fanout.run(task)
+    yield StreamChunk(
+        content=result.output,
+        agent_name="aggregator",
+        chunk_type="final",
+        metadata=result.metadata,
+    )

pyagent_patterns/structural/__init__.py

@@ -0,0 +1,8 @@
+"""Tier 3: Structural patterns — RoleBased, Layered, Topology, Blackboard."""
+
+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, TopologyType
+
+__all__ = ["RoleBased", "Layered", "Topology", "TopologyType", "Blackboard"]

pyagent_patterns/structural/blackboard.py

@@ -0,0 +1,137 @@
+"""Blackboard / Shared-State pattern: agents read/write a shared async store.
+
+Agents don't communicate directly — they read from and write to a shared
+blackboard. Each agent specializes in reading certain keys and writing others.
+
+LLM calls: N agents × rounds
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class BlackboardEntry:
+    """A typed entry on the blackboard with history."""
+
+    def __init__(self, key: str, value: Any = None, author: str = "") -> None:
+        self.key = key
+        self.value = value
+        self.author = author
+        self.history: list[tuple[str, Any]] = []
+        if value is not None:
+            self.history.append((author, value))
+
+    def update(self, value: Any, author: str) -> None:
+        self.value = value
+        self.author = author
+        self.history.append((author, value))
+
+
+class BlackboardState:
+    """Shared state that agents read from and write to."""
+
+    def __init__(self) -> None:
+        self._entries: dict[str, BlackboardEntry] = {}
+
+    def read(self, key: str) -> Any:
+        entry = self._entries.get(key)
+        return entry.value if entry else None
+
+    def write(self, key: str, value: Any, author: str) -> None:
+        if key in self._entries:
+            self._entries[key].update(value, author)
+        else:
+            self._entries[key] = BlackboardEntry(key, value, author)
+
+    def keys(self) -> list[str]:
+        return list(self._entries.keys())
+
+    def snapshot(self) -> dict[str, Any]:
+        return {k: e.value for k, e in self._entries.items()}
+
+    def __repr__(self) -> str:
+        return f"BlackboardState({self.snapshot()})"
+
+
+class BlackboardAgent:
+    """An agent that reads from and writes to specific blackboard keys.
+
+    Args:
+        agent: The underlying LLM agent.
+        reads: Keys this agent reads from the blackboard.
+        writes: Keys this agent writes to the blackboard.
+    """
+
+    def __init__(self, agent: Agent, reads: list[str], writes: list[str]) -> None:
+        self.agent = agent
+        self.reads = reads
+        self.writes = writes
+
+
+class Blackboard(Pattern):
+    """Shared-state communication via a blackboard store.
+
+    Args:
+        agents: List of BlackboardAgent wrappers specifying read/write keys.
+        rounds: Number of rounds agents process the blackboard.
+        initial_state: Optional initial blackboard values.
+    """
+
+    def __init__(
+        self,
+        agents: list[BlackboardAgent],
+        rounds: int = 1,
+        initial_state: dict[str, Any] | None = None,
+    ) -> None:
+        self._agents = agents
+        self._rounds = rounds
+        self._initial_state = initial_state or {}
+
+    @property
+    def pattern_type(self) -> str:
+        return "blackboard"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+        board = BlackboardState()
+
+        # Initialize blackboard
+        board.write("task", ctx.task, "system")
+        for key, value in self._initial_state.items():
+            board.write(key, value, "system")
+
+        for round_num in range(1, self._rounds + 1):
+            for ba in self._agents:
+                # Build prompt from readable keys
+                readable = {k: board.read(k) for k in ba.reads if board.read(k) is not None}
+                prompt = (
+                    f"Task: {ctx.task}\n\n"
+                    f"Blackboard state (your readable keys):\n"
+                    + "\n".join(f"  {k}: {v}" for k, v in readable.items())
+                    + f"\n\nYou must produce values for: {', '.join(ba.writes)}\n"
+                    f"Respond with one value per line in format KEY: VALUE"
+                )
+
+                result = await ba.agent.run([Message.user(prompt)])
+                messages.append(result)
+
+                # Parse and write results to blackboard
+                for line in result.content.split("\n"):
+                    if ":" in line:
+                        key, _, value = line.partition(":")
+                        key = key.strip().lower().replace(" ", "_")
+                        if key in ba.writes:
+                            board.write(key, value.strip(), ba.agent.name)
+
+        return Result(
+            output=str(board.snapshot()),
+            messages=messages,
+            metadata={
+                "rounds": self._rounds,
+                "final_state": board.snapshot(),
+                "agents": [a.agent.name for a in self._agents],
+            },
+        )

pyagent_patterns/structural/layered.py

@@ -0,0 +1,70 @@
+"""Layered Cooperation pattern: agents organized into hierarchical abstraction layers.
+
+Each layer processes the output of the previous layer at a different level
+of abstraction. Layer 1 gathers data, Layer 2 analyzes, Layer 3 synthesizes.
+
+LLM calls: sum of agents across all layers
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+@dataclass
+class Layer:
+    """A named layer containing one or more parallel agents."""
+
+    name: str
+    agents: list[Agent]
+
+
+class Layered(Pattern):
+    """Hierarchical layers of agents with increasing abstraction.
+
+    Args:
+        layers: Ordered list of layers from bottom (data) to top (synthesis).
+    """
+
+    def __init__(self, layers: list[Layer]) -> None:
+        if not layers:
+            raise ValueError("Layered requires at least one layer")
+        self._layers = layers
+
+    @property
+    def pattern_type(self) -> str:
+        return "layered"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+        layer_input = ctx.task
+
+        for i, layer in enumerate(self._layers):
+            # Run all agents in this layer in parallel
+            tasks = [
+                agent.run([Message.user(layer_input)]) for agent in layer.agents
+            ]
+            layer_results = await asyncio.gather(*tasks)
+            messages.extend(layer_results)
+
+            # Combine layer output as input for next layer
+            if len(layer_results) == 1:
+                layer_input = layer_results[0].content
+            else:
+                layer_input = "\n\n".join(
+                    f"[{layer.agents[j].name}]: {r.content}"
+                    for j, r in enumerate(layer_results)
+                )
+
+        return Result(
+            output=layer_input,
+            messages=messages,
+            metadata={
+                "layer_count": len(self._layers),
+                "layer_names": [l.name for l in self._layers],
+                "agents_per_layer": [len(l.agents) for l in self._layers],
+            },
+        )

pyagent_patterns/structural/role_based.py

@@ -0,0 +1,61 @@
+"""Role-Based Cooperation pattern: agents adopt distinct functional roles.
+
+Most frequently used pattern (46.8% in arxiv:2511.08475).
+Each agent has a specialized role and they communicate in a structured order.
+
+LLM calls: N agents × rounds
+"""
+
+from __future__ import annotations
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class RoleBased(Pattern):
+    """Agents with distinct roles collaborate in structured rounds.
+
+    Args:
+        agents: List of role-specialized agents (order matters for turn-taking).
+        rounds: Number of communication rounds.
+        shared_context: If True, all agents see all prior messages. If False,
+            each agent only sees the immediately preceding message.
+    """
+
+    def __init__(
+        self,
+        agents: list[Agent],
+        rounds: int = 1,
+        shared_context: bool = True,
+    ) -> None:
+        self._agents = agents
+        self._rounds = rounds
+        self._shared_context = shared_context
+
+    @property
+    def pattern_type(self) -> str:
+        return "role_based"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+        conversation: list[Message] = [Message.user(ctx.task)]
+
+        for round_num in range(1, self._rounds + 1):
+            for agent in self._agents:
+                if self._shared_context:
+                    input_msgs = list(conversation)
+                else:
+                    input_msgs = [conversation[-1]] if conversation else [Message.user(ctx.task)]
+
+                response = await agent.run(input_msgs)
+                messages.append(response)
+                conversation.append(response)
+
+        return Result(
+            output=conversation[-1].content,
+            messages=messages,
+            metadata={
+                "rounds": self._rounds,
+                "roles": [a.name for a in self._agents],
+                "shared_context": self._shared_context,
+            },
+        )