agent-patterns-py 0.1.0__py3-none-any.whl

agent_patterns/__init__.py

@@ -0,0 +1,98 @@
+"""
+agent-patterns
+==============
+
+Production-ready boilerplate for common agentic AI patterns in Python.
+
+Quick start::
+
+    from agent_patterns import (
+        Agent, Goal, Memory,
+        PythonEnvironment,
+        AgentFunctionCallingActionLanguage,
+        PythonActionRegistry,
+        register_tool,
+        make_generate_response,
+    )
+
+    @register_tool(tags=["my_tools"], terminal=True)
+    def terminate(message: str) -> str:
+        \"\"\"End the session and return a final message.\"\"\"
+        return message
+
+    agent = Agent(
+        goals=[Goal(1, "Task", "Complete the assigned task then terminate.")],
+        agent_language=AgentFunctionCallingActionLanguage(),
+        action_registry=PythonActionRegistry(tags=["my_tools"]),
+        generate_response=make_generate_response("openai/gpt-4o"),
+        environment=PythonEnvironment(),
+    )
+
+    memory = agent.run("Hello!")
+"""
+
+# Core GAME components
+from agent_patterns.core.goal import Goal
+from agent_patterns.core.memory import Memory
+from agent_patterns.core.action import Action, ActionRegistry
+from agent_patterns.core.context import ActionContext
+from agent_patterns.core.environment import Environment, PythonEnvironment
+from agent_patterns.core.agent import Agent
+
+# Language strategies
+from agent_patterns.language.base import AgentLanguage, Prompt
+from agent_patterns.language.function_calling import AgentFunctionCallingActionLanguage
+from agent_patterns.language.json_action import AgentJsonActionLanguage
+
+# Tool system
+from agent_patterns.tools.registry import register_tool, get_tool_metadata, PythonActionRegistry
+
+# Utilities
+from agent_patterns.utils.llm import make_generate_response, generate_response, prompt_llm
+
+# Capabilities
+from agent_patterns.capabilities.base import Capability
+from agent_patterns.capabilities.plan_first import PlanFirstCapability
+from agent_patterns.capabilities.progress_tracking import ProgressTrackingCapability
+
+# Multi-agent
+from agent_patterns.multi_agent.registry import AgentRegistry
+
+# Safety
+from agent_patterns.safety.reversible import ReversibleAction, ActionTransaction
+from agent_patterns.safety.staged import StagedActionEnvironment
+
+__all__ = [
+    # Core
+    "Goal",
+    "Memory",
+    "Action",
+    "ActionRegistry",
+    "ActionContext",
+    "Environment",
+    "PythonEnvironment",
+    "Agent",
+    # Language
+    "AgentLanguage",
+    "Prompt",
+    "AgentFunctionCallingActionLanguage",
+    "AgentJsonActionLanguage",
+    # Tools
+    "register_tool",
+    "get_tool_metadata",
+    "PythonActionRegistry",
+    # Utils
+    "make_generate_response",
+    "generate_response",
+    "prompt_llm",
+    # Capabilities
+    "Capability",
+    "PlanFirstCapability",
+    "ProgressTrackingCapability",
+    # Multi-agent
+    "AgentRegistry",
+    # Safety
+    "ReversibleAction",
+    "ActionTransaction",
+    "StagedActionEnvironment",
+]

agent_patterns/capabilities/__init__.py

@@ -0,0 +1,9 @@
+from agent_patterns.capabilities.base import Capability
+from agent_patterns.capabilities.plan_first import PlanFirstCapability
+from agent_patterns.capabilities.progress_tracking import ProgressTrackingCapability
+
+__all__ = [
+    "Capability",
+    "PlanFirstCapability",
+    "ProgressTrackingCapability",
+]

