> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dreamscalelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat the Dreamscale Python SDK and CLI as the supported public integration surfaces.
> Prefer context-managed sessions and model-specific observation helpers.
> Do not infer or recommend internal control-plane APIs.

# Model contracts

> Match camera, state, action ordering, units, chunk size, and rate for the live Dreamscale models.

A Dreamscale observation is expressed in the selected model's coordinates, not
necessarily your controller's coordinates. Convert at the `RobotIO` boundary
and validate the returned model action before converting it back.

<Warning>
  Matching a vector length is not enough. Joint order, units, camera order,
  gripper convention, and absolute-versus-delta semantics must all match.
</Warning>

The production catalog exposes the contracts below. Check
[Models](https://app.dreamscalelabs.com/dashboard/models) before opening a
session because availability is region- and account-dependent, and some models
require an entitlement on your organization.

| Model              | Observation helper              | Output                                 | Nominal rate | Access               |
| ------------------ | ------------------------------- | -------------------------------------- | ------------ | -------------------- |
| `molmoact2-so101`  | `dreamscale.so101.observe`      | 30 × 6 absolute joint positions        | 30 Hz        | Open                 |
| `molmoact2-libero` | `dreamscale.libero.observe`     | 10 × 7 delta end-effector actions      | 10 Hz        | Open                 |
| `molmoact2-droid`  | `dreamscale.franka.observe`     | 15 × 8 absolute joint/gripper targets  | 15 Hz        | Open                 |
| `dreamzero-yam`    | bimanual observation, see below | 24 × 14 absolute joint/gripper targets | 30 Hz        | Entitlement required |

<Note>
  `molmoact2-droid` is listed in the catalog but has no serving capacity in the
  current region set. `dreamscale status --model molmoact2-droid` reports what is
  actually available before you write against it.
</Note>

## DreamZero-YAM

DreamZero-YAM drives a bimanual I2RT YAM. It is entitlement-gated: your
organization must be granted access before a session will open.

<Warning>
  This is a research robot-control model. Validate the task, workspace, joint
  and velocity limits, emergency stop, and human supervision before any
  hardware use.
</Warning>

### Observation

Three RGB cameras and the packed bimanual joint state, each frame carrying a
real monotonic capture time:

```python theme={null}
observation = dreamscale.dreamzero_yam.observe(
    top_frame=top_rgb,
    left_frame=left_rgb,
    right_frame=right_rgb,
    camera_capture_times_ns=(top_ns, left_ns, right_ns),
    left_joint_positions=left_six_joint_radians,
    left_gripper=left_gripper_position,
    right_joint_positions=right_six_joint_radians,
    right_gripper=right_gripper_position,
)
```

### Action

| Property        | Value                                                          |
| --------------- | -------------------------------------------------------------- |
| Shape           | 24 × 14                                                        |
| Space           | `raw_absolute_joint`                                           |
| Ordering        | left six joints, left gripper, right six joints, right gripper |
| Gripper indices | 6 and 13                                                       |
| Native rate     | 30 Hz                                                          |
| Horizon         | 0.8 s per chunk                                                |
| Hold behaviour  | holds current position when the buffer underruns               |

Grippers are continuous absolute joint positions, not binary open/close
commands. Do not threshold them.

### Command rate

The model is native at 30 Hz. You may request 5–30 Hz at connect, and Dreamscale
stretches the action horizon to match rather than dropping actions, so a 24-step
chunk covers 0.8 s at 30 Hz and 2.4 s at 10 Hz. Lower rates trade responsiveness
for a longer buffer.

## MolmoAct2 SO-101

### Observation

```python theme={null}
observation = dreamscale.so101.observe(
    side_frame=side_rgb,
    wrist_frame=wrist_rgb,
    joint_positions=[
        shoulder_pan_deg,
        shoulder_lift_deg,
        elbow_flex_deg,
        wrist_flex_deg,
        wrist_roll_deg,
        gripper_position,
    ],
)
```

* `side_frame`: H×W×3 RGB image.
* `wrist_frame`: H×W×3 RGB image from a distinct arm-mounted camera.
* `joint_positions`: six finite values in LeRobot SO-101 order and degrees.
* `gripper_position`: LeRobot's 0–100 position convention.
* `actions_remaining`: optional nonnegative buffer depth; the policy loop sets
  this when needed.

### Action

Each returned action has this order:

```text theme={null}
[shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper]
```

The values are absolute targets in the same degrees and gripper convention as
the observation. A normal chunk contains 30 actions for a 30 Hz controller.

On an underrun, the managed loop uses the current observation position as its
hold target. Your robot controller must still enforce per-tick changes, motor
limits, watchdogs, and the physical stop path.

## MolmoAct2 LIBERO

### Observation

```python theme={null}
observation = dreamscale.libero.observe(
    agent_frame=agent_rgb,
    wrist_frame=wrist_rgb,
    state=[
        eef_x,
        eef_y,
        eef_z,
        axis_angle_x,
        axis_angle_y,
        axis_angle_z,
        gripper_qpos_0,
        gripper_qpos_1,
    ],
)
```

The eight state values are end-effector position, end-effector rotation as an
axis-angle vector converted from the environment's XYZW quaternion, then the
two simulator gripper joint positions.

### Action

A normal chunk contains ten 7D robosuite/LIBERO delta actions at 10 Hz:

```text theme={null}
[delta_x, delta_y, delta_z, delta_axis_x, delta_axis_y, delta_axis_z, gripper]
```

Use the action directly only with the matching LIBERO/robosuite environment
configuration. A physical robot controller has a different contract.

## MolmoAct2 DROID

### Observation

```python theme={null}
observation = dreamscale.franka.observe(
    exterior_frame=exterior_rgb,
    wrist_frame=wrist_rgb,
    joint_positions=joint_radians,
    gripper=gripper_position,
    second_exterior_frame=second_exterior_rgb,
)
```

* `exterior_frame`: required H×W×3 `uint8` RGB view.
* `wrist_frame`: required H×W×3 `uint8` RGB view.
* `second_exterior_frame`: optional second exterior RGB view. When omitted,
  Dreamscale maps the first exterior view to both exterior inputs.
* `joint_positions`: seven finite Franka joint positions in radians.
* `gripper`: one finite value from 0 (open) to 1 (closed).

### Action

Each returned action has this order:

```text theme={null}
[joint_0, joint_1, joint_2, joint_3, joint_4, joint_5, joint_6, gripper]
```

The values are absolute joint targets in radians followed by the unit-interval
gripper target. A normal chunk contains 15 actions for a 15 Hz controller.

<Warning>
  Dreamscale provides DROID inference, not a Franka safety controller. Stop at
  `predict()` until your local stack validates joint, velocity, acceleration,
  workspace, collision, gripper, watchdog, and e-stop behavior.
</Warning>

## Validate at the boundary

For every model:

1. Record the raw controller state and the converted model state.
2. Assert camera color order, dtype, shape, and source identity.
3. Assert vector length, order, units, and finite values.
4. Inspect one non-actuating prediction.
5. Reject every output outside local limits before any coordinate conversion.
6. Test hold and e-stop behavior without cloud connectivity.

Continue to the [SO-101](/guides/so101) or [Franka](/guides/franka) recipe.