dream-engine 0.2.0

Python SDK for Dream Engine — frontier video world models, served by Dream Labs.

dream-engine — Python SDK for Dream Engine

dream-engine is the official Python SDK for Dream Engine, the inference engine for video world models from Dream Labs. Run frontier world models (DreamDojo · GR-1, more on the way) over HTTP with a small, typed client.

Status: v0.0.1.dev0 — Phases 0 + 1 of a phased rollout. The :class:Rollout result type, :class:AsyncClient, retries, and bundled examples land in Phases 2–7. See docs/SDK_PLAN.md in the engine repo for the full schedule.

Install

pip install dream-engine

For mp4 → numpy frame decoding:

pip install "dream-engine[decode]"

Quickstart

import dream

client = dream.Client()                              # reads DREAM_API_KEY + DREAM_BASE_URL
model  = client.models.get("dreamdojo-2b-gr1")        # ModelHandle (typed; checks the catalog)
print(model.action_dim, model.resolution)            # 384, (480, 640) — flat accessors

with open("start.png", "rb") as f:
    frame_bytes = f.read()
with open("actions.npy", "rb") as f:
    actions_bytes = f.read()

response = model.predict(frame_bytes=frame_bytes, actions_bytes=actions_bytes)
print(response.engine_wall_ms, response.estimated_charge_usd)

# Always available:
with open("rollout.mp4", "wb") as f:
    f.write(response.mp4_bytes)

# When pip install "dream-engine[decode]" is installed:
print(response.frames.shape)  # (T, H, W, 3) uint8

You can pass file paths instead of bytes:

response = model.predict(frame_path="start.png", actions_path="actions.npy")

Set DREAM_API_KEY in your environment, or pass api_key=... to the Client(...) constructor. Mint keys at https://dreamlabs.ai/dashboard.

List the catalog

for handle in client.models.list():
    print(handle.slug, handle.spec.name, "active" if handle.active else "")

Visual MPC — K candidates in one server roundtrip

batch = client.predict_batch(
    frame_bytes=frame_bytes,
    actions_bytes_list=[seq_0_bytes, seq_1_bytes, ...],   # K npy blobs
)
print(batch.batch_size, batch.engine_wall_ms)
for r in batch.rollouts:
    ...  # each is a PredictResponse, same shape as the single-rollout path

A higher-level model.predict_batch(...) lands in Phase 4.

Byte-level access

If you want to skip the catalog round-trip and call the wire endpoint directly:

response = client.predict(frame_path="start.png", actions_path="actions.npy")

This bypasses ModelHandle.predict()'s active-spec check; use it for scripts that already know which model the server is running.

Coming next

Phase	What lands	When
2	Rollout result type with .save_mp4(), .cost_usd, lazy .frames	next
3	start_frame= accepts np.ndarray / PIL.Image / Path directly	after 2
4	model.predict_batch(...) ergonomic wrap	after 3
5	dream.AsyncClient	after 4
6	Typed errors + automatic retries	after 5
7	dream.examples.dreamdojo_grasp() bundled sample inputs	after 6

PredictResponse / BatchResponse will be replaced by Rollout / Batch[Rollout] in Phase 2; both will be importable from dream until the 1.0.0 release for backwards compatibility.

License

Apache-2.0. See LICENSE.