pyagent-patterns 0.1.0__py3-none-any.whl

pyagent_patterns/__init__.py

@@ -0,0 +1,20 @@
+"""PyAgent Patterns — 18 reusable multi-agent orchestration patterns for LLMs."""
+
+from pyagent_patterns.base import Agent, Context, Message, MockLLM, Pattern, Result, Role
+from pyagent_patterns.composite import CompositePattern
+from pyagent_patterns.registry import get_pattern_class, list_patterns, register_pattern
+
+__all__ = [
+    "Agent",
+    "Context",
+    "CompositePattern",
+    "Message",
+    "MockLLM",
+    "Pattern",
+    "Result",
+    "Role",
+    "get_pattern_class",
+    "list_patterns",
+    "register_pattern",
+]
+__version__ = "0.1.0"

pyagent_patterns/advanced/__init__.py

@@ -0,0 +1,8 @@
+"""Tier 4: Advanced/Emergent patterns — TalkerReasoner, Swarm, HumanInTheLoop, ReAct."""
+
+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
+
+__all__ = ["TalkerReasoner", "Swarm", "HumanInTheLoop", "ReAct"]

pyagent_patterns/advanced/human_in_the_loop.py

@@ -0,0 +1,103 @@
+"""Human-in-the-Loop pattern: approval gates at critical decision points.
+
+An agent processes the task, then a human approval function decides
+whether to accept, reject, or modify the output before it proceeds.
+
+LLM calls: 1 agent + optional revision calls
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class HumanDecision:
+    """Result of a human review."""
+
+    def __init__(
+        self,
+        approved: bool,
+        feedback: str = "",
+        modified_output: str | None = None,
+    ) -> None:
+        self.approved = approved
+        self.feedback = feedback
+        self.modified_output = modified_output
+
+
+# Type alias for the human review callback
+HumanReviewFn = Callable[[str, dict[str, object]], HumanDecision]
+
+
+def auto_approve(output: str, metadata: dict[str, object]) -> HumanDecision:
+    """Default: auto-approve all outputs (for testing)."""
+    return HumanDecision(approved=True)
+
+
+class HumanInTheLoop(Pattern):
+    """Agent with human approval gate.
+
+    Args:
+        agent: The LLM agent that processes the task.
+        review_fn: Callable that presents output to human and returns decision.
+            Signature: (output: str, metadata: dict) -> HumanDecision
+        max_revisions: Maximum number of revision attempts after rejection.
+    """
+
+    def __init__(
+        self,
+        agent: Agent,
+        review_fn: HumanReviewFn = auto_approve,
+        max_revisions: int = 3,
+    ) -> None:
+        self._agent = agent
+        self._review_fn = review_fn
+        self._max_revisions = max_revisions
+
+    @property
+    def pattern_type(self) -> str:
+        return "human_in_the_loop"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+
+        # Initial agent response
+        response = await self._agent.run(ctx.messages)
+        messages.append(response)
+        current_output = response.content
+
+        for revision in range(self._max_revisions + 1):
+            # Human review
+            decision = self._review_fn(current_output, {"revision": revision, "task": ctx.task})
+
+            if decision.approved:
+                final_output = decision.modified_output or current_output
+                return Result(
+                    output=final_output,
+                    messages=messages,
+                    metadata={
+                        "approved": True,
+                        "revisions": revision,
+                        "human_modified": decision.modified_output is not None,
+                    },
+                )
+
+            if revision < self._max_revisions:
+                # Revise based on human feedback
+                revision_prompt = Message.user(
+                    f"Revise your output based on this feedback:\n\n"
+                    f"Your output:\n{current_output}\n\n"
+                    f"Feedback:\n{decision.feedback}"
+                )
+                response = await self._agent.run([revision_prompt])
+                messages.append(response)
+                current_output = response.content
+
+        # Max revisions exceeded — return last output with rejection flag
+        return Result(
+            output=current_output,
+            messages=messages,
+            metadata={"approved": False, "revisions": self._max_revisions},
+        )

pyagent_patterns/advanced/react.py

@@ -0,0 +1,132 @@
+"""ReAct pattern: Reason → Act → Observe cycle.
+
+The agent iteratively reasons about the task, takes an action (e.g., tool call),
+observes the result, then reasons again. Continues until the task is solved
+or max steps reached.
+
+LLM calls: 1 per step × max_steps
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+# Tool function type: (action_input: str) -> str
+ToolFn = Callable[[str], str]
+
+
+class ReAct(Pattern):
+    """Reasoning + Acting loop with tool use.
+
+    Args:
+        agent: The reasoning agent.
+        tools: Mapping of tool names to callable functions.
+        max_steps: Maximum number of Thought→Action→Observation cycles.
+        finish_token: Token in agent response that signals task completion.
+    """
+
+    def __init__(
+        self,
+        agent: Agent,
+        tools: dict[str, ToolFn] | None = None,
+        max_steps: int = 5,
+        finish_token: str = "FINISH",
+    ) -> None:
+        self._agent = agent
+        self._tools = tools or {}
+        self._max_steps = max_steps
+        self._finish_token = finish_token
+
+    @property
+    def pattern_type(self) -> str:
+        return "react"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+        trace: list[dict[str, Any]] = []
+
+        tool_list = ", ".join(self._tools.keys()) if self._tools else "none"
+        system_prompt = (
+            f"You are a ReAct agent. Available tools: {tool_list}\n\n"
+            f"On each step, respond in this EXACT format:\n"
+            f"Thought: [your reasoning]\n"
+            f"Action: [tool_name(input)] OR {self._finish_token}[final answer]\n\n"
+            f"After receiving an observation, continue reasoning.\n"
+            f"When you have the final answer, use: {self._finish_token}[your answer]"
+        )
+
+        conversation: list[Message] = [
+            Message.system(system_prompt),
+            Message.user(ctx.task),
+        ]
+
+        for step in range(1, self._max_steps + 1):
+            # Agent reasons and decides action
+            response = await self._agent.run(conversation)
+            messages.append(response)
+            conversation.append(response)
+
+            step_data: dict[str, Any] = {"step": step, "response": response.content}
+
+            # Check for finish
+            if self._finish_token in response.content:
+                # Extract final answer
+                parts = response.content.split(self._finish_token, 1)
+                final_answer = parts[1].strip() if len(parts) > 1 else response.content
+                step_data["action"] = "finish"
+                trace.append(step_data)
+                break
+
+            # Parse action
+            action_name, action_input = self._parse_action(response.content)
+            step_data["action"] = action_name
+            step_data["action_input"] = action_input
+
+            # Execute tool
+            if action_name and action_name in self._tools:
+                try:
+                    observation = self._tools[action_name](action_input)
+                except Exception as e:
+                    observation = f"Error: {e}"
+                step_data["observation"] = observation
+            else:
+                observation = f"Unknown tool: {action_name}. Available: {tool_list}"
+                step_data["observation"] = observation
+
+            trace.append(step_data)
+
+            # Feed observation back
+            obs_msg = Message.user(f"Observation: {observation}")
+            conversation.append(obs_msg)
+            messages.append(obs_msg)
+        else:
+            final_answer = messages[-1].content if messages else ""
+
+        return Result(
+            output=final_answer,
+            messages=messages,
+            metadata={
+                "steps": len(trace),
+                "max_steps": self._max_steps,
+                "trace": trace,
+                "tools_used": [t["action"] for t in trace if t.get("action") != "finish"],
+            },
+        )
+
+    @staticmethod
+    def _parse_action(content: str) -> tuple[str | None, str]:
+        """Parse 'Action: tool_name(input)' from agent response."""
+        for line in content.split("\n"):
+            line = line.strip()
+            if line.lower().startswith("action:"):
+                action_text = line.split(":", 1)[1].strip()
+                # Parse tool_name(input)
+                if "(" in action_text and action_text.endswith(")"):
+                    name = action_text[: action_text.index("(")]
+                    inp = action_text[action_text.index("(") + 1 : -1]
+                    return name.strip(), inp.strip().strip('"').strip("'")
+                return action_text, ""
+        return None, ""

