agent-patterns-py 0.1.0__tar.gz

agent_patterns_py-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# Copy this file to .env and fill in your API keys
+# Never commit .env to version control
+
+# LLM providers
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=

agent_patterns_py-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb_checkpoints
+
+# OS
+.DS_Store
+Thumbs.db

agent_patterns_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_patterns_py-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: agent-patterns-py
+Version: 0.1.0
+Summary: Production-ready boilerplate for common agentic AI patterns in Python
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: litellm>=1.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: ipykernel>=6.0; 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.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-patterns
+
+A Python framework for building production-ready AI agents using the GAME pattern (Goals, Actions, Memory, Environment).
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/your-username/agent-patterns.git
+cd agent-patterns
+uv sync
+cp .env.example .env  # add your API keys
+```
+
+---
+
+## Quick start
+
+```python
+import os
+from agent_patterns import (
+    Agent, Goal,
+    PythonEnvironment,
+    AgentFunctionCallingActionLanguage,
+    PythonActionRegistry,
+    register_tool,
+    make_generate_response,
+)
+
+@register_tool(tags=["files"])
+def list_files() -> list:
+    """List files in the current directory."""
+    return os.listdir(".")
+
+@register_tool(tags=["files"])
+def read_file(name: str) -> str:
+    """Read a file and return its contents."""
+    with open(name) as f:
+        return f.read()
+
+@register_tool(tags=["system"], terminal=True)
+def terminate(message: str) -> str:
+    """End the session with a final message."""
+    return message
+
+agent = Agent(
+    goals=[
+        Goal(1, "Explore", "List and read files in the current directory."),
+        Goal(2, "Terminate", "Call terminate with a summary when done."),
+    ],
+    agent_language=AgentFunctionCallingActionLanguage(),
+    action_registry=PythonActionRegistry(tags=["files", "system"]),
+    generate_response=make_generate_response("openai/gpt-4o"),
+    environment=PythonEnvironment(),
+)
+
+memory = agent.run("What Python files are here and what do they do?")
+```
+
+---
+
+## Docs
+
+- [Switching models](docs/models.md)
+- [Agent language strategies](docs/agent-language.md)
+- [Capabilities](docs/capabilities.md)
+- [Dependency injection](docs/dependency-injection.md)
+- [Multi-agent](docs/multi-agent.md)
+- [Safety patterns](docs/safety.md)
+
+---
+
+## License
+
+MIT

agent_patterns_py-0.1.0/README.md

@@ -0,0 +1,76 @@
+# agent-patterns
+
+A Python framework for building production-ready AI agents using the GAME pattern (Goals, Actions, Memory, Environment).
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/your-username/agent-patterns.git
+cd agent-patterns
+uv sync
+cp .env.example .env  # add your API keys
+```
+
+---
+
+## Quick start
+
+```python
+import os
+from agent_patterns import (
+    Agent, Goal,
+    PythonEnvironment,
+    AgentFunctionCallingActionLanguage,
+    PythonActionRegistry,
+    register_tool,
+    make_generate_response,
+)
+
+@register_tool(tags=["files"])
+def list_files() -> list:
+    """List files in the current directory."""
+    return os.listdir(".")
+
+@register_tool(tags=["files"])
+def read_file(name: str) -> str:
+    """Read a file and return its contents."""
+    with open(name) as f:
+        return f.read()
+
+@register_tool(tags=["system"], terminal=True)
+def terminate(message: str) -> str:
+    """End the session with a final message."""
+    return message
+
+agent = Agent(
+    goals=[
+        Goal(1, "Explore", "List and read files in the current directory."),
+        Goal(2, "Terminate", "Call terminate with a summary when done."),
+    ],
+    agent_language=AgentFunctionCallingActionLanguage(),
+    action_registry=PythonActionRegistry(tags=["files", "system"]),
+    generate_response=make_generate_response("openai/gpt-4o"),
+    environment=PythonEnvironment(),
+)
+
+memory = agent.run("What Python files are here and what do they do?")
+```
+
+---
+
+## Docs
+
+- [Switching models](docs/models.md)
+- [Agent language strategies](docs/agent-language.md)
+- [Capabilities](docs/capabilities.md)
+- [Dependency injection](docs/dependency-injection.md)
+- [Multi-agent](docs/multi-agent.md)
+- [Safety patterns](docs/safety.md)
+
+---
+
+## License
+
+MIT

agent_patterns_py-0.1.0/docs/agent-language.md

