Metadata-Version: 2.4
Name: agents-ui-sdk
Version: 0.1.0
Summary: Python SDK for the agents-ui terminal workspace application
License: AGPL-3.0-or-later
Project-URL: Homepage, https://agents-ui.com/
Project-URL: Repository, https://github.com/FusionbaseHQ/agents-ui-python-sdk
Project-URL: Documentation, https://github.com/FusionbaseHQ/agents-ui-python-sdk#readme
Project-URL: Parent Project, https://github.com/FusionbaseHQ/agents-ui
Project-URL: Bug Tracker, https://github.com/FusionbaseHQ/agents-ui-python-sdk/issues
Keywords: terminal,agents,sdk,automation,pty
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-timeout>=2; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# agents-ui Python SDK

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

Python SDK for the [agents-ui](https://agents-ui.com/) terminal workspace application. Provides complete programmatic access to all 68 API methods — sessions, projects, files, SSH, recordings, events, and more.

This is the official Python client for [agents-ui](https://github.com/FusionbaseHQ/agents-ui), a terminal workspace for AI coding agents.

## Installation

```bash
pip install agents-ui
```

From source:

```bash
git clone https://github.com/FusionbaseHQ/agents-ui-python-sdk.git
cd agents-ui-python-sdk
pip install -e ".[dev]"
```

## Quick Start

### Async

```python
import asyncio
from agents_ui import AgentsUIClient

async def main():
    async with AgentsUIClient() as client:
        # List projects
        projects = await client.projects.list()
        print(f"Projects: {[p.title for p in projects]}")

        # Create a session and run a command
        session = await client.sessions.create(projects[0].id, name="sdk-demo")
        await client.sessions.write(session.id, "echo hello world\r")

        # Subscribe to output events
        async with client.subscribe(["sessions.output"], session_id=session.id) as stream:
            async for event in stream:
                print(event.data.get("output", ""))
                break

asyncio.run(main())
```

### Sync

```python
from agents_ui import SyncAgentsUIClient

with SyncAgentsUIClient() as client:
    info = client.app.info()
    print(f"Connected to {info.name} v{info.version}")

    projects = client.projects.list()
    for project in projects:
        print(f"  - {project.title} ({project.id})")
```

## Architecture

The SDK communicates with the [agents-ui](https://agents-ui.com/) desktop application over a Unix domain socket using JSON-RPC 2.0. Connection parameters are automatically discovered from `~/.agents-ui/api.json`.

```
Your Python code
      |
      v
 AgentsUIClient  (this SDK)
      |
      v  JSON-RPC 2.0 over Unix socket
      |
 agents-ui desktop app  (Tauri/Rust)
      |
      v  PTY / SSH / filesystem
      |
 Terminal sessions, files, SSH hosts
```

### Key Features

- **Async-first** with a full synchronous wrapper — use whichever fits your project
- **Auto-discovery** — connection parameters are read from `~/.agents-ui/api.json` automatically
- **Complete coverage** — all 68 API methods across 14 namespaces
- **Typed models** — frozen dataclasses for every domain object with full IDE autocompletion
- **Event streaming** — subscribe to real-time terminal output, session exits, and more
- **Zero dependencies** — stdlib only (asyncio, json, socket)

### Namespaces

The client organizes methods into namespaces matching the API categories:

| Namespace | Methods | Description |
|-----------|---------|-------------|
| `client.sessions` | 16 | Terminal session lifecycle and I/O |
| `client.persistent_sessions` | 3 | Background persistent sessions |
| `client.projects` | 8 | Workspace project management |
| `client.prompts` | 7 | Reusable command prompts |
| `client.environments` | 5 | Environment configurations |
| `client.assets` | 7 | Project asset templates |
| `client.recordings` | 6 | Session recording playback |
| `client.ssh` | 4 | SSH connection management |
| `client.files` | 7 | Local file operations |
| `client.ssh_files` | 8 | Remote SSH file operations |
| `client.split_views` | 4 | Terminal split panes |
| `client.ui` | 5 | UI control and state |
| `client.app` | 4 | App info and event subscriptions |
| `client.api` | 2 | API introspection |

### Connection Override

```python
# Use explicit connection parameters instead of auto-discovery
client = AgentsUIClient(
    socket_path="/path/to/api.sock",
    token="your-auth-token",
)
```

### Error Handling

All API errors map to typed exceptions:

```python
from agents_ui import AgentsUIClient, NotFoundError, RateLimitError

async with AgentsUIClient() as client:
    try:
        session = await client.sessions.get("nonexistent")
    except NotFoundError:
        print("Session not found")
    except RateLimitError:
        print("Too many requests")
```

### Event Subscriptions

```python
async with client.subscribe(["sessions.output", "sessions.exit"]) as stream:
    async for event in stream:
        if event.event == "sessions.output":
            print(f"[{event.session_id}] {event.data['output']}")
        elif event.event == "sessions.exit":
            print(f"Session {event.session_id} exited")
            break
```

### Utilities

Raw PTY output includes ANSI escape sequences. Use `strip_ansi()` for clean text:

```python
from agents_ui import strip_ansi

clean = strip_ansi(raw_terminal_output)
```

## Examples

The [`examples/`](examples/) directory contains runnable scripts covering every major feature:

| Example | Description |
|---------|-------------|
| [`01_quickstart.py`](examples/01_quickstart.py) | Connect, list projects and sessions (async) |
| [`02_quickstart_sync.py`](examples/02_quickstart_sync.py) | Same as above using the synchronous client |
| [`03_run_command.py`](examples/03_run_command.py) | Create a session, run a command, capture output |
| [`04_file_operations.py`](examples/04_file_operations.py) | List, read, write, rename, and delete files |
| [`05_event_stream.py`](examples/05_event_stream.py) | Subscribe to real-time session output events |
| [`06_project_management.py`](examples/06_project_management.py) | Create, update, list, and delete projects |
| [`07_ssh_hosts.py`](examples/07_ssh_hosts.py) | List SSH hosts and connection history |
| [`08_prompts_and_environments.py`](examples/08_prompts_and_environments.py) | Manage reusable prompts and environment configs |
| [`09_recordings.py`](examples/09_recordings.py) | List and load session recordings |
| [`10_api_introspection.py`](examples/10_api_introspection.py) | Discover all available API methods at runtime |
| [`11_ui_and_theme.py`](examples/11_ui_and_theme.py) | Control UI state, themes, and panel visibility |
| [`12_error_handling.py`](examples/12_error_handling.py) | Typed exceptions and error handling patterns |

Run any example (requires a running [agents-ui](https://agents-ui.com/) instance):

```bash
python examples/01_quickstart.py
```

## Development

```bash
git clone https://github.com/FusionbaseHQ/agents-ui-python-sdk.git
cd agents-ui-python-sdk
pip install -e ".[dev]"

# Run tests (no running app needed — uses a mock server)
pytest

# Type checking
mypy src/agents_ui/
```

## Requirements

- Python 3.10+
- A running [agents-ui](https://agents-ui.com/) desktop application
- Zero runtime dependencies (stdlib only)

## Related Projects

- [agents-ui](https://github.com/FusionbaseHQ/agents-ui) — The terminal workspace application (Tauri/Rust + React)
- [agents-ui.com](https://agents-ui.com/) — Project homepage and downloads

## License

This project is licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0).

See the [LICENSE](LICENSE) file for the full license text.
