simple-agent-loop 0.1.0__tar.gz

simple_agent_loop-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv build:*)"
+    ]
+  }
+}

simple_agent_loop-0.1.0/.env.example

@@ -0,0 +1 @@
+ANTHROPIC_API_KEY=

simple_agent_loop-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Secrets
+.env

simple_agent_loop-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

simple_agent_loop-0.1.0/GUIDE.md

@@ -0,0 +1,195 @@
+# How to Implement an Agent Loop
+
+An agent loop lets a language model use tools repeatedly until it finishes a task. The model decides what to do, calls tools, sees results, and keeps going until it has an answer. This guide covers the core concepts and data structures needed to build one from scratch in any language.
+
+## Core Data Structure: The Session
+
+A session is a list of messages. Each message has a role or type and some content:
+
+```
+{ role: "system",    content: "..." }       -- system prompt
+{ role: "user",      content: "..." }       -- user input
+{ role: "assistant", content: "..." }       -- model text output
+{ type: "thinking",  content: "..." }       -- model reasoning (if supported)
+{ type: "tool_call", name: "...", id: "...", input: {...} }
+{ type: "tool_result", id: "...", output: "..." }
+```
+
+This is a generic format. It does not match any specific API directly -- you translate to/from the API format at the boundary. This keeps your session representation clean and portable.
+
+## 1. Initialize a Session
+
+Create a session with a system prompt and the user's message:
+
+```
+function init_session(system_prompt, user_prompt):
+    return {
+        messages: [
+            { role: "system", content: system_prompt },
+            { role: "user",   content: user_prompt },
+        ]
+    }
+```
+
+## 2. Convert to API Format
+
+Most model APIs expect messages grouped by role, with tool calls and tool results packed into specific block structures. Write a conversion function that:
+
+- Skips system messages (pass them separately)
+- Groups consecutive `thinking`, `assistant`, and `tool_call` messages into a single assistant message with multiple content blocks
+- Groups consecutive `tool_result` messages into a single user message with multiple content blocks
+
+```
+function to_api_messages(messages):
+    api_messages = []
+    assistant_blocks = []
+    tool_result_blocks = []
+
+    -- When hitting a boundary (user message, or switching between
+    -- assistant-side and tool-result-side), flush the accumulated
+    -- blocks into a single message.
+
+    for each message:
+        if system: skip
+        if user: flush both buffers, add user message
+        if assistant: flush tool results, add text block to assistant buffer
+        if thinking: flush tool results, add thinking block to assistant buffer
+        if tool_call: flush tool results, add tool_use block to assistant buffer
+        if tool_result: flush assistant buffer, add to tool result buffer
+
+    flush remaining buffers
+    return api_messages
+```
+
+The key insight is that what your session stores as separate messages may need to be combined into a single API message with multiple content blocks.
+
+## 3. Parse the Response
+
+The model returns a response with content blocks. Parse each block back into your generic message format:
+
+```
+function parse_response(api_response):
+    messages = []
+    for each block in api_response.content:
+        if block is thinking: append { type: "thinking", content: block.thinking }
+        if block is text:     append { role: "assistant", content: block.text }
+        if block is tool_use: append { type: "tool_call", name: ..., id: ..., input: ... }
+    return messages
+```
+
+## 4. Execute Tool Calls
+
+Tool handlers are just functions. Map tool names to handler functions, then execute them:
+
+```
+function execute_tool_calls(tool_calls, tool_handlers):
+    results = []
+    for each tool_call:
+        handler = tool_handlers[tool_call.name]
+        try:
+            output = handler(tool_call.input)
+        catch error:
+            output = "Error: " + error.message
+        results.append({ type: "tool_result", id: tool_call.id, output: output })
+    return results
+```
+
+Tool calls within a single response are independent of each other, so you can execute them in parallel (threads, promises, goroutines, etc).
+
+## 5. The Loop
+
+The agent loop ties everything together. Each iteration: call the model, add its messages to the session, check for tool calls, execute them, add results, repeat.
+
+```
+function agent_loop(invoke_model, tools, session, tool_handlers):
+    loop:
+        api_messages = to_api_messages(session.messages)
+        api_response = invoke_model(tools, api_messages)
+
+        new_messages = parse_response(api_response)
+        append new_messages to session
+
+        tool_calls = filter new_messages for type "tool_call"
+        if no tool_calls: break  -- model is done
+
+        results = execute_tool_calls(tool_calls, tool_handlers)
+        append results to session
+
+    return session
+```
+
+That's the entire loop. The model drives the control flow -- it decides when to call tools and when to stop (by responding with just text and no tool calls).
+
+## 6. Defining Tools
+
+Tools are defined as schemas that tell the model what's available. Each tool has a name, description, and input schema:
+
+```
+{
+    name: "read_file",
+    description: "Read the contents of a file at the given path.",
+    input_schema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path to read" }
+        },
+        required: ["path"]
+    }
+}
+```
+
+Pass the tool definitions to the model on each call. The corresponding handler is just a function that takes the input and returns a string:
+
+```
+function read_file(input):
+    return file_system.read(input.path)
+```
+
+## 7. Subagents
+
+An agent can use other agents as tools. A subagent is just a tool handler that runs its own agent loop:
+
+```
+function summarize(input):
+    sub_session = init_session(
+        "You are a summarizer. Output only the summary.",
+        input.text
+    )
+    result = agent_loop(invoke_model, [], sub_session, {})
+    return response(result).content
+```
+
+Register it as a tool handler like any other function. The outer agent calls "summarize" as a tool, the handler spins up an inner agent loop, and returns the result. The outer agent sees a simple string tool result and has no idea a whole agent loop ran inside.
+
+This composes naturally:
+- A coordinator agent can dispatch to multiple specialist subagents
+- Subagents can have their own tools (or no tools at all)
+- Subagents can have different system prompts, models, or iteration limits
+- You can run multiple subagents in parallel when the tool calls are independent
+
+## 8. Context Management
+
+Sessions grow over time. Old thinking blocks and tool call inputs can be large and become less relevant as the conversation progresses. You can compact them:
+
+- Walk the message list backwards, counting assistant responses
+- Once N assistant responses have appeared after a message, truncate its content to a short prefix
+- Only compact thinking and tool_call messages -- keep user messages, assistant text, and tool results intact
+- Mark compacted messages so you don't re-process them
+
+This keeps the session under control during long-running agent loops without losing the structural flow of the conversation.
+
+## Putting It Together
+
+The full implementation is around 200 lines in most languages. The essential pieces:
+
+| Component | Purpose |
+|---|---|
+| Session | Ordered list of generic messages |
+| `to_api_messages` | Translate generic messages to API format |
+| `parse_response` | Translate API response back to generic messages |
+| `execute_tool_calls` | Run tool handlers, collect results |
+| `agent_loop` | The loop: call model, execute tools, repeat |
+
+Everything else -- logging, session forking, compaction, subagents -- is layered on top of these five pieces.
+
+The model is the control flow. Your code just provides the loop scaffold and tool execution. The model decides what to do, when to use tools, and when to stop.