agent_patterns/capabilities/base.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from abc import ABC
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from agent_patterns.core.action import Action
+    from agent_patterns.core.context import ActionContext
+    from agent_patterns.core.memory import Memory
+    from agent_patterns.language.base import Prompt
+
+
+class Capability(ABC):
+    """
+    Base class for agent loop extensions.
+
+    Capabilities plug into eight lifecycle hooks in the agent loop,
+    allowing rich extensions (time awareness, planning, logging, metrics,
+    etc.) without modifying :class:`~agent_patterns.core.agent.Agent`.
+
+    All methods have no-op defaults — override only what you need.
+
+    Lifecycle (per ``agent.run()`` call)::
+
+        init()
+        ┌─ loop ─────────────────────────────────────────────────────┐
+        │  start_agent_loop()   ← return False to stop               │
+        │  process_prompt()                                           │
+        │  [LLM call]                                                 │
+        │  process_response()                                         │
+        │  process_action()                                           │
+        │  [Environment.execute_action()]                             │
+        │  process_result()                                           │
+        │  process_new_memories()                                     │
+        │  end_agent_loop()                                           │
+        │  should_terminate()   ← return True to stop                │
+        └─────────────────────────────────────────────────────────────┘
+        terminate()
+    """
+
+    def __init__(self, name: str, description: str) -> None:
+        self.name = name
+        self.description = description
+
+    def init(self, agent: Any, action_context: "ActionContext") -> None:
+        """Called once before the loop starts. Set up state here."""
+
+    def start_agent_loop(
+        self, agent: Any, action_context: "ActionContext"
+    ) -> Optional[bool]:
+        """
+        Called at the start of each iteration.
+        Return ``False`` to stop the loop immediately.
+        """
+        return True
+
+    def process_prompt(
+        self, agent: Any, action_context: "ActionContext", prompt: "Prompt"
+    ) -> "Prompt":
+        """Modify the prompt before it is sent to the LLM."""
+        return prompt
+
+    def process_response(
+        self, agent: Any, action_context: "ActionContext", response: str
+    ) -> str:
+        """Modify the raw LLM response before it is parsed."""
+        return response
+
+    def process_action(
+        self, agent: Any, action_context: "ActionContext", action: Dict
+    ) -> Dict:
+        """Modify the parsed action invocation before execution."""
+        return action
+
+    def process_result(
+        self,
+        agent: Any,
+        action_context: "ActionContext",
+        response: str,
+        action_def: "Action",
+        action: Dict,
+        result: Any,
+    ) -> Any:
+        """Modify the action result before it is stored in memory."""
+        return result
+
+    def process_new_memories(
+        self,
+        agent: Any,
+        action_context: "ActionContext",
+        memory: "Memory",
+        response: str,
+        result: Any,
+        memories: List[Dict],
+    ) -> List[Dict]:
+        """Add, remove, or modify memory entries before they are committed."""
+        return memories
+
+    def end_agent_loop(self, agent: Any, action_context: "ActionContext") -> None:
+        """Called at the end of each iteration (after memory update)."""
+
+    def should_terminate(
+        self, agent: Any, action_context: "ActionContext", response: str
+    ) -> bool:
+        """Return ``True`` to stop the loop after the current iteration."""
+        return False
+
+    def terminate(self, agent: Any, action_context: "ActionContext") -> None:
+        """Called once when the agent stops (cleanup, flushing, etc.)."""

agent_patterns/capabilities/plan_first.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from agent_patterns.capabilities.base import Capability
+
+if TYPE_CHECKING:
+    from agent_patterns.core.context import ActionContext
+
+
+class PlanFirstCapability(Capability):
+    """
+    Forces the agent to create a detailed execution plan before acting.
+
+    On the first iteration, invokes
+    :func:`~agent_patterns.tools.planning.create_plan` and stores the
+    result in memory so every subsequent prompt includes the plan.
+
+    This improves reliability for multi-step tasks by anchoring the agent
+    to a structured strategy rather than improvising step-by-step.
+
+    Args:
+        plan_memory_type: Memory type tag for the plan entry.
+                          ``"system"`` keeps it out of the visible
+                          conversation while still influencing the prompt.
+    """
+
+    def __init__(self, plan_memory_type: str = "system") -> None:
+        super().__init__(
+            name="Plan First",
+            description="Generates an execution plan before the agent takes its first action.",
+        )
+        self.plan_memory_type = plan_memory_type
+        self._planned = False
+
+    def init(self, agent: Any, action_context: "ActionContext") -> None:
+        if self._planned:
+            return
+        self._planned = True
+
+        # Import here to avoid circular imports at module load time
+        from agent_patterns.tools.planning import create_plan
+
+        memory = action_context.get_memory()
+        action_registry = action_context.get_action_registry()
+
+        if memory is None or action_registry is None:
+            return
+
+        plan = create_plan(
+            action_context=action_context,
+            _memory=memory,
+            _action_registry=action_registry,
+        )
+
+        memory.add_memory({
+            "type": self.plan_memory_type,
+            "content": (
+                "You must follow these instructions carefully to complete the task:\n\n"
+                + plan
+            ),
+        })

