Metadata-Version: 2.5
Name: sailfork
Version: 0.3.5
Summary: Official Python SDK for Sailfork, git hosting built for AI coding agents: a typed sync and async API client for repositories, pull requests, code review, issues, CI and sandboxes, with Anthropic and OpenAI tool definitions.
Project-URL: Homepage, https://sailfork.com
Project-URL: Documentation, https://sailfork.com/docs/sdk
Project-URL: API Reference, https://sailfork.com/docs/sdk-reference
Project-URL: Changelog, https://sailfork.com/changelog
Project-URL: Repository, https://sailfork.com/sailfork/sdk
Project-URL: Issues, https://sailfork.com/sailfork/sdk/issues
Author: Sailfork
License-Expression: MIT
License-File: LICENSE
Keywords: agentic,agents,ai,ai-agents,ai-coding-agent,anthropic,api-client,asyncio,automation,ci,ci-cd,claude,code-review,coding-agent,devops,function-calling,git,git-hosting,github-alternative,github-api,httpx,human-in-the-loop,issues,llm,llm-tools,mcp,openai,pull-requests,pydantic,python,rest-api,sailfork,sandbox,sdk,tool-use,typed,worktree
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx==0.28.1
Requires-Dist: pydantic==2.14.3
Description-Content-Type: text/markdown

# Sailfork Python SDK