pyagent_patterns/advanced/swarm.py

@@ -0,0 +1,106 @@
+"""Swarm pattern: emergent behavior from many agents with local rules, no controller.
+
+Each agent operates independently with simple local rules.
+Global behavior emerges from agent interactions. No central orchestrator.
+
+LLM calls: N agents × rounds
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class Swarm(Pattern):
+    """Decentralized swarm: agents interact locally, behavior emerges globally.
+
+    Args:
+        agents: Pool of swarm agents (all follow same local rules).
+        rounds: Number of interaction rounds.
+        neighbor_count: How many random peers each agent interacts with per round.
+        aggregation: How to produce final output from swarm state.
+            "last" = last round's outputs, "vote" = majority vote.
+    """
+
+    def __init__(
+        self,
+        agents: list[Agent],
+        rounds: int = 3,
+        neighbor_count: int = 2,
+        aggregation: str = "last",
+    ) -> None:
+        if len(agents) < 2:
+            raise ValueError("Swarm requires at least 2 agents")
+        self._agents = agents
+        self._rounds = rounds
+        self._neighbor_count = min(neighbor_count, len(agents) - 1)
+        self._aggregation = aggregation
+
+    @property
+    def pattern_type(self) -> str:
+        return "swarm"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+        # Initialize each agent's state
+        states: dict[str, str] = {}
+
+        # Round 0: each agent independently responds to the task
+        init_tasks = [agent.run([Message.user(ctx.task)]) for agent in self._agents]
+        init_results = await asyncio.gather(*init_tasks)
+        for agent, result in zip(self._agents, init_results):
+            states[agent.name] = result.content
+            messages.append(result)
+
+        # Subsequent rounds: agents interact with random neighbors
+        for round_num in range(1, self._rounds + 1):
+            new_states: dict[str, str] = {}
+
+            async def _update_agent(agent: Agent) -> tuple[str, str]:
+                # Select random neighbors
+                others = [a for a in self._agents if a.name != agent.name]
+                neighbors = random.sample(others, min(self._neighbor_count, len(others)))
+
+                neighbor_views = "\n".join(
+                    f"- {n.name}: {states[n.name]}" for n in neighbors
+                )
+                prompt = Message.user(
+                    f"Task: {ctx.task}\n\n"
+                    f"Your current response: {states[agent.name]}\n\n"
+                    f"Neighbor responses:\n{neighbor_views}\n\n"
+                    f"Update your response considering your neighbors' views."
+                )
+                result = await agent.run([prompt])
+                return agent.name, result.content
+
+            update_tasks = [_update_agent(agent) for agent in self._agents]
+            updates = await asyncio.gather(*update_tasks)
+            for name, content in updates:
+                new_states[name] = content
+                messages.append(Message.assistant(content, name=name))
+
+            states = new_states
+
+        # Aggregate final output
+        if self._aggregation == "vote":
+            from collections import Counter
+
+            first_lines = [s.split("\n")[0].strip() for s in states.values()]
+            winner = Counter(first_lines).most_common(1)[0][0]
+            output = winner
+        else:
+            output = "\n\n".join(f"[{name}]: {content}" for name, content in states.items())
+
+        return Result(
+            output=output,
+            messages=messages,
+            metadata={
+                "agents": len(self._agents),
+                "rounds": self._rounds,
+                "aggregation": self._aggregation,
+                "final_states": states,
+            },
+        )

pyagent_patterns/advanced/talker_reasoner.py

@@ -0,0 +1,92 @@
+"""Talker-Reasoner pattern: System 1 (fast/cheap) + System 2 (slow/expensive).
+
+Inspired by Kahneman's dual-process theory and Google DeepMind's 2024 paper.
+A fast "talker" handles routine queries; a slow "reasoner" is activated
+only for complex queries that exceed a complexity threshold.
+
+LLM calls: 1 (easy) or 2 (hard: classifier + reasoner) or 3 (with classifier)
+"""
+
+from __future__ import annotations
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class TalkerReasoner(Pattern):
+    """Dual-process: fast intuition (System 1) + slow deliberation (System 2).
+
+    Args:
+        talker: Fast, cheap agent for routine queries (System 1).
+        reasoner: Slow, expensive agent for complex queries (System 2).
+        classifier: Optional agent that decides talker vs reasoner.
+            If None, always starts with talker and escalates on uncertainty keywords.
+        complexity_threshold: Keywords in talker output that trigger escalation to reasoner.
+    """
+
+    def __init__(
+        self,
+        talker: Agent,
+        reasoner: Agent,
+        classifier: Agent | None = None,
+        complexity_threshold: list[str] | None = None,
+    ) -> None:
+        self._talker = talker
+        self._reasoner = reasoner
+        self._classifier = classifier
+        self._complexity_keywords = complexity_threshold or [
+            "I'm not sure",
+            "I don't know",
+            "complex",
+            "need to think",
+            "uncertain",
+            "ESCALATE",
+        ]
+
+    @property
+    def pattern_type(self) -> str:
+        return "talker_reasoner"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+
+        if self._classifier:
+            # Use classifier to decide
+            classify_prompt = Message.user(
+                f"Is this query simple or complex? "
+                f"Respond with exactly 'SIMPLE' or 'COMPLEX'.\n\n"
+                f"Query: {ctx.task}"
+            )
+            classification = await self._classifier.run([classify_prompt])
+            messages.append(classification)
+            use_reasoner = "COMPLEX" in classification.content.upper()
+        else:
+            use_reasoner = False
+
+        if not use_reasoner:
+            # System 1: fast talker
+            talker_result = await self._talker.run(ctx.messages)
+            messages.append(talker_result)
+
+            # Check if talker signals uncertainty → escalate to reasoner
+            should_escalate = any(
+                kw.lower() in talker_result.content.lower() for kw in self._complexity_keywords
+            )
+
+            if should_escalate:
+                use_reasoner = True
+            else:
+                return Result(
+                    output=talker_result.content,
+                    messages=messages,
+                    metadata={"system": "talker", "escalated": False},
+                )
+
+        # System 2: slow reasoner
+        reasoner_result = await self._reasoner.run(ctx.messages)
+        messages.append(reasoner_result)
+
+        return Result(
+            output=reasoner_result.content,
+            messages=messages,
+            metadata={"system": "reasoner", "escalated": not bool(self._classifier)},
+        )

pyagent_patterns/advisor.py

@@ -0,0 +1,166 @@
+"""PatternAdvisor: recommend the best pattern based on task constraints.
+
+Based on: Augment 2026 "Five Decision Rules" for pattern selection.
+
+Decision factors:
+1. Task complexity (simple vs multi-step vs adversarial)
+2. Quality requirement (draft vs production)
+3. Budget constraint (tokens/$)
+4. Latency requirement (real-time vs batch)
+5. Reliability requirement (best-effort vs fault-tolerant)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Quality(str, Enum):
+    DRAFT = "draft"
+    STANDARD = "standard"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class Latency(str, Enum):
+    REALTIME = "realtime"  # < 2s
+    INTERACTIVE = "interactive"  # < 10s
+    BATCH = "batch"  # minutes OK
+
+
+@dataclass
+class Constraints:
+    """Task constraints for pattern selection."""
+
+    quality: Quality = Quality.STANDARD
+    latency: Latency = Latency.INTERACTIVE
+    max_cost_usd: float = 0.05
+    fault_tolerant: bool = False
+    multi_step: bool = False
+
+
+@dataclass
+class Recommendation:
+    """A pattern recommendation with reasoning."""
+
+    pattern: str
+    reason: str
+    estimated_calls: int
+    estimated_cost_range: str
+    alternatives: list[str]
+
+
+class PatternAdvisor:
+    """Recommend patterns based on task description and constraints.
+
+    Usage:
+        advisor = PatternAdvisor()
+        rec = advisor.recommend("Write and review code", Constraints(quality=Quality.HIGH))
+        print(rec.pattern, rec.reason)
+    """
+
+    def recommend(self, task: str, constraints: Constraints | None = None) -> Recommendation:
+        """Recommend the best pattern for the given task and constraints."""
+        c = constraints or Constraints()
+        task_lower = task.lower()
+
+        # Decision tree based on Augment 2026 "Five Decision Rules"
+
+        # Rule 1: Simple single-step tasks → Pipeline or single agent
+        if not c.multi_step and c.quality in (Quality.DRAFT, Quality.STANDARD):
+            if c.latency == Latency.REALTIME:
+                return Recommendation(
+                    pattern="pipeline",
+                    reason="Simple task with real-time latency → minimal sequential processing",
+                    estimated_calls=1,
+                    estimated_cost_range="$0.001-0.003",
+                    alternatives=["talker_reasoner"],
+                )
+
+        # Rule 2: Cost-sensitive → Route to cheapest viable model
+        if c.max_cost_usd < 0.01:
+            return Recommendation(
+                pattern="talker_reasoner",
+                reason="Tight budget → use cheap model for easy, expensive only when needed",
+                estimated_calls=1,
+                estimated_cost_range="$0.001-0.005",
+                alternatives=["pipeline"],
+            )
+
+        # Rule 3: High reliability / fault tolerance → Voting or Fan-Out
+        if c.fault_tolerant:
+            return Recommendation(
+                pattern="voting",
+                reason="Fault-tolerant requirement → multiple independent agents with consensus",
+                estimated_calls=3,
+                estimated_cost_range="$0.006-0.012",
+                alternatives=["fan_out_fan_in"],
+            )
+
+        # Rule 4: High quality → Reflection, Debate, or Evaluator
+        if c.quality in (Quality.HIGH, Quality.CRITICAL):
+            # Check for adversarial/debate keywords
+            if any(w in task_lower for w in ["compare", "pros and cons", "debate", "argue", "versus"]):
+                return Recommendation(
+                    pattern="debate",
+                    reason="High quality + adversarial task → structured debate with judge",
+                    estimated_calls=7,
+                    estimated_cost_range="$0.014-0.028",
+                    alternatives=["evaluator_optimizer", "cross_reflection"],
+                )
+
+            # Check for code/writing that benefits from review
+            if any(w in task_lower for w in ["write", "code", "generate", "create", "draft"]):
+                return Recommendation(
+                    pattern="self_reflection",
+                    reason="High quality creative/code task → generate-critique-refine loop",
+                    estimated_calls=4,
+                    estimated_cost_range="$0.004-0.012",
+                    alternatives=["cross_reflection", "evaluator_optimizer"],
+                )
+
+            return Recommendation(
+                pattern="evaluator_optimizer",
+                reason="High quality task → explicit evaluation criteria with optimization",
+                estimated_calls=4,
+                estimated_cost_range="$0.004-0.008",
+                alternatives=["self_reflection"],
+            )
+
+        # Rule 5: Multi-step/complex → Supervisor, Hierarchical, or Pipeline
+        if c.multi_step or any(w in task_lower for w in ["steps", "process", "workflow", "pipeline"]):
+            if any(w in task_lower for w in ["team", "delegate", "manage", "coordinate"]):
+                return Recommendation(
+                    pattern="hierarchical",
+                    reason="Multi-step with team coordination → hierarchical delegation",
+                    estimated_calls=7,
+                    estimated_cost_range="$0.010-0.020",
+                    alternatives=["supervisor", "orchestrator_workers"],
+                )
+
+            if any(w in task_lower for w in ["classify", "route", "triage", "categorize"]):
+                return Recommendation(
+                    pattern="supervisor",
+                    reason="Multi-step with classification → supervisor routes to specialists",
+                    estimated_calls=3,
+                    estimated_cost_range="$0.004-0.008",
+                    alternatives=["pipeline"],
+                )
+
+            return Recommendation(
+                pattern="pipeline",
+                reason="Multi-step sequential task → stage-by-stage processing",
+                estimated_calls=4,
+                estimated_cost_range="$0.004-0.008",
+                alternatives=["supervisor"],
+            )
+
+        # Default: Pipeline (safest general-purpose)
+        return Recommendation(
+            pattern="pipeline",
+            reason="General-purpose task → sequential pipeline with composable stages",
+            estimated_calls=2,
+            estimated_cost_range="$0.002-0.004",
+            alternatives=["supervisor", "self_reflection"],
+        )