Python tools for models
Hand the Sailfork operations to Claude or an OpenAI model as tool definitions, run the tool a model picks, and handle held writes and errors in the loop.
sailfork.tools exports the catalog's operations as tool definitions for the Anthropic and OpenAI APIs, and a function that runs the tool a model picked. The same operations are on the MCP server, for assistants that call Sailfork with no code of yours in between.
What it exports
| Name | What it is |
|---|---|
ANTHROPIC_TOOLS | A list of tool definitions as dicts with name, description and input_schema, for the Anthropic Messages API. |
OPENAI_TOOLS | The same tools as {"type": "function", "function": {"name", "description", "parameters"}}, for the OpenAI API. |
run(name, input, *, client=None) | Runs the tool the model called. |
arun(name, input, *, client=None) | run for asyncio. |
from sailfork.tools import ANTHROPIC_TOOLS, OPENAI_TOOLS
print(len(ANTHROPIC_TOOLS), sorted(tool["name"] for tool in ANTHROPIC_TOOLS)[:5]) Tool names are the MCP server's: pull_merge, caisson_batch, issue_start. The set is the catalog's operations offered as tools, wait included. Every tool but wait names the repository's owner org, as the MCP server does (org, repo and number for pull_get); wait takes the owner as owner inside its target, as the wait request does. Arguments are named as in each tool's input_schema, in snake case, and run maps them to the operation's. Send the whole list, or pick the tools a job needs, which keeps the prompt short and the model on task:
WANTED = {"issue_get", "pull_list", "pull_get", "pull_merge"}
tools = [tool for tool in ANTHROPIC_TOOLS if tool["name"] in WANTED] Running a tool
run uses client when given, else one Sailfork() built from the environment on first use and kept for the process. arun uses client, else opens an AsyncSailfork for the call and closes it after. Pass your own client to choose the token, host and retry settings.
What run returns is JSON-ready, with the server's camel case keys: dicts, lists and scalars that json.dumps accepts. A call that fails raises the usual error, and an unknown tool name raises KeyError. A tool that can be held, pull_merge among them, answers {"status": "done", "value": ...} when it ran and {"status": "held", "held": ..., "url": ..., "message": ...} when a person has to approve it, so the model sees the difference and can tell the user.
Send a SailforkError back to the model as an error result, so it can correct itself, instead of ending the loop.
The wait tool
wait takes target ({"kind": "pull", "owner": ..., ...}, as for sf.wait), until, timeout, waited and baseline. It is the catalog's single window of about 55 seconds, so a long wait is several calls. When it answers pending, the model calls it again with the baseline and waited from that answer. sf.wait in your own code does that loop for you.
An Anthropic loop
A complete loop with the anthropic package. It runs until the model stops asking for tools.
import json
import anthropic
from sailfork import Sailfork, SailforkError
from sailfork.tools import ANTHROPIC_TOOLS, run
WANTED = {"issue_get", "pull_list", "pull_get", "pull_merge"}
tools = [tool for tool in ANTHROPIC_TOOLS if tool["name"] in WANTED]
with Sailfork() as sf:
claude = anthropic.Anthropic()
messages = [
{
"role": "user",
"content": "List the open pull requests in acme/api and merge #128 if its checks pass.",
}
]
while True:
response = claude.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
tools=tools,
messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
break
results = []
for block in response.content:
if block.type != "tool_use":
continue
try:
output = run(block.name, block.input, client=sf)
results.append(
{"type": "tool_result", "tool_use_id": block.id, "content": json.dumps(output)}
)
except SailforkError as err:
results.append(
{"type": "tool_result", "tool_use_id": block.id, "content": str(err), "is_error": True}
)
messages.append({"role": "user", "content": results})
print("".join(block.text for block in response.content if block.type == "text")) An async loop
The same with AsyncAnthropic and arun, sharing one AsyncSailfork.
import asyncio
import json
import anthropic
from sailfork import AsyncSailfork, SailforkError
from sailfork.tools import ANTHROPIC_TOOLS, arun
async def main() -> None:
claude = anthropic.AsyncAnthropic()
messages = [{"role": "user", "content": "Which pull requests in acme/api are open?"}]
async with AsyncSailfork() as sf:
while True:
response = await claude.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
tools=[t for t in ANTHROPIC_TOOLS if t["name"] == "pull_list"],
messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
break
results = []
for block in response.content:
if block.type != "tool_use":
continue
try:
content = json.dumps(await arun(block.name, block.input, client=sf))
results.append({"type": "tool_result", "tool_use_id": block.id, "content": content})
except SailforkError as err:
results.append(
{"type": "tool_result", "tool_use_id": block.id, "content": str(err), "is_error": True}
)
messages.append({"role": "user", "content": results})
print("".join(b.text for b in response.content if b.type == "text"))
asyncio.run(main()) An OpenAI loop
A short one with the openai package:
import json
import os
from openai import OpenAI
from sailfork.tools import OPENAI_TOOLS, run
client = OpenAI()
messages = [{"role": "user", "content": "How many pull requests are open in acme/api?"}]
while True:
reply = client.chat.completions.create(
model=os.environ["OPENAI_MODEL"], tools=OPENAI_TOOLS, messages=messages
).choices[0].message
messages.append(reply)
if not reply.tool_calls:
break
for call in reply.tool_calls:
result = run(call.function.name, json.loads(call.function.arguments))
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
print(reply.content) Next to the TypeScript version of this page: TypeScript tools for models.