pyagent-patterns 0.1.0__py3-none-any.whl

pyagent_patterns/base.py

@@ -0,0 +1,215 @@
+"""Core abstractions: Pattern, Agent, Message, Context, Result."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, AsyncIterator, Callable, Protocol, runtime_checkable
+
+
+class Role(str, Enum):
+    """Well-known agent roles."""
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    """A single message in an agent conversation.
+
+    Attributes:
+        role: The sender role (system, user, assistant, tool).
+        content: The text content of the message.
+        name: Optional agent name for multi-agent conversations.
+        metadata: Arbitrary key-value metadata attached to the message.
+    """
+
+    role: Role
+    content: str
+    name: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def system(cls, content: str, **kw: Any) -> Message:
+        return cls(role=Role.SYSTEM, content=content, **kw)
+
+    @classmethod
+    def user(cls, content: str, **kw: Any) -> Message:
+        return cls(role=Role.USER, content=content, **kw)
+
+    @classmethod
+    def assistant(cls, content: str, name: str | None = None, **kw: Any) -> Message:
+        return cls(role=Role.ASSISTANT, content=content, name=name, **kw)
+
+
+@runtime_checkable
+class LLMCallable(Protocol):
+    """Protocol for any LLM backend — sync or async."""
+
+    async def __call__(self, messages: list[Message]) -> str: ...
+
+
+class MockLLM:
+    """A mock LLM for testing that echoes or returns canned responses.
+
+    Args:
+        responses: If provided, returns these in order (cycling). Otherwise echoes last user message.
+        delay: Simulated latency in seconds.
+    """
+
+    def __init__(self, responses: list[str] | None = None, delay: float = 0.0) -> None:
+        self._responses = responses or []
+        self._index = 0
+        self._delay = delay
+        self.call_count = 0
+        self.call_log: list[list[Message]] = []
+
+    async def __call__(self, messages: list[Message]) -> str:
+        if self._delay > 0:
+            await asyncio.sleep(self._delay)
+        self.call_count += 1
+        self.call_log.append(list(messages))
+        if self._responses:
+            resp = self._responses[self._index % len(self._responses)]
+            self._index += 1
+            return resp
+        # Echo the last user message
+        for msg in reversed(messages):
+            if msg.role == Role.USER:
+                return f"[MockLLM] Echo: {msg.content}"
+        return "[MockLLM] No user message found"
+
+
+@dataclass
+class Context:
+    """Shared execution context for a pattern run.
+
+    Attributes:
+        task: The original user task/prompt.
+        messages: Accumulated message history.
+        metadata: Arbitrary shared state across agents.
+        parent_id: ID of the parent context (for nested patterns).
+    """
+
+    task: str
+    messages: list[Message] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    parent_id: str | None = None
+    _id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    def child(self, task: str | None = None) -> Context:
+        """Create a child context for nested pattern execution."""
+        return Context(
+            task=task or self.task,
+            metadata=dict(self.metadata),
+            parent_id=self._id,
+        )
+
+
+@dataclass
+class Result:
+    """Outcome of a pattern execution.
+
+    Attributes:
+        output: The final output text.
+        messages: All messages generated during execution.
+        metadata: Pattern-specific metadata (rounds, consensus, votes, etc.).
+        duration_seconds: Wall-clock execution time.
+        token_estimate: Rough estimate of total tokens consumed.
+        cost_estimate: Rough estimate of total cost in USD.
+    """
+
+    output: str
+    messages: list[Message] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    duration_seconds: float = 0.0
+    token_estimate: int = 0
+    cost_estimate: float = 0.0
+
+
+@dataclass
+class Agent:
+    """An LLM-backed agent with a name, system prompt, and callable.
+
+    Args:
+        name: Human-readable agent name.
+        llm: The LLM callable to use for this agent.
+        system_prompt: Optional system prompt prepended to every call.
+        description: Description of the agent's purpose (for routing/selection).
+    """
+
+    name: str
+    llm: LLMCallable
+    system_prompt: str = ""
+    description: str = ""
+
+    async def run(self, messages: list[Message]) -> Message:
+        """Send messages to the LLM and return an assistant message."""
+        call_messages = list(messages)
+        if self.system_prompt:
+            call_messages.insert(0, Message.system(self.system_prompt))
+        content = await self.llm(call_messages)
+        return Message.assistant(content, name=self.name)
+
+
+class Pattern(ABC):
+    """Abstract base class for all multi-agent patterns.
+
+    Subclasses must implement `_execute`. The `run` method handles timing,
+    context creation, and metadata collection.
+    """
+
+    @property
+    @abstractmethod
+    def pattern_type(self) -> str:
+        """Return the pattern type name (e.g., 'supervisor', 'debate')."""
+        ...
+
+    async def run(self, task: str, context: Context | None = None) -> Result:
+        """Execute the pattern on the given task.
+
+        Args:
+            task: The user task or prompt.
+            context: Optional existing context. Created automatically if None.
+
+        Returns:
+            Result with output, messages, metadata, timing, and cost estimates.
+        """
+        ctx = context or Context(task=task)
+        ctx.messages.append(Message.user(task))
+
+        start = time.perf_counter()
+        result = await self._execute(ctx)
+        result.duration_seconds = time.perf_counter() - start
+        result.metadata["pattern_type"] = self.pattern_type
+
+        # Rough token estimate: ~4 chars per token
+        total_chars = sum(len(m.content) for m in result.messages)
+        result.token_estimate = total_chars // 4
+
+        return result
+
+    @abstractmethod
+    async def _execute(self, ctx: Context) -> Result:
+        """Implement the pattern logic. Called by `run`."""
+        ...
+
+    async def stream(self, task: str, context: Context | None = None) -> AsyncIterator[str]:
+        """Stream partial results as they become available.
+
+        Default implementation runs the full pattern and yields the result.
+        Subclasses can override for true streaming.
+        """
+        result = await self.run(task, context)
+        yield result.output

pyagent_patterns/composite.py

@@ -0,0 +1,105 @@
+"""Composite patterns: chain/nest multiple patterns with escalation triggers.
+
+CompositePattern runs patterns in sequence, escalating to the next
+if the current pattern's result doesn't meet a quality check.
+
+EscalationChain is a pre-built composite: Reflection → Debate → Voting → Human.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from pyagent_patterns.base import Context, Pattern, Result
+
+
+# Quality check: returns True if the result is acceptable
+QualityCheckFn = Callable[[Result], bool]
+
+
+def always_pass(result: Result) -> bool:
+    """Default quality check: always passes."""
+    return True
+
+
+def min_length_check(min_chars: int = 50) -> QualityCheckFn:
+    """Quality check: output must be at least min_chars characters."""
+
+    def check(result: Result) -> bool:
+        return len(result.output) >= min_chars
+
+    return check
+
+
+class CompositePattern(Pattern):
+    """Chain multiple patterns with escalation on quality failure.
+
+    Args:
+        patterns: Ordered list of patterns to try.
+        quality_check: Function that evaluates whether a pattern's result
+            is acceptable. If it returns False, the next pattern is tried.
+        combine_results: If True, passes previous output as context to next pattern.
+    """
+
+    def __init__(
+        self,
+        patterns: list[Pattern],
+        quality_check: QualityCheckFn = always_pass,
+        combine_results: bool = True,
+    ) -> None:
+        if not patterns:
+            raise ValueError("CompositePattern requires at least one pattern")
+        self._patterns = patterns
+        self._quality_check = quality_check
+        self._combine_results = combine_results
+
+    @property
+    def pattern_type(self) -> str:
+        types = [p.pattern_type for p in self._patterns]
+        return f"composite({'+'.join(types)})"
+
+    async def _execute(self, ctx: Context) -> Result:
+        all_messages = []
+        escalation_log = []
+
+        for i, pattern in enumerate(self._patterns):
+            # Create child context for each pattern
+            child_ctx = ctx.child()
+
+            result = await pattern._execute(child_ctx)
+            all_messages.extend(result.messages)
+            escalation_log.append({
+                "pattern": pattern.pattern_type,
+                "output_length": len(result.output),
+                "metadata": result.metadata,
+            })
+
+            if self._quality_check(result):
+                return Result(
+                    output=result.output,
+                    messages=all_messages,
+                    metadata={
+                        "escalation_level": i,
+                        "pattern_used": pattern.pattern_type,
+                        "escalation_log": escalation_log,
+                        "total_patterns_tried": i + 1,
+                    },
+                )
+
+            # If not last pattern and combining, update context with current output
+            if self._combine_results and i < len(self._patterns) - 1:
+                ctx.metadata["previous_output"] = result.output
+                ctx.metadata["previous_pattern"] = pattern.pattern_type
+
+        # All patterns tried, return last result
+        return Result(
+            output=result.output,
+            messages=all_messages,
+            metadata={
+                "escalation_level": len(self._patterns) - 1,
+                "pattern_used": self._patterns[-1].pattern_type,
+                "escalation_log": escalation_log,
+                "total_patterns_tried": len(self._patterns),
+                "fully_escalated": True,
+            },
+        )

