Metadata-Version: 2.5
Name: openrelay-sdk
Version: 0.2.0
Summary: The official Python SDK for the OpenRelay API
Project-URL: Homepage, https://openrelay.inc
Project-URL: Documentation, https://docs.openrelay.inc
Project-URL: Repository, https://github.com/OpenRelayInc/OpenRelay
Project-URL: Issues, https://github.com/OpenRelayInc/OpenRelay/issues
Project-URL: Changelog, https://github.com/OpenRelayInc/OpenRelay/blob/master/sdks/python/CHANGELOG.md
License-Expression: MIT
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: attrs>=22.2.0
Requires-Dist: httpx<0.29.0,>=0.23.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# OpenRelay Python SDK

The official Python SDK for the [OpenRelay](https://openrelay.inc) API. It is
generated from the API's OpenAPI document (served at
`https://api.openrelay.inc/openapi.yaml`), so it has one function per API
operation and one model per schema, and it changes when the API does.

## Installation

```bash
pip install openrelay-sdk
```

It needs Python 3.11 or later. The package imports as `openrelay`. The
unrelated `openrelay` distribution on PyPI also provides a top-level
`openrelay` module, so install `openrelay-sdk`, and do not install both into
the same environment.

From a checkout of this repository: `pip install ./sdks/python`.

## Quick start

```python
import os

from openrelay import AuthenticatedClient
from openrelay.api.account import whoami
from openrelay.api.catalog import list_gpu_models
from openrelay.api.vms import create_vm, get_vm, list_org_vms
from openrelay.models import CreateVmRequest

with AuthenticatedClient(
    base_url="https://api.openrelay.inc",
    token=os.environ["OPENRELAY_API_KEY"],
) as client:
    org_id = whoami.sync(client=client).organization_id

    for gpu in list_gpu_models.sync(client=client):
        print(gpu.id, gpu.vram_gb)

    vm = create_vm.sync(
        org_id,
        client=client,
        body=CreateVmRequest(
            name="dev-box",
            ssh_key_ids=["your-ssh-key-id"],
            gpu_model_id="rtx-4090",
            gpu_count=1,
            disk_size_gb=100,
        ),
    )
    print(get_vm.sync(vm.id, client=client).status)

    for vm in list_org_vms.sync(org_id, client=client).items:
        print(vm.id, vm.status)
```

## How calls work

