Metadata-Version: 2.4
Name: swebot-client
Version: 0.9.9
Summary: Python client for the swebot autonomous coding agent
Project-URL: Homepage, https://github.com/tickup-se/swebot
Project-URL: Repository, https://github.com/tickup-se/swebot
Project-URL: Issues, https://github.com/tickup-se/swebot/issues
Author: Tickup SE
License-Expression: MIT
Keywords: ai,automation,coding-agent,llm,swebot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# swebot-client

Python client for the [swebot](https://github.com/tickup-se/swebot) autonomous coding agent.

Pure Python — zero dependencies beyond the standard library.

## Install

```bash
# pip
pip install swebot-client

# uv
uv add swebot-client
```

## Quick start

```python
from swebot_client import SwebotClient

client = SwebotClient("http://localhost:8080")
session = client.create_session()

# Stream tokens
for token in session.stream("explain goroutines"):
    print(token, end="", flush=True)

# Or get the full reply at once
reply = session.send("what is 2+2?")
print(reply)
```

## Features

- **Streaming** — real-time token-by-token output via SSE
- **Tool callbacks** — observe tool invocations and results
- **Session management** — create, resume, list, delete sessions
- **Todos** — read and update agent todo items
- **MCP management** — configure MCP servers programmatically
- **Context control** — compact or clear session context
- **Skills** — list and use built-in skill agents

## Examples

```python
from swebot_client import SwebotClient, Session, ToolCall, TodoItem

client = SwebotClient("http://localhost:8080")

# Wait for backend to be ready
client.wait_until_ready(timeout=10)

# Create a session with a specific agent
session = client.create_session(agent="developer")

# Stream with tool call callbacks
def on_tool(tc: ToolCall):
    print(f"  ⚙ {tc.name}")

reply = session.send_with_events(
    "create a hello.py file",
    on_tool_start=on_tool,
)

# Read todos
for todo in session.get_todos():
    print(f"[{todo.status}] {todo.title}")

# List MCP servers
for mcp in client.list_mcp():
    print(f"{mcp['name']}: {'connected' if mcp.get('connected') else 'disconnected'}")

# Token usage
usage = session.token_usage()
print(f"Tokens: {usage['tokens_in']:,} in / {usage['tokens_out']:,} out ({usage['usage_pct']}%)")
```

## API reference

### `SwebotClient(addr="http://localhost:8080")`

No token needed for local use. If the backend was started with `--token`,
set `SWEBOT_TOKEN` in your environment — the SDK reads it automatically.

| Method | Description |
|--------|-------------|
| `health()` | Check if backend is reachable |
| `wait_until_ready(timeout)` | Block until backend responds |
| `create_session(agent)` | Create a new session → `Session` |
| `get_session(id)` | Resume an existing session → `Session` |
| `list_sessions()` | List all sessions |
| `delete_session(id)` | Delete a session |
| `list_agents()` | List available agents |
| `list_providers()` | List LLM providers |
| `stats()` | Backend stats (model, tokens, uptime) |
| `skills()` | List built-in skill agents |
| `list_mcp()` | List MCP servers |
| `add_mcp(...)` | Add an MCP server |
| `delete_mcp(name)` | Remove an MCP server |
| `shutdown()` | Gracefully stop the backend |

### `Session`

| Method | Description |
|--------|-------------|
| `stream(message)` | Stream tokens → `Iterator[str]` |
| `send(message)` | Send and get full reply → `str` |
| `send_with_events(message, ...)` | Send with tool callbacks → `str` |
| `get_todos()` | List todo items → `list[TodoItem]` |
| `update_todo(id, status)` | Update a todo's status |
| `compact()` | Trigger context compaction |
| `clear()` | Clear all session context |
| `token_usage()` | Get token usage stats |

## Requirements

- Python 3.9+
- A running swebot backend (`swebot --serve`)

## License

MIT