pyagent_patterns/guardrails.py

@@ -0,0 +1,165 @@
+"""Guardrail Layer: validate input, output, and inter-agent messages.
+
+Based on: Microsoft Azure AI Agent Patterns Guide
+          Augment 2026 "Guardrail Layering (P11)"
+
+Four insertion points:
+1. Input guardrail: before the pattern receives user input
+2. Inter-agent guardrail: between agent communications
+3. Tool-call guardrail: before tool execution
+4. Output guardrail: before returning final result
+"""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class GuardrailResult:
+    """Result of a guardrail check."""
+
+    passed: bool
+    message: str = ""
+    sanitized_content: str | None = None  # Modified content if sanitization applied
+
+
+class Guardrail(ABC):
+    """Abstract base for all guardrails."""
+
+    @abstractmethod
+    def check(self, content: str) -> GuardrailResult:
+        """Check content against this guardrail's rules."""
+        ...
+
+
+class LengthGuard(Guardrail):
+    """Reject messages exceeding a maximum length.
+
+    Args:
+        max_chars: Maximum allowed characters.
+        truncate: If True, truncate instead of rejecting.
+    """
+
+    def __init__(self, max_chars: int = 10000, truncate: bool = False) -> None:
+        self._max_chars = max_chars
+        self._truncate = truncate
+
+    def check(self, content: str) -> GuardrailResult:
+        if len(content) <= self._max_chars:
+            return GuardrailResult(passed=True)
+        if self._truncate:
+            return GuardrailResult(
+                passed=True,
+                message=f"Truncated from {len(content)} to {self._max_chars} chars",
+                sanitized_content=content[: self._max_chars] + "... [truncated]",
+            )
+        return GuardrailResult(
+            passed=False,
+            message=f"Content exceeds maximum length: {len(content)}/{self._max_chars} chars",
+        )
+
+
+class PIIGuard(Guardrail):
+    """Detect and optionally redact personally identifiable information.
+
+    Detects: email addresses, phone numbers, SSNs, credit card numbers.
+
+    Args:
+        redact: If True, redact PII and pass. If False, reject on detection.
+    """
+
+    _PATTERNS = {
+        "email": r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b",
+        "phone": r"\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b",
+        "ssn": r"\b\d{3}[-]?\d{2}[-]?\d{4}\b",
+        "credit_card": r"\b(?:\d{4}[-\s]?){3}\d{4}\b",
+    }
+
+    def __init__(self, redact: bool = True) -> None:
+        self._redact = redact
+
+    def check(self, content: str) -> GuardrailResult:
+        detections: list[str] = []
+        sanitized = content
+
+        for pii_type, pattern in self._PATTERNS.items():
+            matches = re.findall(pattern, content)
+            if matches:
+                detections.append(f"{pii_type}: {len(matches)} found")
+                if self._redact:
+                    sanitized = re.sub(pattern, f"[REDACTED-{pii_type.upper()}]", sanitized)
+
+        if not detections:
+            return GuardrailResult(passed=True)
+
+        if self._redact:
+            return GuardrailResult(
+                passed=True,
+                message=f"PII redacted: {', '.join(detections)}",
+                sanitized_content=sanitized,
+            )
+
+        return GuardrailResult(
+            passed=False,
+            message=f"PII detected: {', '.join(detections)}",
+        )
+
+
+class ContentGuard(Guardrail):
+    """Block content matching configurable deny patterns.
+
+    Args:
+        deny_patterns: List of regex patterns that should be blocked.
+        deny_words: List of exact words/phrases to block.
+    """
+
+    def __init__(
+        self,
+        deny_patterns: list[str] | None = None,
+        deny_words: list[str] | None = None,
+    ) -> None:
+        self._patterns = [re.compile(p, re.IGNORECASE) for p in (deny_patterns or [])]
+        self._words = [w.lower() for w in (deny_words or [])]
+
+    def check(self, content: str) -> GuardrailResult:
+        content_lower = content.lower()
+
+        for word in self._words:
+            if word in content_lower:
+                return GuardrailResult(passed=False, message=f"Blocked word detected: '{word}'")
+
+        for pattern in self._patterns:
+            if pattern.search(content):
+                return GuardrailResult(
+                    passed=False, message=f"Blocked pattern matched: {pattern.pattern}"
+                )
+
+        return GuardrailResult(passed=True)
+
+
+class GuardrailChain:
+    """Chain multiple guardrails together. All must pass.
+
+    Args:
+        guardrails: List of guardrails to apply in order.
+    """
+
+    def __init__(self, guardrails: list[Guardrail]) -> None:
+        self._guardrails = guardrails
+
+    def check(self, content: str) -> GuardrailResult:
+        current_content = content
+
+        for guard in self._guardrails:
+            result = guard.check(current_content)
+            if not result.passed:
+                return result
+            if result.sanitized_content is not None:
+                current_content = result.sanitized_content
+
+        if current_content != content:
+            return GuardrailResult(passed=True, sanitized_content=current_content)
+        return GuardrailResult(passed=True)