agent_patterns/capabilities/progress_tracking.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from agent_patterns.capabilities.base import Capability
+
+if TYPE_CHECKING:
+    from agent_patterns.core.context import ActionContext
+
+
+class ProgressTrackingCapability(Capability):
+    """
+    Adds a progress report to memory at the end of every N iterations.
+
+    After each tracked iteration, invokes
+    :func:`~agent_patterns.tools.planning.track_progress` and stores the
+    result so the agent can reflect on what it has accomplished and adjust
+    its strategy accordingly.
+
+    This is especially useful for long-running tasks where the agent needs
+    to self-correct rather than continue executing a stale plan.
+
+    Args:
+        memory_type:      Type tag for progress report entries.
+        track_frequency:  Generate a report every N iterations (default 1).
+    """
+
+    def __init__(
+        self,
+        memory_type: str = "system",
+        track_frequency: int = 1,
+    ) -> None:
+        super().__init__(
+            name="Progress Tracking",
+            description="Adds an LLM-generated progress report to memory after each iteration.",
+        )
+        self.memory_type = memory_type
+        self.track_frequency = track_frequency
+        self._iteration = 0
+
+    def end_agent_loop(self, agent: Any, action_context: "ActionContext") -> None:
+        self._iteration += 1
+
+        if self._iteration % self.track_frequency != 0:
+            return
+
+        from agent_patterns.tools.planning import track_progress
+
+        memory = action_context.get_memory()
+        action_registry = action_context.get_action_registry()
+
+        if memory is None or action_registry is None:
+            return
+
+        report = track_progress(
+            action_context=action_context,
+            _memory=memory,
+            _action_registry=action_registry,
+        )
+
+        memory.add_memory({
+            "type": self.memory_type,
+            "content": f"Progress Report (iteration {self._iteration}):\n\n{report}",
+        })

agent_patterns/core/__init__.py

@@ -0,0 +1,17 @@
+from agent_patterns.core.goal import Goal
+from agent_patterns.core.memory import Memory
+from agent_patterns.core.action import Action, ActionRegistry
+from agent_patterns.core.context import ActionContext
+from agent_patterns.core.environment import Environment, PythonEnvironment
+from agent_patterns.core.agent import Agent
+
+__all__ = [
+    "Goal",
+    "Memory",
+    "Action",
+    "ActionRegistry",
+    "ActionContext",
+    "Environment",
+    "PythonEnvironment",
+    "Agent",
+]

