# Python SDK

> Install the rayform package, authenticate, and configure caching for laptops and clusters.

Source: https://rayform.world/docs/sdk
Last updated: 2026-10-18
Status: Rayform is in private preview. APIs, formats and the SDK described here may change before general availability.

The `rayform` package wraps the HTTP API and Arrow Flight, decodes assets, caches data locally, and loads slices into PyTorch. It supports Python 3.10 to 3.13 on Linux (x86-64 and ARM) and macOS (Apple silicon).

## Install

```bash
pip install rayform
```

The core depends only on NumPy and PyArrow, so installing it never pulls in CUDA, PyTorch or ROS. Add what you use:

| Extra | Adds |
| --- | --- |
| `rayform[torch]` | `rayform.torch.EpisodeDataset` |
| `rayform[lerobot]` | Helpers to load LeRobot exports |
| `rayform[usd]` | `Scene.to_usd()` |
| `rayform[mujoco]` | `Scene.to_mjcf()` |
| `rayform[rerun]` | `rayform.rerun.show()` |
| `rayform[all]` | Everything above |

## Authenticate

```python
import rayform

client = rayform.Client()                         # reads RAYFORM_API_KEY
client = rayform.Client(api_key="rf_live_...")    # or pass it explicitly
```

## Configuration

Every setting can be passed to `Client` or set in the environment.

| Environment variable | `Client` argument | Default | Description |
| --- | --- | --- | --- |
| `RAYFORM_API_KEY` | `api_key` | none | API key |
| `RAYFORM_BASE_URL` | `base_url` | `https://api.rayform.world/v1` | API base URL |
| `RAYFORM_CACHE_DIR` | `cache_dir` | `~/.cache/rayform` | Local content-addressed cache |
| `RAYFORM_CACHE_MAX_GB` | `cache_max_gb` | `200` | Evict least-recently-used files above this size |
| `RAYFORM_OFFLINE` | `offline` | `0` | `1` serves only from the cache and fails on any network call |
| `RAYFORM_TIMEOUT_S` | `timeout_s` | `60` | Per-request timeout |

## On clusters

- Set `RAYFORM_API_KEY` from your secret manager; the SDK never prompts.
- Point `RAYFORM_CACHE_DIR` at shared storage so every node reuses downloads.
- Run `rayform pull <slice>` once before a job, then train with `RAYFORM_OFFLINE=1`.

## Errors

All errors derive from `rayform.RayformError` and carry the API's `code` and `request_id`.

| Exception | Raised when |
| --- | --- |
| `AuthenticationError` | The key is missing or invalid |
| `PermissionError` | The key lacks the needed permission |
| `NotFoundError` | The object does not exist |
| `InvalidRequestError` | A parameter is wrong |
| `RateLimitError` | Too many requests; the SDK retries these automatically first |
| `IntegrityError` | A download or decoded asset does not match its hash; the file is evicted from the cache |
| `CodecUnavailableError` | No decoder is installed for an asset's codec; the message says what to install |
| `OfflineError` | A network call was needed while `offline` is set |

```python
try:
    slice_ = client.slices.get("slc_missing")
except rayform.NotFoundError as err:
    print(err.code, err.request_id)
```

See the [SDK reference](https://rayform.world/docs/sdk/reference) for every class and method.