pyagent_patterns/orchestration/__init__.py

@@ -0,0 +1,9 @@
+"""Tier 1: Orchestration patterns — Supervisor, Pipeline, FanOut, Hierarchical, OrchestratorWorkers."""
+
+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
+
+__all__ = ["Supervisor", "Pipeline", "FanOutFanIn", "Hierarchical", "OrchestratorWorkers"]

pyagent_patterns/orchestration/fan_out_fan_in.py

@@ -0,0 +1,76 @@
+"""Fan-Out / Fan-In pattern: broadcast task to N agents in parallel, aggregate results.
+
+All agents receive the same task and run concurrently. An aggregator
+combines their outputs into a unified response.
+
+LLM calls: N agents (parallel) + 1 aggregator = N+1 total
+Wall-clock latency: max(agent latencies) + aggregator
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import AsyncIterator
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+class FanOutFanIn(Pattern):
+    """Parallel execution with result aggregation.
+
+    Args:
+        agents: List of agents to run in parallel on the same task.
+        aggregator: Agent that combines all parallel outputs into one.
+    """
+
+    def __init__(self, agents: list[Agent], aggregator: Agent) -> None:
+        if not agents:
+            raise ValueError("FanOutFanIn requires at least one agent")
+        self._agents = agents
+        self._aggregator = aggregator
+
+    @property
+    def pattern_type(self) -> str:
+        return "fan_out_fan_in"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+
+        # Fan-out: run all agents in parallel
+        tasks = [agent.run(ctx.messages) for agent in self._agents]
+        parallel_results = await asyncio.gather(*tasks)
+        messages.extend(parallel_results)
+
+        # Fan-in: aggregate results
+        combined = "\n\n".join(
+            f"--- {self._agents[i].name} ---\n{r.content}"
+            for i, r in enumerate(parallel_results)
+        )
+        agg_prompt = Message.user(
+            f"Combine the following analyses into a unified response:\n\n{combined}"
+        )
+        aggregated = await self._aggregator.run([agg_prompt])
+        messages.append(aggregated)
+
+        return Result(
+            output=aggregated.content,
+            messages=messages,
+            metadata={
+                "parallel_agents": len(self._agents),
+                "agent_names": [a.name for a in self._agents],
+            },
+        )
+
+    async def stream(self, task: str, context: Context | None = None) -> AsyncIterator[str]:
+        """Stream individual agent results as they complete."""
+        ctx = context or Context(task=task)
+        ctx.messages.append(Message.user(task))
+
+        async def _run_one(agent: Agent) -> tuple[str, str]:
+            result = await agent.run(ctx.messages)
+            return agent.name, result.content
+
+        tasks = [_run_one(agent) for agent in self._agents]
+        for coro in asyncio.as_completed(tasks):
+            name, content = await coro
+            yield f"[{name}] {content}"

pyagent_patterns/orchestration/hierarchical.py

@@ -0,0 +1,110 @@
+"""Hierarchical Coordination pattern: Manager → Teams → Workers.
+
+A tiered approach where a manager delegates to team leads,
+who further delegate to individual workers. Results flow back
+up through the hierarchy.
+
+LLM calls: 1 manager + T team leads + W workers
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from pyagent_patterns.base import Agent, Context, Message, Pattern, Result
+
+
+@dataclass
+class Team:
+    """A team with a lead agent and worker agents.
+
+    Args:
+        name: Team name (e.g., "Research", "Risk").
+        lead: The team lead agent who coordinates workers.
+        workers: Individual worker agents on this team.
+    """
+
+    name: str
+    lead: Agent
+    workers: list[Agent]
+
+
+class Hierarchical(Pattern):
+    """Manager → Team Leads → Workers hierarchical coordination.
+
+    Args:
+        manager: Top-level manager that decomposes work and synthesizes results.
+        teams: List of teams, each with a lead and workers.
+    """
+
+    def __init__(self, manager: Agent, teams: list[Team]) -> None:
+        self._manager = manager
+        self._teams = teams
+
+    @property
+    def pattern_type(self) -> str:
+        return "hierarchical"
+
+    async def _execute(self, ctx: Context) -> Result:
+        messages: list[Message] = []
+
+        # Step 1: Manager decomposes task
+        decompose_prompt = Message.user(
+            f"Decompose this task into subtasks for these teams: "
+            f"{', '.join(t.name for t in self._teams)}.\n"
+            f"For each team, provide a clear subtask description.\n\n"
+            f"Task: {ctx.task}"
+        )
+        manager_plan = await self._manager.run([decompose_prompt])
+        messages.append(manager_plan)
+
+        # Step 2: Teams work in parallel
+        async def _run_team(team: Team, plan: str) -> tuple[str, list[Message]]:
+            team_msgs: list[Message] = []
+
+            # Team lead delegates to workers
+            worker_tasks = [
+                worker.run([Message.user(f"Team {team.name} task: {plan}\nDo your part.")])
+                for worker in team.workers
+            ]
+            worker_results = await asyncio.gather(*worker_tasks)
+            team_msgs.extend(worker_results)
+
+            # Team lead synthesizes worker outputs
+            worker_summary = "\n".join(
+                f"- {team.workers[i].name}: {r.content}" for i, r in enumerate(worker_results)
+            )
+            lead_msg = Message.user(
+                f"Synthesize your team's work:\n{worker_summary}"
+            )
+            lead_result = await team.lead.run([lead_msg])
+            team_msgs.append(lead_result)
+            return lead_result.content, team_msgs
+
+        team_tasks = [_run_team(team, manager_plan.content) for team in self._teams]
+        team_outputs = await asyncio.gather(*team_tasks)
+
+        for _, team_msgs in team_outputs:
+            messages.extend(team_msgs)
+
+        # Step 3: Manager synthesizes all team outputs
+        team_summary = "\n\n".join(
+            f"--- {self._teams[i].name} Team ---\n{output}"
+            for i, (output, _) in enumerate(team_outputs)
+        )
+        synthesis_prompt = Message.user(
+            f"Synthesize these team outputs into a final response:\n\n{team_summary}"
+        )
+        final = await self._manager.run([synthesis_prompt])
+        messages.append(final)
+
+        return Result(
+            output=final.content,
+            messages=messages,
+            metadata={
+                "teams": len(self._teams),
+                "total_workers": sum(len(t.workers) for t in self._teams),
+                "team_names": [t.name for t in self._teams],
+            },
+        )