# 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](https://sailfork.com/docs/mcp), 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. |

```python
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:

```python
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](https://sailfork.com/docs/sdk-python-errors), 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`](https://sailfork.com/docs/sdk-python-held-and-waits#wait-for-a-change)), `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.

```python
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`.

```python
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:

```python
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](https://sailfork.com/docs/sdk-typescript-tools).

---

Every docs page: https://sailfork.com/llms.txt