@@ -0,0 +1,74 @@
+# Agent language strategies
+
+`AgentLanguage` controls two things:
+
+1. **How GAME components are formatted into a prompt** sent to the LLM
+2. **How the LLM's response is parsed** back into an action
+
+Swapping the language changes the prompting strategy without touching the agent loop.
+
+---
+
+## Function calling (recommended)
+
+Uses the LLM's native tool/function calling API. The LLM returns a structured tool call — no text parsing needed.
+
+```python
+from agent_patterns import AgentFunctionCallingActionLanguage
+
+agent = Agent(
+    ...
+    agent_language=AgentFunctionCallingActionLanguage(),
+)
+```
+
+**When to use:** Almost always. More reliable, no prompt engineering needed to get structured output.
+
+---
+
+## JSON action blocks
+
+The LLM outputs free-form reasoning text and embeds its action in a fenced ` ```action ``` ` block:
+
+```
+I'll start by listing the files.
+
+```action
+{
+    "tool": "list_files",
+    "args": {}
+}
+```
+
+```python
+from agent_patterns import AgentJsonActionLanguage
+
+agent = Agent(
+    ...
+    agent_language=AgentJsonActionLanguage(),
+)
+```
+
+**When to use:**
+- The model doesn't support native function calling
+- You want the agent's reasoning visible in memory
+- You need a model-agnostic fallback
+
+---
+
+## Custom language
+
+Subclass `AgentLanguage` and implement two methods:
+
+```python
+from agent_patterns import AgentLanguage, Prompt
+
+class MyLanguage(AgentLanguage):
+    def construct_prompt(self, actions, environment, goals, memory) -> Prompt:
+        # build and return a Prompt however you like
+        ...
+
+    def parse_response(self, response: str) -> dict:
+        # return {"tool": "...", "args": {...}}
+        ...
+```

agent_patterns_py-0.1.0/docs/capabilities.md

@@ -0,0 +1,79 @@
+# Capabilities
+
+Capabilities extend the agent loop at specific lifecycle points without modifying the `Agent` class. Pass a list of them when creating an agent:
+
+```python
+from agent_patterns import Agent, PlanFirstCapability, ProgressTrackingCapability
+
+agent = Agent(
+    ...
+    capabilities=[
+        PlanFirstCapability(),
+        ProgressTrackingCapability(track_frequency=3),
+    ],
+)
+```
+
+---
+
+## Built-in capabilities
+
+### PlanFirstCapability
+
+Before the agent takes its first action, generates a detailed step-by-step execution plan and stores it in memory. Every subsequent prompt includes the plan, keeping the agent on track for multi-step tasks.
+
+```python
+from agent_patterns import PlanFirstCapability
+
+PlanFirstCapability(
+    plan_memory_type="system",  # memory type for the plan entry (default: "system")
+)
+```
+
+---
+
+### ProgressTrackingCapability
+
+At the end of every N iterations, generates a progress report (what's done, any blockers, recommended next steps) and adds it to memory. Useful for long-running tasks where the agent needs to self-correct.
+
+```python
+from agent_patterns import ProgressTrackingCapability
+
+ProgressTrackingCapability(
+    memory_type="system",    # memory type for report entries (default: "system")
+    track_frequency=1,       # generate a report every N iterations (default: 1)
+)
+```
+
+---
+
+## Writing your own
+
+Subclass `Capability` and override only the hooks you need:
+
+```python
+from agent_patterns import Capability
+
+class LoggingCapability(Capability):
+    def __init__(self):
+        super().__init__(name="Logging", description="Logs every action taken.")
+
+    def process_action(self, agent, action_context, action):
+        print(f"[LOG] action={action['tool']} args={action.get('args')}")
+        return action  # always return the (optionally modified) value
+```
+
+### Available hooks
+
+| Method | Called when | Return |
+|--------|------------|--------|
+| `init` | Once, before the loop starts | — |
+| `start_agent_loop` | Start of each iteration | `False` to stop the loop |
+| `process_prompt` | Before the prompt is sent to the LLM | modified `Prompt` |
+| `process_response` | After the LLM responds, before parsing | modified response `str` |
+| `process_action` | After parsing, before execution | modified action `dict` |
+| `process_result` | After execution | modified result |
+| `process_new_memories` | Before memory entries are committed | modified `list[dict]` |
+| `end_agent_loop` | End of each iteration | — |
+| `should_terminate` | After memory update | `True` to stop the loop |
+| `terminate` | Once, when the agent stops | — |

agent_patterns_py-0.1.0/docs/dependency-injection.md

@@ -0,0 +1,86 @@
+# Dependency injection
+
+Tools often need access to things beyond their explicit arguments — a database connection, an auth token, the agent's memory. Rather than hardcoding these or passing them through the LLM, the framework injects them automatically based on parameter naming conventions.
+
+---
+
+## How it works
+
+When `PythonEnvironment` executes a tool, it inspects the function's parameters and injects matching values before calling it. Three conventions are supported:
+
+| Parameter name | What gets injected |
+|---------------|-------------------|
+| `action_context` | The live `ActionContext` for this run |
+| `action_agent` | The `Agent` instance |
+| `_<key>` | `action_context.properties[key]` |
+
+These parameters are **hidden from the LLM** — they never appear in the tool's JSON schema.
+
+---
+
+## action_context
+
+Use this when you need direct access to the context object:
+
+```python
+from agent_patterns import register_tool, ActionContext
+
+@register_tool(tags=["llm"])
+def summarise(action_context: ActionContext, text: str) -> str:
+    """Summarise the given text."""
+    generate = action_context.get("llm")
+    return generate(Prompt(messages=[
+        {"role": "user", "content": f"Summarise: {text}"}
+    ]))
+```
+
+---
+
+## _prefixed parameters
+
+For injecting specific values from the context, prefix the parameter name with `_`:
+
+```python
+@register_tool(tags=["db"])
+def query(action_context: ActionContext, sql: str, _db_conn) -> list:
+    """Run a SQL query."""
+    return _db_conn.execute(sql).fetchall()
+```
+
+Then pass `db_conn` (without the underscore) when running the agent:
+
+```python
+agent.run(
+    "Find all users created this month.",
+    action_context_props={"db_conn": my_db_connection},
+)
+```
+
+`_db_conn` maps to `action_context.properties["db_conn"]` automatically.
+
+---
+
+## Common injected values
+
+```python
+agent.run(
+    "Process the request.",
+    action_context_props={
+        "auth_token": "Bearer abc123",   # → _auth_token
+        "db_conn": db,                   # → _db_conn
+        "user_config": config,           # → _user_config
+        "agent_registry": registry,      # → used by call_agent
+    },
+)
+```
+
+---
+
+## Using base Environment
+
+If you use the base `Environment` instead of `PythonEnvironment`, no injection happens — tools receive only the arguments the LLM explicitly provided.
+
+```python
+from agent_patterns import Environment  # no DI
+from agent_patterns import PythonEnvironment  # with DI
+```

agent_patterns_py-0.1.0/docs/models.md

@@ -0,0 +1,57 @@
+# Switching models
+
+The framework uses [LiteLLM](https://docs.litellm.ai) under the hood, so any model LiteLLM supports works out of the box.
+
+Use `make_generate_response` to create a callable bound to a specific model and pass it to your agent:
+
+```python
+from agent_patterns import make_generate_response, Agent
+
+agent = Agent(
+    ...
+    generate_response=make_generate_response("openai/gpt-4o"),
+)
+```
+
+## Examples
+
+```python
+# OpenAI
+make_generate_response("openai/gpt-4o")
+make_generate_response("openai/gpt-4o-mini")
+
+# Anthropic
+make_generate_response("anthropic/claude-opus-4-5")
+make_generate_response("anthropic/claude-sonnet-4-5")
+
+# Any other LiteLLM-supported provider
+make_generate_response("groq/llama-3.1-70b-versatile")
+```
+
+## Different models per agent
+
+Each agent gets its own `generate_response` callable, so you can mix models freely:
+
+```python
+fast_agent = Agent(
+    ...
+    generate_response=make_generate_response("openai/gpt-4o-mini"),
+)
+
+smart_agent = Agent(
+    ...
+    generate_response=make_generate_response("anthropic/claude-opus-4-5"),
+)
+```
+
+## Using a custom LLM function
+
+`generate_response` is just a callable with the signature `(Prompt) -> str`. You can pass anything that matches:
+
+```python
+def my_llm(prompt: Prompt) -> str:
+    # call any API you want
+    ...
+
+agent = Agent(..., generate_response=my_llm)
+```

agent_patterns_py-0.1.0/docs/multi-agent.md

@@ -0,0 +1,77 @@
+# Multi-agent
+
+One agent can delegate tasks to other agents using the built-in `call_agent` tool and `AgentRegistry`.
+
+---
+
+## Setup
+
+### 1. Create your agents
+
+```python
+from agent_patterns import Agent, Goal, PythonEnvironment, AgentFunctionCallingActionLanguage, PythonActionRegistry, make_generate_response
+
+summariser = Agent(
+    goals=[Goal(1, "Summarise", "Summarise the provided text concisely then terminate.")],
+    agent_language=AgentFunctionCallingActionLanguage(),
+    action_registry=PythonActionRegistry(tags=["summariser", "system"]),
+    generate_response=make_generate_response("openai/gpt-4o-mini"),
+    environment=PythonEnvironment(),
+)
+```
+
+### 2. Register them
+
+```python
+from agent_patterns import AgentRegistry
+
+registry = AgentRegistry()
+registry.register_agent("summariser", summariser.run)
+```
+
+### 3. Give the coordinator the call_agent tool
+
+```python
+# Import to register it in the global tool registry
+import agent_patterns.tools.agent_tools  # noqa: F401
+
+coordinator = Agent(
+    goals=[Goal(1, "Coordinate", "Delegate tasks to specialist agents as needed.")],
+    agent_language=AgentFunctionCallingActionLanguage(),
+    action_registry=PythonActionRegistry(tags=["coordinator", "system"]),
+    generate_response=make_generate_response("openai/gpt-4o"),
+    environment=PythonEnvironment(),
+)
+```
+
+### 4. Pass the registry at runtime
+
+```python
+memory = coordinator.run(
+    "Summarise this report: ...",
+    action_context_props={"agent_registry": registry},
+)
+```
+
+---
+
+## How call_agent works
+
+When the coordinator calls `call_agent`:
+
+- A **fresh memory** is created for the sub-agent (no memory leakage between agents)
+- Context properties are forwarded, except `agent_registry` and `memory` (prevents infinite recursion)
+- The sub-agent's final memory item is returned as the result
+
+---
+
+## Memory sharing patterns
+
+Beyond basic message passing, you can control how much context a sub-agent receives by what you pass in `action_context_props`. Four patterns, in order of context shared:
+
+| Pattern | How |
+|---------|-----|
+| Message passing | Default — fresh memory, task only |
+| Memory handoff | Pass `memory=existing_memory` to `agent.run()` |
+| Memory reflection | Copy sub-agent memories back to caller after the call |
+| Selective sharing | Filter memories before passing them to the sub-agent |

agent_patterns_py-0.1.0/docs/safety.md

@@ -0,0 +1,85 @@
+# Safety patterns
+
+Three patterns for agents that take real-world actions (calendar events, emails, API calls, etc.).
+
+---
+
+## Reversible actions
+
+Wrap any action so it can be undone:
+
+```python
+from agent_patterns import ReversibleAction
+
+create_event = ReversibleAction(
+    execute_func=calendar.create_event,
+    reverse_func=lambda **record: calendar.delete_event(record["result"]["event_id"]),
+)
+
+# Execute
+result = create_event.run(title="Sync", attendees=["alice@example.com"])
+
+# Undo if needed
+create_event.undo()
+```
+
+The `reverse_func` receives the full execution record as kwargs:
+
+```python
+{
+    "args": {...},        # original arguments
+    "result": {...},      # return value from execute_func
+    "timestamp": "...",   # ISO timestamp
+}
+```
+
+---
+
+## Action transactions
+
+Group multiple reversible actions into an atomic unit — all succeed or all roll back:
+
+```python
+from agent_patterns import ActionTransaction, ReversibleAction
+
+tx = ActionTransaction()
+tx.add(create_event, title="Sync", attendees=["alice@example.com"])
+tx.add(send_invite, event_id="abc123")
+
+try:
+    tx.execute()   # runs both; rolls back automatically on failure
+    tx.commit()    # marks as final
+except Exception as e:
+    print(f"Transaction failed and was rolled back: {e}")
+```
+
+---
+
+## Staged execution
+
+Collect actions for review before executing them. Useful when a human or a more capable model should sign off before side-effects occur:
+
+```python
+from agent_patterns import StagedActionEnvironment, ReversibleAction
+
+env = StagedActionEnvironment()
+
+# Register a reviewer — returns True to approve, False to reject
+def my_reviewer(task_id, transaction):
+    print(f"Approving {len(transaction._pending)} actions for task {task_id}")
+    return True  # or False to reject
+
+env.set_reviewer(my_reviewer)
+
+# Stage actions
+tx = env.stage_actions(task_id="meeting-setup")
+tx.add(create_event, title="Team sync")
+tx.add(send_invite, attendees=["team@example.com"])
+
+# Review, then execute
+if env.review_transaction("meeting-setup"):
+    tx.execute()
+    tx.commit()
+```
+
+The reviewer can be a human approval step, an LLM policy check, or any callable that returns a bool.