Each operation is a module under `openrelay.api.<tag>`, named after its
`operationId` in snake case (`getVm` is `openrelay.api.vms.get_vm`). The tags
are the sections of the [API reference](https://docs.openrelay.inc). Every
module has four functions:

| Function | Returns |
|---|---|
| `sync(...)` | the parsed body |
| `sync_detailed(...)` | a `Response` with `status_code` (an `http.HTTPStatus`, or an `int` for a status it does not name), `headers`, `content` and `parsed` |
| `asyncio(...)`, `asyncio_detailed(...)` | the same, awaited |

The parsed body is the operation's model on success, the error model the
operation documents for an error status (usually `openrelay.models.Error`,
whose `error` holds the message and `code` the machine-readable code), and
`None` for a status the API does not document. Pass `raise_on_unexpected_status=True` to
the client to get `openrelay.errors.UnexpectedStatus` instead of `None`.

Request and response models live in `openrelay.models`; optional fields
default to `openrelay.types.UNSET`. A field the API sends that the model does
not declare is kept in the model's `additional_properties`, except on the
few schemas that forbid extra fields, which drop it. An enum field
types its values as a `Literal`, and a value added to the API after this
release still parses.

Webhook payloads have models too: parse a delivery with, for example,
`openrelay.models.VmWebhookEvent.from_dict(json.loads(body))`.

## Async usage

```python
import asyncio
import os

from openrelay import AuthenticatedClient
from openrelay.api.vms import get_vm


async def main() -> None:
    async with AuthenticatedClient(
        base_url="https://api.openrelay.inc",
        token=os.environ["OPENRELAY_API_KEY"],
    ) as client:
        vm = await get_vm.asyncio("your-vm-id", client=client)
        print(vm.status)


asyncio.run(main())
```

## Configuration

`AuthenticatedClient` takes the API host as `base_url` and your `or_` API key
as `token`, which it sends as `Authorization: Bearer <token>`. The `orl` CLI
reads the key from `OPENRELAY_API_KEY` and the host from `OPENRELAY_API_URL`;
read the same variables to share one shell setup. Other options:

| Option | Meaning |
|---|---|
| `timeout` | an `httpx.Timeout` for every request, 60 seconds when not given; `None` waits forever |
| `headers` | headers added to every request, beside the `User-Agent: openrelay-python/<version>` the client sends |
| `httpx_args` | arguments for the underlying `httpx.Client` and `httpx.AsyncClient`, such as `{"transport": httpx.HTTPTransport(retries=2)}` to retry failed connections (`httpx.AsyncHTTPTransport` for async calls) |
| `raise_on_unexpected_status` | raise on a status the API does not document (above) |

## Inference

The inference API at `https://inference.openrelay.inc` (chat completions,
messages, embeddings, decisions, batches and files) is OpenAI- and
Anthropic-compatible and is not part of this package: use the `openai` or
`anthropic` SDK with OpenRelay's base URL, as
[Using OpenAI SDKs](https://docs.openrelay.inc/docs/inference/openai-sdks)
shows. This package covers everything served at `https://api.openrelay.inc`.

## Migrating from 0.1.0

0.2.0 replaces the hand-written client of 0.1.0, whose routes the API does
not serve, so no 0.1.0 call worked. The package name and the `openrelay`
import stay; the rest is renamed:

| 0.1.0 | 0.2.0 |
|---|---|
| `openrelay.Client(api_key=...)`, `openrelay.AsyncClient(...)` | `openrelay.AuthenticatedClient(base_url="https://api.openrelay.inc", token=...)`, for both sync and async calls |
| the key and host read from `OPENRELAY_API_KEY` and `OPENRELAY_API_URL` | pass `token` and `base_url` (read the variables yourself) |
| `timeout=60.0` | `timeout=httpx.Timeout(...)`, 60 seconds when not given |
| `max_retries`, which retried timeouts, connection failures and 429, 500, 502, 503 and 504 responses | no built-in retry. `httpx_args={"transport": httpx.HTTPTransport(retries=...)}` retries failed connections only, and async calls need their own client built with `httpx.AsyncHTTPTransport` |
| `client.gpus.list()` | `openrelay.api.catalog.list_gpu_models.sync(client=client)` |
| `client.gpus.availability()` | `openrelay.api.catalog.get_gpu_availability.sync(client=client)` |
| `client.gpus.pricing()` | `openrelay.api.catalog.get_pricing.sync(client=client)` |
| `client.vms.create(...)` | `openrelay.api.vms.create_vm.sync(org_id, client=client, body=CreateVmRequest(...))` |
| `client.vms.get(vm_id)` | `openrelay.api.vms.get_vm.sync(vm_id, client=client)`, or `get_vm_detail` for the full record |
| `client.vms.stop`, `restart`, `reboot` | `openrelay.api.vms.stop_vm`, `restart_vm`, `reboot_vm` |
| `client.vms.delete(vm_id)` | `openrelay.api.vms.terminate_vm.sync(vm_id, client=client)` |
| `client.vms.wait_for_status(vm_id)` | poll `get_vm.sync` until `status` is the one you want |
| `openrelay.Vm`, `VmCreateResponse`, `VmActionResponse` | `openrelay.models.VmSummary`, which create, get, stop, restart and terminate return (reboot returns no body), and `VmDetail` |
| `openrelay.GpuModel`, `GpuAvailability`, `GpuPricing` and the other 0.1.0 types | the models in `openrelay.models` each operation returns, such as `GpuModel`, `GpuAvailability` and `Pricing` |
| `OpenRelayError` and its subclasses, raised on an error status | an `openrelay.models.Error` returned as the parsed body; `openrelay.errors.UnexpectedStatus` for an undocumented status |
| `openrelay.__version__` | `importlib.metadata.version("openrelay-sdk")` |
| Python 3.8 or later | Python 3.11 or later |

## Development

The package under `src/openrelay` is generated; edit the API's spec, never
the package. After a change to `services/control-plane-go/openapi.public.yaml`,
regenerate it from `sdks/python` with the pinned toolchain:

```bash
pip install --require-hashes -r codegen/requirements.txt
python codegen/generate.py
```

`python codegen/generate.py --check` fails when the package differs from what
the spec generates; CI runs it on every change to the spec or the SDK. The
tests run with `pip install -e ".[dev]"` and `pytest tests/`.

## License

MIT
