tinyray

A minimal, actor-only Ray for ML experiments. Rust core, Python API.

import tinyray as tr

@tr.remote(num_gpus=1, max_restarts=3)
class Rollout:
    def __init__(self, cfg):
        self.env = make_env(cfg)
    def step(self):
        return self.env.rollout()          # ~10 MB

rollouts = tr.create_actors(Rollout, cfg, count=32)   # atomic, all or nothing
refs = [r.step.remote() for r in rollouts]            # returns immediately
ready, pending = tr.wait(refs, num_returns=24)        # 24 finished; 8 still running
learner.update.remote(ready)                          # data goes rollout -> learner

wait returns two lists of ObjectRef, never values: ready are the ones that have settled, pending the ones still running. Both are just names -- a task id and the address of the actor holding the result -- so the driver moves a few dozen bytes per reference and never the payload. Passing ready to the learner hands over those names, and the learner fetches each 10 MB batch straight from the rollout that produced it.

Dropping the eight slow rollouts drops their results, not their work: they are still running, and their outputs still occupy the producers' stores until the watermark or TTL reclaims them. And if the group runs NCCL collectives, those same eight actors must still attend the next barrier -- see tinyray.collective.

What it is, and is not

Built for one workload: RL rollouts and hyperparameter sweeps, ~32 actors, ~10 MB payloads, ~200 ms per call.

Actors only. No stateless tasks. ML workers hold models and CUDA contexts.
HTTP for control and results. At 200 ms per call a ~200 µs round trip is 0.1% overhead, and every message is inspectable with ordinary tools.
No object store. A result stays in the actor that produced it; consumers fetch it directly. No plasma, no spilling, no distributed refcounting.
NCCL for weights. tinyray implements no collective transport at all. It assigns ranks and manages the epoch state machine; torch.distributed moves the bytes.

Design notes, measurements and the decisions the implementation forced us to revise are kept with the source rather than published here.

Why Rust

An actor running a 200 ms training step holds the GIL. If the data path were Python, it could not serve result fetches during that time, and 32 actors fetching from each other would degrade to serial. The Rust core removes that coupling entirely:

10 MB decode	idle	4 GIL-bound threads	slowdown
native thread (the real serving path)	0.37 ms	0.38 ms	1.04x
initiated from Python	0.75 ms	36.7 ms	49x

Which also yields an architectural rule: the serving path must be driven by tokio, never by a Python-side loop. Work initiated from Python inherits GIL scheduling latency no matter how little of it runs in the interpreter, so /task/fetch never enters the interpreter at all.

Install

pip install tinyray

Wheels are built per interpreter version (3.9-3.13) for Linux and macOS on both x86_64 and aarch64. There is no abi3 build: the buffer protocol that makes results zero-copy is absent from the limited API on older interpreters, and version-specific wheels are a cheap price for it.

The package ships py.typed and hand-written stubs for the Rust extension, so type checkers see the full API.

From source

Requires a Rust toolchain.

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/maturin develop --release
pre-commit install

Tests

./scripts/test.sh                    # everything
cargo test --workspace               # 120 Rust tests
pytest tests/ -q                     # 216 Python tests
pytest benchmarks/ -q -s -m bench
python scripts/mutate.py             # 19 mutants: do the tests actually work?

Testing the tests

A green suite proves nothing about the tests. Three mechanisms keep them honest:

tests/test_suite_quality.py -- structural checks encoding the six blind spots that let real bugs through: unwired modules, timing constants that only ever run at their production value, options accepted but ignored, collapsed error taxonomies, untested lock branches, and design claims with no test.
tests/test_driver_byte_budget.py -- parks a 32 MB result in an actor, exercises every driver-side operation and asserts what crossed the driver's wire. The design's central claim is that payloads move between actors and never through the driver; this is where that claim is enforced for every operation rather than one.
scripts/mutate.py -- deliberately breaks 21 invariants and reports which ones the suite catches. It has already found three tests that passed while the behaviour they claimed to check was disabled.

Each check exists because a real bug got through in that exact shape.

Development

pre-commit install wires up the gates that CI also runs:

hook	what it guards
`ruff check` / `ruff format`	Python lint and formatting
`cargo fmt` / `cargo clippy -D warnings`	Rust formatting and lint
`mypy`	the public API's annotations, checked against the stubs