simple_agent_loop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tom MacWright
+
+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.

simple_agent_loop-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: simple-agent-loop
+Version: 0.1.0
+Summary: A minimal agent loop for tool-using language models
+Project-URL: Homepage, https://github.com/tmcw/agent-loop
+Project-URL: Repository, https://github.com/tmcw/agent-loop
+Author: Tom MacWright
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.79.0; extra == 'anthropic'
+Description-Content-Type: text/markdown
+
+# simple_agent_loop
+
+A minimal agent loop for tool-using language models. ~250 lines. Handles
+message format conversion, parallel tool execution, session compaction,
+and subagent composition.
+
+## Install
+
+```
+pip install simple-agent-loop
+```
+
+## Setup
+
+```python
+import anthropic
+import json
+import simple_agent_loop as sal
+
+client = anthropic.Anthropic()  # uses ANTHROPIC_API_KEY env var
+
+def invoke_model(tools, session):
+    kwargs = dict(
+        model="claude-sonnet-4-5",
+        max_tokens=16000,
+        messages=session["messages"],
+    )
+    if "system" in session:
+        kwargs["system"] = session["system"]
+    if tools:
+        kwargs["tools"] = tools
+    return client.messages.create(**kwargs).to_dict()
+```
+
+## Hello World
+
+No tools, single turn -- the model just responds:
+
+```python
+session = init_session(
+    system_prompt="You are a helpful assistant.",
+    user_prompt="Say hello in three languages.",
+)
+result = agent_loop(invoke_model, [], session, max_iterations=1)
+print(response(result)["content"])
+```
+
+## Tool-Using Agent
+
+Define tools as Anthropic tool schemas and provide handler functions. The
+handler receives tool input as keyword arguments and returns a string.
+
+```python
+import requests
+
+tools = [
+    {
+        "name": "get_weather",
+        "description": "Get the current weather for a city.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "city": {"type": "string", "description": "City name"},
+            },
+            "required": ["city"],
+        },
+    }
+]
+
+def get_weather(city):
+    resp = requests.get(f"https://wttr.in/{city}?format=j1")
+    data = resp.json()["current_condition"][0]
+    return json.dumps({
+        "city": city,
+        "temp_c": data["temp_C"],
+        "description": data["weatherDesc"][0]["value"],
+    })
+
+session = init_session(
+    system_prompt="You answer weather questions. Use the get_weather tool.",
+    user_prompt="What's the weather in Tokyo and Paris?",
+)
+result = agent_loop(
+    invoke_model, tools, session,
+    tool_handlers={"get_weather": get_weather},
+)
+print(response(result)["content"])
+```
+
+The model will call get_weather twice (in parallel), see the results, and
+respond with a summary. The loop runs until the model responds without
+making any tool calls.
+
+## Subagents
+
+A subagent is a tool handler that runs its own agent loop. The outer agent
+calls it like any tool and gets back a string result.
+
+### Example: Text Compressor (compressor.py)
+
+A coordinator agent iteratively compresses text using two subagents:
+a shortener and a quality judge.
+
+```python
+# Subagent: compresses text
+def shorten(text):
+    session = init_session(
+        system_prompt="Rewrite the text to half its length. Output ONLY the result.",
+        user_prompt=text,
+    )
+    result = agent_loop(invoke_model, [], session, name="shortener", max_iterations=1)
+    shortened = response(result)["content"]
+    ratio = len(shortened) / len(text)
+    return json.dumps({"compression_ratio": round(ratio, 3), "shortened_text": shortened})
+
+# Subagent: judges compression quality
+def judge(original, shortened):
+    session = init_session(
+        system_prompt=(
+            "Compare original and shortened text. Return ONLY JSON: "
+            '{"verdict": "acceptable", "reason": "..."} or '
+            '{"verdict": "too_lossy", "reason": "..."}'
+        ),
+        user_prompt=f"ORIGINAL:\n{original}\n\nSHORTENED:\n{shortened}",
+    )
+    result = agent_loop(invoke_model, [], session, name="judge", max_iterations=1)
+    return response(result)["content"]
+```
+
+The coordinator has tools for `shorten` and `judge`, and its system prompt
+tells it to loop: shorten, judge, stop if too_lossy or diminishing returns,
+otherwise shorten again. Each subagent is a one-shot agent loop
+(max_iterations=1) with no tools of its own.
+
+### Example: Transform Rule Derivation (derive_transform.py)
+
+A more complex example with four subagents and a coordinator. Given a
+source text and target text, it derives general transformation rules and
+specific info that together reproduce the target from the source.
+
+```python
+# Subagent: applies rules + specific info to source text
+def edit(text, rules, specific_info):
+    session = init_session(
+        system_prompt="Apply the rules to the text using the specific info. Output ONLY the result.",
+        user_prompt=f"SOURCE TEXT:\n{text}\n\nRULES:\n{rules}\n\nSPECIFIC INFO:\n{specific_info}",
+    )
+    result = agent_loop(invoke_model, [], session, name="editor", max_iterations=1)
+    return response(result)["content"]
+
+# Subagent: scores how close the output is to the target
+def judge_similarity(editor_output, target):
+    session = init_session(
+        system_prompt='Compare texts. Return JSON: {"score": 0-100, "differences": "..."}',
+        user_prompt=f"EDITOR OUTPUT:\n{editor_output}\n\nTARGET:\n{target}",
+    )
+    result = agent_loop(invoke_model, [], session, name="similarity-judge", max_iterations=1)
+    return response(result)["content"]
+
+# Subagent: checks rules are abstract (no specific content leaked in)
+def judge_generality(rules):
+    ...
+
+# Subagent: checks specific_info is a flat fact list
+def judge_specific_info(specific_info):
+    ...
+```
+
+The coordinator calls `edit`, then calls all three judges in parallel,
+refines based on scores, and repeats until all judges score above 90.
+Tool calls within a single model response execute in parallel automatically.
+
+## API Reference
+
+### Session Management
+
+- `init_session(system_prompt, user_prompt)` - Create a new session
+- `extend_session(session, message)` - Append a message to the session
+- `send(session, user_message)` - Add a user message to the session
+- `fork_session(session)` - Deep copy a session for branching
+- `response(session)` - Get the last assistant message, or None
+
+### Agent Loop
+
+- `agent_loop(invoke_model, tools, session, tool_handlers=None, name=None, max_iterations=None)`
+  - `invoke_model(tools, session)` - Function that calls the model API
+  - `tools` - List of Anthropic tool schemas ([] for no tools)
+  - `session` - Session dict from init_session
+  - `tool_handlers` - Dict mapping tool names to handler functions
+  - `name` - Agent name for log output
+  - `max_iterations` - Max model calls before stopping (None = unlimited)
+  - Returns the session with all messages appended
+
+### Message Format
+
+Messages use a generic format independent of any API:
+
+    {"role": "system", "content": "..."}
+    {"role": "user", "content": "..."}
+    {"role": "assistant", "content": "..."}
+    {"type": "thinking", "content": "..."}
+    {"type": "tool_call", "name": "...", "id": "...", "input": {...}}
+    {"type": "tool_result", "id": "...", "output": "..."}
+
+Conversion to/from Anthropic API format is handled by `to_api_messages()`
+and `parse_response()`.