agent_patterns/core/action.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+
+class Action:
+    """
+    Represents a tool the agent can invoke.
+
+    ``Action`` is the *interface* — it describes what the tool does and
+    what parameters it accepts.  The ``Environment`` provides the
+    *implementation* that actually runs the underlying function.
+
+    Attributes:
+        name:        Unique identifier matched against the LLM's tool call.
+        function:    The Python callable to execute.
+        description: Human/LLM-readable description (used in the prompt).
+        parameters:  JSON Schema object describing the tool's arguments.
+        terminal:    When ``True``, the agent loop stops after this action.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        function: Callable,
+        description: str,
+        parameters: Dict,
+        terminal: bool = False,
+    ) -> None:
+        self.name = name
+        self.function = function
+        self.description = description
+        self.terminal = terminal
+        self.parameters = parameters
+
+    def execute(self, **kwargs: Any) -> Any:
+        """Call the underlying function with *kwargs*."""
+        return self.function(**kwargs)
+
+
+class ActionRegistry:
+    """
+    Maps action names to :class:`Action` objects.
+
+    Use :class:`~agent_patterns.tools.registry.PythonActionRegistry` for
+    automatic population from the ``@register_tool`` decorator registry.
+    """
+
+    def __init__(self) -> None:
+        self.actions: Dict[str, Action] = {}
+
+    def register(self, action: Action) -> None:
+        """Add *action* to the registry (overwrites if name already exists)."""
+        self.actions[action.name] = action
+
+    def get_action(self, name: str) -> Optional[Action]:
+        """Return the ``Action`` for *name*, or ``None`` if not found."""
+        return self.actions.get(name)
+
+    def get_actions(self) -> List[Action]:
+        """Return all registered actions."""
+        return list(self.actions.values())

agent_patterns/core/agent.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional
+
+from agent_patterns.core.action import ActionRegistry
+from agent_patterns.core.context import ActionContext
+from agent_patterns.core.environment import Environment
+from agent_patterns.core.goal import Goal
+from agent_patterns.core.memory import Memory
+from agent_patterns.language.base import AgentLanguage, Prompt
+
+if TYPE_CHECKING:
+    from agent_patterns.capabilities.base import Capability
+
+logger = logging.getLogger(__name__)
+
+
+class Agent:
+    """
+    Core GAME loop: Goals · Actions · Memory · Environment.
+
+    The loop runs until one of:
+
+    - A ``terminal`` action is selected.
+    - ``max_iterations`` is reached.
+    - ``max_duration_seconds`` elapses.
+    - A :class:`~agent_patterns.capabilities.base.Capability` signals stop.
+
+    **Capabilities** plug into eight lifecycle hooks without modifying this
+    class.  Pass a list of them to ``capabilities``.
+
+    Example::
+
+        agent = Agent(
+            goals=[Goal(1, "task", "Do X")],
+            agent_language=AgentFunctionCallingActionLanguage(),
+            action_registry=PythonActionRegistry(tags=["my_tools"]),
+            generate_response=make_generate_response("openai/gpt-4o"),
+            environment=PythonEnvironment(),
+        )
+        memory = agent.run("Please do X for me.")
+    """
+
+    def __init__(
+        self,
+        goals: List[Goal],
+        agent_language: AgentLanguage,
+        action_registry: ActionRegistry,
+        generate_response: Callable[[Prompt], str],
+        environment: Environment,
+        capabilities: Optional[List["Capability"]] = None,
+        max_iterations: int = 50,
+        max_duration_seconds: int = 180,
+        verbose: bool = True,
+    ) -> None:
+        self.goals = goals
+        self.generate_response = generate_response
+        self.agent_language = agent_language
+        self.actions = action_registry
+        self.environment = environment
+        self.capabilities: List["Capability"] = capabilities or []
+        self.max_iterations = max_iterations
+        self.max_duration_seconds = max_duration_seconds
+        self.verbose = verbose
+
+    # ------------------------------------------------------------------
+    # Prompt construction
+    # ------------------------------------------------------------------
+
+    def construct_prompt(
+        self, goals: List[Goal], memory: Memory, actions: ActionRegistry
+    ) -> Prompt:
+        return self.agent_language.construct_prompt(
+            actions=actions.get_actions(),
+            environment=self.environment,
+            goals=goals,
+            memory=memory,
+        )
+
+    # ------------------------------------------------------------------
+    # Response helpers
+    # ------------------------------------------------------------------
+
+    def get_action(self, response: str):
+        """Parse *response* and look up the corresponding Action."""
+        invocation = self.agent_language.parse_response(response)
+        action = self.actions.get_action(invocation["tool"])
+        return action, invocation
+
+    def should_terminate(self, response: str) -> bool:
+        """Return ``True`` if the parsed action is terminal."""
+        try:
+            action_def, _ = self.get_action(response)
+            return action_def is not None and action_def.terminal
+        except Exception:
+            return False
+
+    # ------------------------------------------------------------------
+    # Memory helpers
+    # ------------------------------------------------------------------
+
+    def set_current_task(self, memory: Memory, task: str) -> None:
+        memory.add_memory({"type": "user", "content": task})
+
+    # ------------------------------------------------------------------
+    # LLM call
+    # ------------------------------------------------------------------
+
+    def prompt_llm_for_action(self, prompt: Prompt) -> str:
+        return self.generate_response(prompt)
+
+    # ------------------------------------------------------------------
+    # Main loop
+    # ------------------------------------------------------------------
+
+    def run(
+        self,
+        user_input: str,
+        memory: Optional[Memory] = None,
+        action_context_props: Optional[Dict] = None,
+        max_iterations: Optional[int] = None,
+    ) -> Memory:
+        """
+        Execute the GAME loop and return the final :class:`Memory`.
+
+        Args:
+            user_input:           The task to give the agent.
+            memory:               Existing memory to continue from (e.g. for
+                                  multi-agent hand-offs).  A fresh one is
+                                  created when ``None``.
+            action_context_props: Extra properties injected into
+                                  :class:`ActionContext` and available to
+                                  tools via ``_<key>`` parameters.
+            max_iterations:       Override the instance-level default.
+        """
+        memory = memory or Memory()
+        action_context_props = action_context_props or {}
+        iterations = max_iterations if max_iterations is not None else self.max_iterations
+
+        action_context = ActionContext({
+            "memory": memory,
+            "llm": self.generate_response,
+            "action_registry": self.actions,
+            **action_context_props,
+        })
+
+        # Initialise capabilities (runs once)
+        for cap in self.capabilities:
+            cap.init(self, action_context)
+
+        self.set_current_task(memory, user_input)
+        start_time = time.time()
+
+        for _ in range(iterations):
+            # Hard wall on execution time
+            if time.time() - start_time > self.max_duration_seconds:
+                logger.warning("Agent stopped: max_duration_seconds (%s) reached.", self.max_duration_seconds)
+                break
+
+            # start_agent_loop — any capability can halt by returning False
+            if any(cap.start_agent_loop(self, action_context) is False for cap in self.capabilities):
+                break
+
+            # Build and augment prompt
+            prompt = self.construct_prompt(self.goals, memory, self.actions)
+            for cap in self.capabilities:
+                prompt = cap.process_prompt(self, action_context, prompt)
+
+            if self.verbose:
+                print("Agent thinking…")
+
+            # Call the LLM
+            response = self.prompt_llm_for_action(prompt)
+
+            if self.verbose:
+                print(f"Agent Decision: {response}")
+
+            # Capability post-processing on the raw response
+            for cap in self.capabilities:
+                response = cap.process_response(self, action_context, response)
+
+            # Parse → look up action
+            try:
+                action_def, invocation = self.get_action(response)
+            except Exception as exc:
+                logger.warning("Failed to parse agent response: %s", exc)
+                break
+
+            if action_def is None:
+                logger.warning("Unknown action in response, stopping: %s", response)
+                break
+
+            # Capability hook on the parsed invocation
+            for cap in self.capabilities:
+                invocation = cap.process_action(self, action_context, invocation)
+
+            # Execute in environment
+            result = self.environment.execute_action(
+                self, action_context, action_def, invocation.get("args", {})
+            )
+
+            if self.verbose:
+                print(f"Action Result: {result}")
+
+            # Capability hook on the result
+            for cap in self.capabilities:
+                result = cap.process_result(
+                    self, action_context, response, action_def, invocation, result
+                )
+
+            # Build memory entries and let capabilities modify them
+            new_memories: List[Dict] = [
+                {"type": "assistant", "content": response},
+                {"type": "environment", "content": json.dumps(result)},
+            ]
+            for cap in self.capabilities:
+                new_memories = cap.process_new_memories(
+                    self, action_context, memory, response, result, new_memories
+                )
+            for m in new_memories:
+                memory.add_memory(m)
+
+            # End-of-loop hook
+            for cap in self.capabilities:
+                cap.end_agent_loop(self, action_context)
+
+            # Termination checks
+            if self.should_terminate(response):
+                break
+            if any(cap.should_terminate(self, action_context, response) for cap in self.capabilities):
+                break
+
+        # Shutdown hook
+        for cap in self.capabilities:
+            cap.terminate(self, action_context)
+
+        return memory