dream_library

The public dream library: everything a customer installs to drive a robot with a Dream-1 policy through DreamAPI. Two products live here, each with its own package, tests, docs and changelog:

dreamlabs, the distribution this directory's pyproject.toml defines, is the library as one pip install: it depends on dreamlabs-client for the client (the dream package, with shared.datasets, the dataset checks it runs) and its wheel carries the robots package, the parts of the monorepo's shared package robots imports (shared.contracts.live, the live-view wire; shared.faceblur, the blur at capture), copied in from ../shared when the wheel is built, the vendored YAM arm driver i2rt (vendor/i2rt/), and dream's IK (dream_ik, from vendor/dream_ik/, with the pyroki and jaxls it solves with, vendor/pyroki/ and vendor/jaxls/), which the client's ik config key uses. One install gives the client, the robots package and the dreamcli command. No file is in both wheels, so the two install side by side, and pip install dreamlabs-client alone is the client with nothing else.

Examples

Dream YAM Sim runs two simulated arms with live cameras and a task terminal: dreamcli example yam-mujoco once the library is installed (examples/README.md).

Install

On a station, the platform's Setup API page gives one block that does it all: uv, a Python 3.12 environment at ~/dream-env, that site's build of this library, and ~/.dreamlabs/credentials. By hand, a plain pip install into a Python 3.12 venv (Ubuntu's system Python refuses installs outside one, and Ubuntu 22.04's python3 is 3.10, where dream's IK, which a Makers or Metal arm needs, does not install):

uv venv --seed --python 3.12 ~/dream-env && source ~/dream-env/bin/activate
pip install dreamlabs                                         # from PyPI: everything a station runs (brings dreamlabs-client)
pip install dreamlabs-client                                  # from PyPI: the client alone, `import dream`, nothing else
pip install ./dreamlabs_client-<version>-py3-none-any.whl ./dreamlabs-<version>-py3-none-any.whl   # the two files the Setup API page downloads
pip install ./dreamlabs-prod/dream_library/dream_client ./dreamlabs-prod/dream_library   # from a checkout: everything (both, so the client is this tree's)
pip install ./dreamlabs-prod/dream_library/dream_client       # from a checkout: the client alone
pip install "dreamlabs-client @ git+https://github.com/dreamlabs-co/dreamlabs.git#subdirectory=dream_library/dream_client" "dreamlabs @ git+https://github.com/dreamlabs-co/dreamlabs.git#subdirectory=dream_library"   # from the public copy

One install is the whole station: the base dependency list carries the arm driver's own runtime requirements, mujoco for the arm model, PyAV and websockets for the live view, and pyrealsense2 for the RealSense cameras, which is marked Linux and Python 3.12 or older because its wheels stop there. The three extras hardware, ui and live are kept as empty aliases, so an instruction that says pip install "dreamlabs[hardware,ui]" resolves and installs the same thing. One extra adds something: so101, the robots package's own, LeRobot's Feetech bus for an SO-101 station (pip install "dreamlabs[so101]", Python 3.12 or newer; it brings torch, so only an SO-101 station installs it). The driver itself, i2rt, is in the wheel: vendor/i2rt/ is a verbatim copy of the upstream package at the commit robots pins, and vendor/i2rt/VENDOR.md says why, and which of its requirements are left out: ruckig and evdev, because nothing imports them and neither ships a wheel, so the install needs no compiler and no access to GitHub. dream's IK is in the wheel the same way (vendor/dream_ik/VENDOR.md), and on Python 3.11 or newer the base list carries what it needs, JAX 0.7.1 among them; it is left out on 3.10, where JAX 0.7.1 does not install, and the client's ik key says so. The PyPI names are dreamlabs and dreamlabs-client; dream on PyPI is another project.

The wheel is built from the source tree it is installed from, and reaches ../shared while it builds, so the install works from the monorepo (a checkout, or the clone pip makes of the git URL above); a copy of this directory alone, with no shared/ beside it, does not build. Inside the monorepo, uv sync in this directory makes a venv with both products installed editable and the shared parts copied in (uv run dreamcli --help); each product's own directory has its own venv, lock and make check for development, and make check here runs tests/test_distribution.py, which holds this file's dependencies and extras to the products' own.

A station, end to end

# first, ~/.dreamlabs/credentials: the install block on the platform's Setup API page writes it (and installs this library)
dreamcli setup          # the setup wizard on port 8092 (open the private address it prints): arms, cameras -> ~/.dreamlabs/station.yaml
dreamcli robot up       # the station agent on that file; its API on :8091; nothing moves until a Start
dreamcli robot log      # the last 40 lines of ~/.dreamlabs/station.log
dreamcli robot down     # stops the agent: the arms switch off and go limp (support them first); it says whether they are off

robots/README.md, Command line, is the reference for the four commands; Config file there documents every key the wizard writes.

Versions

dreamlabs (this directory) and dreamlabs-client (dream_client/) are both 0.0.3, their first release on PyPI, where the numbering restarts (2026-10-18). Before it the library was the dream distribution, which bundled the client, and the client was dream-client, numbered 1.x to 4.x inside Dream Labs (the client's last was 4.1.0, the library's 4.0.0); 0.0.3 continues from those, it does not precede them. It is the version where dream.DreamClient keeps the camera frames itself and set_observation() with a bare get_action() is the only way to run a model (dream.init and get_action(observation) are gone), and where DreamClient.policy() converts between a robot's parts and the slots a fine-tune trained on; DreamAPI refuses a checkpoint whose robot has parts to any older client (shared.contracts.v1.MIN_PARTS_CLIENT), so a robot with parts needs it. DreamAPI's oldest accepted major (shared.contracts.v1.MIN_CLIENT_MAJOR) went from 4 to 0 with the restart, so a library of either numbering is served. pip orders versions by number, so a 4.x already installed counts as newer than 0.0.3: pip install -U dreamlabs from PyPI leaves it in place, so uninstall it first (pip uninstall dreamlabs dreamlabs-client); installing the platform's two wheels by file, as the Setup API page does, replaces it. The robots package keeps its 0.x line as dream-robots (robots.__version__). dream.__version__ is read on import from the metadata of the distribution that owns the package, which is dreamlabs-client in either install (with the commit, 0.0.3+g<commit>, in the wheels the platform's web image builds); robots.__version__ is dreamlabs's. dreamlabs asks for the client at >=0.0.3,<1, so a client release within the major needs no library release.