Metadata-Version: 2.4
Name: dream-engine
Version: 0.4.1
Summary: Python SDK for Dream Engine — frontier video world models, served by Dream Engines.
Project-URL: Homepage, https://dreamengines.run
Project-URL: Documentation, https://dreamengines.run/docs
Project-URL: Repository, https://github.com/kingjulio8238/dreamengine
Project-URL: Bug Tracker, https://github.com/kingjulio8238/dreamengine/issues
Author-email: Dream Engines <hello@dreamengines.run>
License: Apache-2.0
License-File: LICENSE
Keywords: dream-engine,inference,robotics,video-diffusion,world-models
Classifier: Development Status :: 4 - Beta
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'
Provides-Extra: io
Requires-Dist: boto3>=1.34; extra == 'io'
Requires-Dist: datasets>=3.0; extra == 'io'
Requires-Dist: huggingface-hub>=0.24; extra == 'io'
Requires-Dist: pyarrow>=15; extra == 'io'
Description-Content-Type: text/markdown

# dream-engine — Python SDK for Dream Engine

`dream-engine` is the official Python SDK for [Dream Engine](https://dreamengines.run),
the inference engine for video world models from Dream Engines. Run frontier
world models (DreamDojo · GR-1, more on the way) over HTTP with a small,
typed client.

> **Status:** v0.4.0 — stable release. `Rollout`, `AsyncClient`,
> typed errors, retries, `predict_batch`, and bundled examples are all
> available. See
> [`sdk/python/CHANGELOG.md`](https://github.com/kingjulio8238/dreamengine/blob/main/sdk/python/CHANGELOG.md)
> for the full version history.

## Install

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

For mp4 → numpy frame decoding:

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

## Quickstart

```python
import dream
import numpy as np
from PIL import Image

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

img  = Image.open("start.png")
acts = np.load("actions.npy")                        # (48, 384) float32

rollout = model.predict(start_frame=img, actions=acts)
print("frames:", rollout.frames, "cost:", rollout.cost_usd)
rollout.save("rollout.mp4")

# Access decoded frames as a numpy array (requires [decode] extra):
print(rollout.video().shape)  # (T, H, W, 3) uint8
```

You can also pass file paths or raw bytes:

```python
# Paths (str or Path) — SDK reads the file and encodes for the wire
rollout = model.predict(start_frame="start.png", actions="actions.npy")
```

Set `DREAM_API_KEY` in your environment, or pass `api_key=...` to the
`Client(...)` constructor. Mint keys at <https://dreamengines.run/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
import numpy as np

candidates = np.random.randn(8, 48, 384).astype(np.float32)  # (K, T, action_dim)

batch = model.predict_batch(start_frame=img, actions=candidates)
print(batch.batch_size, batch.engine_wall_ms)
for r in batch.rollouts:
    print(r.cost_usd)
```

## Wire-level access (advanced)

If you want to skip the `ModelHandle` layer and call the endpoint with
pre-encoded bytes:

```python
# Low-level: bypasses active-spec check and input coercion
response = client.predict(frame_bytes=frame_bytes, actions_bytes=actions_bytes)
```

> **Prefer `model.predict(start_frame=…, actions=…)` for most use
> cases.** The wire-level path is for scripts that already have
> wire-ready bytes and don't need the typed `Rollout` result.

## License

Apache-2.0. See `LICENSE`.
