pyagent-patterns 0.1.0__tar.gz

pyagent_patterns-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+site/
+.env
+*.log

pyagent_patterns-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: pyagent-patterns
+Version: 0.1.0
+Summary: 18 reusable multi-agent orchestration patterns for LLMs
+License: MIT
+Keywords: LLM,agents,multi-agent,orchestration,patterns
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyagent-patterns
+
+**18 reusable multi-agent orchestration patterns for LLMs** — zero dependencies, async-first, fully typed.
+
+## Install
+
+```bash
+pip install pyagent-patterns
+```
+
+## Patterns
+
+| Tier | Patterns |
+|------|----------|
+| Orchestration | Supervisor, Pipeline, Fan-Out/Fan-In, Hierarchical, Orchestrator-Workers |
+| Resolution | Self-Reflection, Cross-Reflection, Debate, Voting, Evaluator-Optimizer |
+| Structural | Role-Based, Layered, Topology, Blackboard |
+| Advanced | Talker-Reasoner, Swarm, Human-in-the-Loop, ReAct |
+
+Plus: CompositePattern (escalation chains), PatternAdvisor, GuardrailChain, BoundedExecution, CircuitBreaker.
+
+## Quick Example
+
+```python
+import asyncio
+from pyagent_patterns.base import Agent, MockLLM
+from pyagent_patterns.resolution import SelfReflection
+
+llm = MockLLM(responses=["Draft code", "Needs error handling", "Improved code", "APPROVED"])
+pattern = SelfReflection(agent=Agent("coder", llm), max_rounds=3)
+result = asyncio.run(pattern.run("Write a sorting function"))
+print(result.output)
+```
+
+## Documentation
+
+Full docs: [pyagent.dev](https://pyagent.dev)

pyagent_patterns-0.1.0/README.md

@@ -0,0 +1,37 @@
+# pyagent-patterns
+
+**18 reusable multi-agent orchestration patterns for LLMs** — zero dependencies, async-first, fully typed.
+
+## Install
+
+```bash
+pip install pyagent-patterns
+```
+
+## Patterns
+
+| Tier | Patterns |
+|------|----------|
+| Orchestration | Supervisor, Pipeline, Fan-Out/Fan-In, Hierarchical, Orchestrator-Workers |
+| Resolution | Self-Reflection, Cross-Reflection, Debate, Voting, Evaluator-Optimizer |
+| Structural | Role-Based, Layered, Topology, Blackboard |
+| Advanced | Talker-Reasoner, Swarm, Human-in-the-Loop, ReAct |
+
+Plus: CompositePattern (escalation chains), PatternAdvisor, GuardrailChain, BoundedExecution, CircuitBreaker.
+
+## Quick Example
+
+```python
+import asyncio
+from pyagent_patterns.base import Agent, MockLLM
+from pyagent_patterns.resolution import SelfReflection
+
+llm = MockLLM(responses=["Draft code", "Needs error handling", "Improved code", "APPROVED"])
+pattern = SelfReflection(agent=Agent("coder", llm), max_rounds=3)
+result = asyncio.run(pattern.run("Write a sorting function"))
+print(result.output)
+```
+
+## Documentation
+
+Full docs: [pyagent.dev](https://pyagent.dev)

pyagent_patterns-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyagent-patterns"
+version = "0.1.0"
+description = "18 reusable multi-agent orchestration patterns for LLMs"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+keywords = ["agents", "multi-agent", "LLM", "patterns", "orchestration"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "ruff>=0.5", "mypy>=1.10"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyagent_patterns"]

pyagent_patterns-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)},
+        )