Python SDK | Docs

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

Shell

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 for every class and method.