Metadata-Version: 2.4
Name: dream-engine
Version: 0.2.0
Summary: Python SDK for Dream Engine — frontier video world models, served by Dream Labs.
Project-URL: Homepage, https://dreamlabs.ai
Project-URL: Documentation, https://dreamlabs.ai/docs
Project-URL: Repository, https://github.com/kingjulio8238/dreamengine
Project-URL: Bug Tracker, https://github.com/kingjulio8238/dreamengine/issues
Author-email: Dream Labs <hello@dreamlabs.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: dream-engine,inference,robotics,video-diffusion,world-models
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: numpy>=2.0
Requires-Dist: pillow>=10
Provides-Extra: decode
Requires-Dist: mediapy>=1.2; extra == 'decode'
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pillow>=10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-xdist; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# dream-engine — Python SDK for Dream Engine

`dream-engine` is the official Python SDK for [Dream Engine](https://dreamlabs.ai),
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`](https://github.com/kingjulio8238/dreamengine/blob/main/docs/SDK_PLAN.md)
> in the engine repo for the full schedule.

## Install

```bash
pip install dream-engine
```

For mp4 → numpy frame decoding:

```bash
pip install "dream-engine[decode]"
```

## Quickstart

```python
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:

```python
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

```python
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

```python
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:

```python
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`.