Releases are cut by pushing a v* tag; .github/workflows/release.yml runs the full suite, builds the wheel matrix and an sdist, and publishes to PyPI through a trusted publisher. workflow_dispatch targets TestPyPI by default so a dry run cannot reach the real index by accident.

Operations

tinyray status 127.0.0.1:41234 127.0.0.1:41235   # what is each actor doing?
tinyray introspect 127.0.0.1:41234               # raw report
tinyray health 127.0.0.1:41234

status calls out stalled callers, evictions, backpressure and stragglers, because "which actor is stuck, and on what?" is the question that dominates distributed ML debugging.

Layout

crates/tinyray-core/      wire protocol, framing, identifiers
crates/tinyray-runtime/   store, ordered queue, transport, cluster, collective, shm
crates/tinyray-py/        PyO3 bindings (all unsafe lives in buffers.rs)
python/tinyray/           API, serde, launcher, head, collective, pool, CLI

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tinyray-0.0.3.tar.gz (107.3 kB view details)

Uploaded Aug 14, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

tinyray-0.0.3-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

tinyray-0.0.3-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.13manylinux: glibc 2.17+ ARM64

tinyray-0.0.3-cp313-cp313-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (2.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.13macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

tinyray-0.0.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

tinyray-0.0.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.12manylinux: glibc 2.17+ ARM64

tinyray-0.0.3-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (2.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.12macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

tinyray-0.0.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

tinyray-0.0.3-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.11manylinux: glibc 2.17+ ARM64

tinyray-0.0.3-cp311-cp311-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (2.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.11macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

tinyray-0.0.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64

tinyray-0.0.3-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.10manylinux: glibc 2.17+ ARM64

tinyray-0.0.3-cp310-cp310-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (2.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.10macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

tinyray-0.0.3-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.9manylinux: glibc 2.17+ x86-64

tinyray-0.0.3-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.1 MB view details)

Uploaded Aug 14, 2026 CPython 3.9manylinux: glibc 2.17+ ARM64

tinyray-0.0.3-cp39-cp39-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl (2.0 MB view details)

Uploaded Aug 14, 2026 CPython 3.9macOS 10.12+ universal2 (ARM64, x86-64)macOS 10.12+ x86-64macOS 11.0+ ARM64

File details

Details for the file tinyray-0.0.3.tar.gz.

File metadata

Download URL: tinyray-0.0.3.tar.gz
Upload date: Aug 14, 2026
Size: 107.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tinyray-0.0.3.tar.gz
Algorithm	Hash digest
SHA256	`003d5be9e5db4d8eec0a7340eed4bd142454ba614539b3a52f2b41dc545a58a0`
MD5	`65ccf542c3766123056aee57495f9dab`
BLAKE2b-256	`7e4e677363740b3f51913f144eadebb84cd6a95e1231c043aa921d70fe3c373e`

Algorithm	Hash digest
SHA256	`909ad82ba1fa7e613cffff1b15a72dbe055dce0b0dab5a2e3aae160a6c1652f3`
MD5	`45a382b90f2e991438b69595e7e2824f`
BLAKE2b-256	`6bf7496976e53d502e89944946251b07ee66efc6eabd642e7ebf331869f24dc7`

Algorithm	Hash digest
SHA256	`fead0b9028b8ce196defa1af05dc11969cbb5490e72327dbecc2ab934f12cc85`
MD5	`b0c4ac209b4e296b304cc33e68dd710d`
BLAKE2b-256	`a0284727aab50730f78c04b4d108dd9110f193b7f464abf7af243d1d61e19d81`

Algorithm	Hash digest
SHA256	`924e6a731eb4b10094626d484b790ecb282c0117d4024a69226cf70d84fefaef`
MD5	`ccce5434eed6956e05d7eda67a0bc992`
BLAKE2b-256	`4256e7c4d9f50e19aa541abbd7a07babad9be16aa1df25470e24c3403cf17808`

Algorithm	Hash digest
SHA256	`1524e8c67a45f823a0cea9a072683a26b58d554d5c3bbb94cf4e03bbcb35a560`
MD5	`d9f3b3f9eaf251660cf34b28ecd87d83`
BLAKE2b-256	`0e544e05a6f31babd45ae86ad4ebdfab1f9ff7185c957f5cd686ff364f3d76b5`

Algorithm	Hash digest
SHA256	`23a0726b17c81179986e892641ea5c6b0cb15adfff163809ea4fd62bbbdeb993`
MD5	`5941cbaedf59f4943c53ede66709f57f`
BLAKE2b-256	`2f8112a1e90819a5fb0725a2a7b70c0a2bfbd0c4a80a1098b82629d439866370`

Algorithm	Hash digest
SHA256	`a59e354307ff1b5a7ac6fbe2c29ef5e69b74e011bd9c71dd15785f775c71ea62`
MD5	`4d53abc66f643871af30b98af323481d`
BLAKE2b-256	`2c242778928de2f7b1a39d4935da284f27572dd123dc9b0742bb0dad12691cfd`

Algorithm	Hash digest
SHA256	`b1d008f3f3782cde91b1c31e3e51cdb45ce8a0d50623e190f0f6deb01475642c`
MD5	`b2a55657b4f0daeceec2766ad867c98b`
BLAKE2b-256	`102655ccc0374f3fc4f398404395353d5b66c14d3b9cc6612b1cea1e81f410b2`

Algorithm	Hash digest
SHA256	`94dd45d1cf4bbfeb4596cffc311fe146709783339ace1529f20b5a3d9c097528`
MD5	`7fe07a37cd402281809d32d344facdab`
BLAKE2b-256	`6ac95824a677eff1dd9131234a15590394c3dbb6a1590fb9f673c7fdc8717b82`

Algorithm	Hash digest
SHA256	`cfcc5fc31a6a7f01ec4dd7fc467ae51c395de313a9fdeca8eccb2d27b56d590d`
MD5	`a55367808e3aa47c66a4b7a58ba01c10`
BLAKE2b-256	`7b683dd33ec1631def97352bb1307d4c04ab65a30152c55222e9d1d5eee4eb98`

Algorithm	Hash digest
SHA256	`ac72a42e7fcb9a0d7d4e35bb4d6f47cb2466e450f00027f640f7c240b9fa33eb`
MD5	`6b5ad0e4540fa4b67eabdc9f8b312e96`
BLAKE2b-256	`cf8bac282019789583972bd22de25322037c1c2a01cf0efad0006d243aa8f2e3`

Algorithm	Hash digest
SHA256	`a405399acd52f0471679c38e1de7e3d4e4a11357bafa6316aabf8d6a92c2e14d`
MD5	`03f554ac9fca429ef0188f7b2ee95c0b`
BLAKE2b-256	`d0062a855f6d2fa63668806f3090b4af72fb252ca2c0c5f696f150eb03f57875`

Algorithm	Hash digest
SHA256	`e126b751271a58808991e2cb365ff392c16fdb8c9a57290be714f4ac3c58d99e`
MD5	`40024e64df3b65e3be13bf95777fe07a`
BLAKE2b-256	`b8c46410bb0c76a669ef4a23fd33021a8318b3fc0f1e0678f1a612efb5d54006`

Algorithm	Hash digest
SHA256	`05a24fe0264866ae06b35b80959a89ac77882b3cc8dc6f728abb6d03b208be0a`
MD5	`403a83f051ba4d95eba33493e3f08bb7`
BLAKE2b-256	`c782412a64e9971b107b11823d65e703e583dcbae983219e0efebe227eaf3de9`

Algorithm	Hash digest
SHA256	`d28e8bce4e86dcdbd7ab8fdc8107f09fd6a707acf767b1b9e1e5e6d60d05e527`
MD5	`b095ce43b2904d241c812f17e55f491e`
BLAKE2b-256	`8484f91a2ae9a3420e9bfd4fbf62d3a553c4d26ce1f79573efe4eff983fc7b7a`

Algorithm	Hash digest
SHA256	`1a3c9c44463bbc8b5f3c88c4b2b53d2c393c10aa7703232a43aef8891a8edc69`
MD5	`365f0cd9534df2a2cd0d799f08eccf27`
BLAKE2b-256	`33caf3e8ef2b480b02e664ef682c089177ffe847a419f373b4d1564c7ff9914d`

tinyray 0.0.3

tinyray

What it is, and is not

Why Rust

Install

From source

Tests

Testing the tests

Development

Operations

Layout

Project links

Key dates

1 maintainer

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details