simple_agent_loop-0.1.0/README.md

@@ -0,0 +1,206 @@
+# simple_agent_loop
+
+A minimal agent loop for tool-using language models. ~250 lines. Handles
+message format conversion, parallel tool execution, session compaction,
+and subagent composition.
+
+## Install
+
+```
+pip install simple-agent-loop
+```
+
+## Setup
+
+```python
+import anthropic
+import json
+import simple_agent_loop as sal
+
+client = anthropic.Anthropic()  # uses ANTHROPIC_API_KEY env var
+
+def invoke_model(tools, session):
+    kwargs = dict(
+        model="claude-sonnet-4-5",
+        max_tokens=16000,
+        messages=session["messages"],
+    )
+    if "system" in session:
+        kwargs["system"] = session["system"]
+    if tools:
+        kwargs["tools"] = tools
+    return client.messages.create(**kwargs).to_dict()
+```
+
+## Hello World
+
+No tools, single turn -- the model just responds:
+
+```python
+session = init_session(
+    system_prompt="You are a helpful assistant.",
+    user_prompt="Say hello in three languages.",
+)
+result = agent_loop(invoke_model, [], session, max_iterations=1)
+print(response(result)["content"])
+```
+
+## Tool-Using Agent
+
+Define tools as Anthropic tool schemas and provide handler functions. The
+handler receives tool input as keyword arguments and returns a string.
+
+```python
+import requests
+
+tools = [
+    {
+        "name": "get_weather",
+        "description": "Get the current weather for a city.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "city": {"type": "string", "description": "City name"},
+            },
+            "required": ["city"],
+        },
+    }
+]
+
+def get_weather(city):
+    resp = requests.get(f"https://wttr.in/{city}?format=j1")
+    data = resp.json()["current_condition"][0]
+    return json.dumps({
+        "city": city,
+        "temp_c": data["temp_C"],
+        "description": data["weatherDesc"][0]["value"],
+    })
+
+session = init_session(
+    system_prompt="You answer weather questions. Use the get_weather tool.",
+    user_prompt="What's the weather in Tokyo and Paris?",
+)
+result = agent_loop(
+    invoke_model, tools, session,
+    tool_handlers={"get_weather": get_weather},
+)
+print(response(result)["content"])
+```
+
+The model will call get_weather twice (in parallel), see the results, and
+respond with a summary. The loop runs until the model responds without
+making any tool calls.
+
+## Subagents
+
+A subagent is a tool handler that runs its own agent loop. The outer agent
+calls it like any tool and gets back a string result.
+
+### Example: Text Compressor (compressor.py)
+
+A coordinator agent iteratively compresses text using two subagents:
+a shortener and a quality judge.
+
+```python
+# Subagent: compresses text
+def shorten(text):
+    session = init_session(
+        system_prompt="Rewrite the text to half its length. Output ONLY the result.",
+        user_prompt=text,
+    )
+    result = agent_loop(invoke_model, [], session, name="shortener", max_iterations=1)
+    shortened = response(result)["content"]
+    ratio = len(shortened) / len(text)
+    return json.dumps({"compression_ratio": round(ratio, 3), "shortened_text": shortened})
+
+# Subagent: judges compression quality
+def judge(original, shortened):
+    session = init_session(
+        system_prompt=(
+            "Compare original and shortened text. Return ONLY JSON: "
+            '{"verdict": "acceptable", "reason": "..."} or '
+            '{"verdict": "too_lossy", "reason": "..."}'
+        ),
+        user_prompt=f"ORIGINAL:\n{original}\n\nSHORTENED:\n{shortened}",
+    )
+    result = agent_loop(invoke_model, [], session, name="judge", max_iterations=1)
+    return response(result)["content"]
+```
+
+The coordinator has tools for `shorten` and `judge`, and its system prompt
+tells it to loop: shorten, judge, stop if too_lossy or diminishing returns,
+otherwise shorten again. Each subagent is a one-shot agent loop
+(max_iterations=1) with no tools of its own.
+
+### Example: Transform Rule Derivation (derive_transform.py)
+
+A more complex example with four subagents and a coordinator. Given a
+source text and target text, it derives general transformation rules and
+specific info that together reproduce the target from the source.
+
+```python
+# Subagent: applies rules + specific info to source text
+def edit(text, rules, specific_info):
+    session = init_session(
+        system_prompt="Apply the rules to the text using the specific info. Output ONLY the result.",
+        user_prompt=f"SOURCE TEXT:\n{text}\n\nRULES:\n{rules}\n\nSPECIFIC INFO:\n{specific_info}",
+    )
+    result = agent_loop(invoke_model, [], session, name="editor", max_iterations=1)
+    return response(result)["content"]
+
+# Subagent: scores how close the output is to the target
+def judge_similarity(editor_output, target):
+    session = init_session(
+        system_prompt='Compare texts. Return JSON: {"score": 0-100, "differences": "..."}',
+        user_prompt=f"EDITOR OUTPUT:\n{editor_output}\n\nTARGET:\n{target}",
+    )
+    result = agent_loop(invoke_model, [], session, name="similarity-judge", max_iterations=1)
+    return response(result)["content"]
+
+# Subagent: checks rules are abstract (no specific content leaked in)
+def judge_generality(rules):
+    ...
+
+# Subagent: checks specific_info is a flat fact list
+def judge_specific_info(specific_info):
+    ...
+```
+
+The coordinator calls `edit`, then calls all three judges in parallel,
+refines based on scores, and repeats until all judges score above 90.
+Tool calls within a single model response execute in parallel automatically.
+
+## API Reference
+
+### Session Management
+
+- `init_session(system_prompt, user_prompt)` - Create a new session
+- `extend_session(session, message)` - Append a message to the session
+- `send(session, user_message)` - Add a user message to the session
+- `fork_session(session)` - Deep copy a session for branching
+- `response(session)` - Get the last assistant message, or None
+
+### Agent Loop
+
+- `agent_loop(invoke_model, tools, session, tool_handlers=None, name=None, max_iterations=None)`
+  - `invoke_model(tools, session)` - Function that calls the model API
+  - `tools` - List of Anthropic tool schemas ([] for no tools)
+  - `session` - Session dict from init_session
+  - `tool_handlers` - Dict mapping tool names to handler functions
+  - `name` - Agent name for log output
+  - `max_iterations` - Max model calls before stopping (None = unlimited)
+  - Returns the session with all messages appended
+
+### Message Format
+
+Messages use a generic format independent of any API:
+
+    {"role": "system", "content": "..."}
+    {"role": "user", "content": "..."}
+    {"role": "assistant", "content": "..."}
+    {"type": "thinking", "content": "..."}
+    {"type": "tool_call", "name": "...", "id": "...", "input": {...}}
+    {"type": "tool_result", "id": "...", "output": "..."}
+
+Conversion to/from Anthropic API format is handled by `to_api_messages()`
+and `parse_response()`.