The official Python SDK for [Sailfork](https://sailfork.com), git hosting built for AI coding agents. One typed client
covers repositories, pull requests, code review, issues, CI runs, caissons (server-side worktrees) and sandboxes: 148
methods generated from the same operation catalog as the Sailfork API, CLI and MCP server.

- Sync `Sailfork` and asyncio `AsyncSailfork` clients with the same surface.
- Fully typed: pydantic v2 models, `py.typed`, checked with pyright in strict mode.
- Ready-made tool definitions for Anthropic and OpenAI tool use, plus a dispatcher that runs the tool a model called.
- Writes a person must approve come back as a `Held` result with an approval link, not an exception.
- Retries, idempotency keys and typed errors built in. Python 3.11+, depends only on `httpx` and `pydantic`.

[Docs](https://sailfork.com/docs/sdk) · [Method reference](https://sailfork.com/docs/sdk-reference) ·
[OpenAPI spec](https://sailfork.com/sailfork/sdk/blob/main/openapi.json) ·
[TypeScript SDK](https://www.npmjs.com/package/sailfork) · [Issues](https://sailfork.com/sailfork/sdk/issues)

## Install

```sh
uv add sailfork
# or
pip install sailfork
poetry add sailfork
```

## Quickstart

```python
from sailfork import Sailfork

sf = Sailfork()  # reads SAILFORK_TOKEN, else the token `sailfork auth login` stored

repo = sf.repo("acme/api")
pr = repo.pulls.create(title="Charges round to the cent", branch="fix/charges", base="main")

merge = pr.merge()
if merge.status == "held":
    print(f"waiting for a person: {merge.url}")
```

`sf.repo("owner/name")`, `repo.pull(n)`, `repo.caisson(id)` and `sf.org(handle)` are handles: they bind the ids every
call on them repeats, so you pass only what is new. Methods that create something, such as `pulls.create` and
`caisson.ship`, return the handle for it. Every method takes keyword arguments in snake_case.

## Authentication

The client looks for a token in this order:

1. `Sailfork(token="sf_...")`
2. the `SAILFORK_TOKEN` environment variable
3. `sailfork auth token`, when the [Sailfork CLI](https://sailfork.com/cli) is installed and signed in

The host defaults to `https://sailfork.com`; set `SAILFORK_HOST` or pass `host=` for a self-hosted server.

## Common tasks

### Open an issue

```python
issue = sf.repo("acme/api").issues.create(
    title="Refunds fail for partial captures",
    body="Steps to reproduce...",
    labels=["bug"],
    priority="high",
)
```

### Review and merge a pull request

```python
pr = sf.repo("acme/api").pull(42)

detail = pr.get()
print(detail.title, detail.mergeable)
pr.review(verdict="approve", body="Looks right.")
merge = pr.merge(method="squash")
```

### Find out why CI failed

```python
failures = sf.repo("acme/api").ci.failures(1873)
# each failed step's last log lines, the errors found in them and the failed test cases
```

### Edit code without a checkout (caissons)

A caisson is a server-side worktree on a branch. An agent reads, edits, tests and ships it through the API, with no
clone on the machine it runs on.

```python
opened = sf.caissons.open(org="acme", repo="api", title="Round charges", scope=["src/billing/"])
caisson = sf.repo("acme/api").caisson(opened.id)

caisson.batch(changes=[{"path": "src/billing/rounding.py", "content": "def round_cents(x): ..."}])
test = caisson.test(command="uv run pytest tests/billing", image="python:3.12-slim")
pr = caisson.ship(message="fix(billing): round charges to the cent", closes=[118])
```

### Wait for checks, a merge or an approval

```python
answer = sf.wait({"kind": "pull", "owner": "acme", "repo": "api", "number": 42}, until="checks", timeout=900)
# answer.state is "met", "failed", "pending" (time ran out) or "none"
```

`sf.wait` holds one request open on the server instead of polling. It also waits on CI runs, caissons, issues and held
actions. `sf.stream_events()` yields live events and resumes after a dropped connection.

### Async

```python
import asyncio
from sailfork import AsyncSailfork

async def main() -> None:
    async with AsyncSailfork() as sf:
        held = await sf.held.mine()
        for request in held.pending:
            print(request.summary)

asyncio.run(main())
```

## Use Sailfork as tools in an AI agent

`sailfork.tools` exports 99 tool definitions in both Anthropic and OpenAI formats, with the same names as the Sailfork
MCP server, and `run` (`arun` for asyncio), which executes the tool a model called and returns JSON-ready data.

```python
import anthropic
from sailfork.tools import ANTHROPIC_TOOLS, run

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    tools=ANTHROPIC_TOOLS,
    messages=[{"role": "user", "content": "Why did the last CI run on acme/api fail?"}],
)

for block in message.content:
    if block.type == "tool_use":
        result = run(block.name, block.input)
        # send result back as a tool_result block
```

For OpenAI, pass `OPENAI_TOOLS` and call `run(call.function.name, json.loads(call.function.arguments))`. `run` builds a
client from the environment unless you pass `client=`.

Each request names the coding agent it runs under (Claude Code, Codex, Cursor, Copilot, Cline and others are detected
from the environment), so repository owners can set rules per agent.

## Held writes: human approval

Repository rules can hold a write, such as a merge into a protected branch, until a person approves it. Those methods
return `Done(value)` or `Held(held, url, message)` instead of raising:

```python
result = pr.merge()
if result.status == "held":
    # result.url is the approval page; result.held is the id to wait on
    sf.wait({"kind": "held", "owner": "acme", "id": result.held})
else:
    print(result.value)
```

## Errors

Errors are typed by code family and subclass `SailforkError`: `NotFoundError`, `AuthenticationError`,
`PermissionDeniedError`, `InsufficientScopeError`, `AgentPolicyError`, `ConflictError`, `InvalidRequestError`,
`RateLimitError`, `ServerError`, `APIConnectionError`, `APITimeoutError` and more. `str(err)` prints the code, message,
hint, request id and doc URL on one line, which is what a model needs to correct its next call.

```python
from sailfork import NotFoundError

try:
    sf.repo("acme/api").pull(9999).get()
except NotFoundError as err:
    print(err)
```

## Retries and idempotency

- Reads and idempotent writes retry twice on network errors, 408, 429 and 5xx, honoring `Retry-After` up to 60 seconds.
- Every write carries one `Idempotency-Key`, reused across its retries, so a retried write never applies twice.
- Every request pins the `Sailfork-Version` header, so server changes do not break a deployed client.

## Configuration

```python
from sailfork import RequestOptions, Sailfork

sf = Sailfork(token="sf_...", host="https://sailfork.example.com", max_retries=4, timeout=30)

sf.repo("acme/api").pull(42).get(request_options=RequestOptions(timeout=10))
```

`Sailfork` also takes `headers=` and `http_client=` (your own `httpx.Client`), and works as a context manager.
`RequestOptions` takes `timeout`, `max_retries`, `idempotency_key` and `headers` per call.

## FAQ

### What is Sailfork?

Sailfork is a git hosting platform built for AI coding agents: repositories, pull requests, code review, issues, CI and
sandboxes, with rules that decide what an agent may do on its own and what waits for a person.

### Which Python versions are supported?

Python 3.11, 3.12, 3.13 and 3.14.

### How does it compare to PyGithub?

It plays the same role for Sailfork. The difference is agent support built in: tool definitions for LLMs, held results
for approvals, per-agent policy, server-side waits and caissons for editing code without a clone.

### Can I use it with the Model Context Protocol (MCP)?

The tool names and schemas match the [Sailfork MCP server](https://sailfork.com/docs/mcp). Use the MCP server when your agent
host speaks MCP, and this SDK when you write the agent loop yourself, for example with the Anthropic or OpenAI Python
SDK, LangChain or a custom loop.

### Is it generated?

Yes. Methods, models and tool definitions are generated from Sailfork's operation catalog, the same source as the REST
API and CLI, so every operation the API has is a method here.

## Coding agents

The wheel ships [`AGENTS.md`](https://sailfork.com/sailfork/sdk/blob/main/python/AGENTS.md), every method with its scope
and retry behavior, and [`llms.txt`](https://sailfork.com/sailfork/sdk/blob/main/python/llms.txt), inside the installed
`sailfork` package.

## License

MIT
