Metadata-Version: 2.4
Name: trelent-agents
Version: 0.2.1
Summary: Python SDK for the Agent Orchestration API.
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.31
Description-Content-Type: text/markdown

# trelent-agents

Python SDK for the Trelent Agent Orchestration API.

## Installation

```bash
pip install trelent-agents
```

## Quick Start

### Without authentication

```python
from trelent_agents import Client

client = Client(api_url="http://localhost:8000")

images = client.images.list()
print(images)

run = client.runs.create(
    sandbox="example-agent:latest",
    prompt="Create hello.txt with a greeting",
)
print(run.run_id, run.status)
```

### With authentication

When the API has authentication enabled, provide your OAuth2 client credentials:

```python
from trelent_agents import Client

client = Client(
    api_url="https://agents.trelent.com",
    client_id="your-client-id",
    client_secret="your-client-secret",
)

images = client.images.list()
run = client.runs.create(
    sandbox="my-image:latest",
    prompt="Do something useful",
)
```

The SDK handles token acquisition automatically — it exchanges your client credentials for a JWT via the API's `/token` endpoint before making authenticated requests.

The client also supports context manager usage:

```python
with Client(api_url="https://agents.trelent.com", client_id="...", client_secret="...") as client:
    runs = client.runs.list()
```

## Client Options

```python
client = Client(
    api_url="https://agents.trelent.com",  # API base URL (default: https://agents.trelent.com)
    client_id="...",                        # OAuth2 client ID (optional)
    client_secret="...",                    # OAuth2 client secret (optional)
    scope="...",                            # Override default OAuth2 scope (optional)
)
```

Both `client_id` and `client_secret` must be provided together, or both omitted.

## Resources

### `client.images`

```python
images = client.images.list()
# => list[RegistryImage] — [RegistryImage(name="my-image", tags=["latest", "v1"])]
```

When auth is enabled, images are automatically filtered to your namespace. Image names are returned without the namespace prefix.

### `client.sandboxes`

```python
sandboxes = client.sandboxes.list()
# => list[str] — registered sandbox image names

client.sandboxes.register("my-image:latest")
```

### `client.runs`

```python
from trelent_agents import LocalImporter, S3Exporter

# Create a run
run = client.runs.create(
    sandbox="my-image:latest",
    prompt="Build a web server",
    model="gpt-5.4",              # optional, default: "gpt-5.4"
    timeout_seconds=3600,          # optional, default: 3600
    imports=[LocalImporter(path="./data")],  # optional
    exports=[S3Exporter()],                  # optional
)

# List runs (optionally filter by sandbox)
runs = client.runs.list()
filtered = client.runs.list(sandbox="my-image:latest")

# Get a specific run
run = client.runs.get("run-id")

# Check status
status = client.runs.get_status("run-id")

# Get checkpoints
chain = client.runs.get_checkpoint_chain("run-id")
checkpoint = client.runs.get_checkpoint("run-id", "checkpoint-id")
```

### Run operations

```python
# Fork (resume from checkpoint)
forked = run.fork(
    "Continue from where you left off",
    model="gpt-5.4",
)

# Refresh run state
run.refresh()
print(run.status)  # updated status
```

### `client.health()`

```python
health = client.health()
# => HealthResponse(status="ok")
```

## Connectors

### Importing local files

```python
from trelent_agents import LocalImporter

run = client.runs.create(
    sandbox="my-image:latest",
    prompt="Process the data",
    imports=[LocalImporter(path="./my-data-dir")],
)
```

The `LocalImporter` tarballs and base64-encodes the local path, sending it inline with the request.

### Exporting to S3

```python
from trelent_agents import S3Exporter

run = client.runs.create(
    sandbox="my-image:latest",
    prompt="Generate a report",
    exports=[S3Exporter(bucket="my-bucket", path="reports/")],
)
```

## Docker Registry Setup

When auth is enabled, push images to your user namespace on the registry:

```bash
# Login with your OAuth2 credentials
docker login registry.example.com -u <client_id> -p <client_secret>

# Push to your namespace
docker tag my-image:latest registry.example.com/<client_id>/my-image:latest
docker push registry.example.com/<client_id>/my-image:latest
```

When creating runs via the SDK, just use the image name without the namespace prefix:

```python
run = client.runs.create(
    sandbox="my-image:latest",  # not "<client_id>/my-image:latest"
    prompt="...",
)
```

The API resolves the full registry path automatically based on your authenticated identity.

## Types

The SDK exports the following types:

```python
from trelent_agents import (
    Client,
    Run,
    RunStatus,
    RunResult,
    RunStatusResponse,
    RegistryImage,
    CheckpointResponse,
    ChatHistoryEntry,
    FileOutput,
    OutputFile,
    HealthResponse,
    WorkflowIds,
    LocalImporter,
    S3Exporter,
    APIError,
    NotFoundError,
    ValidationError,
)
```
