Metadata-Version: 2.4
Name: dropbear
Version: 0.1.0a2
Summary: Cloud robot policy inference — one function call.
Project-URL: Homepage, https://dropbear.dreamscalelabs.com
Project-URL: Documentation, https://dropbear.dreamscalelabs.com/docs
Author: Dreamscale Labs
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: inference,physical-ai,robotics,vla
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.11
Requires-Dist: dropbear-transport==0.1.1a2
Requires-Dist: httpx<1,>=0.27
Requires-Dist: numpy<3,>=2.0
Requires-Dist: pillow<12,>=10
Requires-Dist: rich<14,>=13.9
Requires-Dist: tomli-w<2,>=1.0
Requires-Dist: typer<0.26,>=0.12
Requires-Dist: typing-extensions<5,>=4.10
Provides-Extra: sim
Requires-Dist: bddl==1.0.1; extra == 'sim'
Requires-Dist: easydict<2,>=1.13; extra == 'sim'
Requires-Dist: future<2,>=1; extra == 'sim'
Requires-Dist: imageio<3,>=2.36; extra == 'sim'
Requires-Dist: matplotlib<4,>=3.9; extra == 'sim'
Requires-Dist: mujoco<4,>=3.2; extra == 'sim'
Requires-Dist: opencv-python<5,>=4.10; extra == 'sim'
Requires-Dist: pyyaml<7,>=6; extra == 'sim'
Requires-Dist: robosuite==1.4.1; extra == 'sim'
Provides-Extra: so101
Requires-Dist: lerobot[feetech]==0.5.1; extra == 'so101'
Description-Content-Type: text/markdown

# Dropbear

Cloud robot policy inference — one function call.

> `0.1.0a2` is a pre-alpha release. Pin the exact version while the public API
> is still evolving.

## Install

Add Dropbear to a Python 3.11–3.14 project:

```bash
uv add "dropbear==0.1.0a2"
```

Install the CLI as a standalone tool:

```bash
uv tool install "dropbear==0.1.0a2"
dropbear login
```

The base package contains cloud inference, transport, model contracts, and
robot-neutral observation helpers. Install a hardware or simulator stack only
when you need it:

```bash
uv add "dropbear[so101]==0.1.0a2"
uv add "dropbear[sim]==0.1.0a2"
```

The base SDK supports Python 3.11 through 3.14. The `so101` extra currently
supports Python 3.12 and 3.13 because its pinned LeRobot dependency requires
Python 3.12 and does not yet provide a wheel-compatible Python 3.14 dependency
stack.

The `sim` extra is currently Linux/WSL2 only because of upstream
LIBERO/robosuite limitations.

## Cloud policy inference

```python
import dropbear

policy = dropbear.connect()  # defaults to molmoact2-so101
policy.run(
    instruction="pick up the cube",
    observe=observe,
    act=act,
    max_actions=300,
)
```

`dropbear.connect()` is the canonical SDK entrypoint.
`connect_so101()` is a deprecated compatibility path for the legacy physical
SO-101 safety loop and will be removed after that behavior is folded into the
generic policy surface. New cloud-policy work should use `dropbear.connect()`.
There is no first-class public `connect_libero()` or `connect_franka()`
entrypoint; use `dropbear.connect(model="molmoact2-libero")` or select another
checkpoint with `model=`.

Use a context manager so every cloud session closes deterministically:

```python
import dropbear

with dropbear.connect(model="molmoact2-libero") as policy:
    result = policy.run(
        instruction="put the mug on the plate",
        observe=observe,
        act=act,
        max_actions=220,
        strategy=dropbear.RunStrategy.libero_default(),
    )
```

`region="nearest"` is the default. `region="available"` may fall back to
another supported region when the nearest region has no capacity. Passing an
AWS region pins the session there.

`transport="auto"` tries QUIC first and can use the hosted relay;
`transport="quic"` requires QUIC, and `transport="relay"` uses the relay
directly.

## MolmoAct2-DROID on Franka

MolmoAct2-DROID consumes an exterior RGB view and wrist RGB view. A second
exterior view is optional; when omitted, Dropbear reuses the first exterior
frame for the checkpoint's second exterior slot.

Robot state is seven Franka joint positions in radians followed by a gripper
value in `[0, 1]`.

```python
import numpy as np
import dropbear

exterior_rgb = np.zeros((480, 640, 3), dtype=np.uint8)
wrist_rgb = np.zeros((480, 640, 3), dtype=np.uint8)

observation = dropbear.franka.observe(
    exterior_frame=exterior_rgb,
    wrist_frame=wrist_rgb,
    joint_positions=[0.0] * 7,
    gripper=0.5,  # 0=open, 1=closed
)

with dropbear.connect(model="molmoact2-droid") as policy:
    result = policy.predict(
        observation,
        instruction="pick up the green block",
    )

assert len(result.actions) == 15
assert all(len(action) == 8 for action in result.actions)
```

The checkpoint returns a 15-step chunk at 15 Hz. Each action is an absolute
target `[joint_0, ..., joint_6, gripper]`; joints are radians and the gripper is
in `[0, 1]`.

`predict()` does not actuate hardware or provide a Franka safety controller.
Validate joint, velocity, acceleration, workspace, collision, and gripper
limits before sending any target to a robot.

## MolmoAct2-BimanualYAM

This surface was introduced in `0.1.0a2`; `0.1.0a1` does not include it.

The BimanualYAM checkpoint consumes three RGB views in exact `top`, `left`,
`right` order. State and absolute actions are 14 values:
`[left_joint_0..5, left_gripper, right_joint_0..5, right_gripper]`, with joints
in radians and each gripper in `[0, 1]`.

```python
observation = dropbear.yam.observe(
    top_frame=top_rgb,
    left_frame=left_rgb,
    right_frame=right_rgb,
    left_joint_positions=left_joint_radians,
    left_gripper=left_gripper,
    right_joint_positions=right_joint_radians,
    right_gripper=right_gripper,
)

with dropbear.connect(model="molmoact2-bimanual-yam") as policy:
    result = policy.predict(observation, instruction="fold the towel")
```

The checkpoint returns 30 actions at 30 Hz. `predict()` performs inference only;
the caller remains responsible for synchronized two-arm validation, soft
limits, collision handling, watchdogs, and physical e-stop procedures. See the
complete single-chunk example in
[`examples/yam_inference.py`](examples/yam_inference.py).

The model is staged behind empty Terraform region gates and a `coming_soon`
catalog entry. This SDK contract does not make it allocatable as a live session.

## Manual action loop

For a caller-owned control loop, pass the task instruction to
`policy.next_action(...)`. Dropbear owns inference, refill, action buffering,
calibration, and RTC prefix context; the caller owns sensing, actuation, and
loop cadence.

```python
import time

dt = 1.0 / policy.action_hz
while running:
    tick = time.perf_counter()
    action = policy.next_action(
        observe(),
        instruction="put the mug on the plate",
    )
    robot.execute(action)
    time.sleep(max(0.0, dt - (time.perf_counter() - tick)))
```

## CLI

Sign in once. Credentials are stored in `~/.dropbear/config.toml`.

```bash
dropbear login
dropbear status
```

For non-interactive setup, pass an API key or use bare `--api-key` to paste it
into a hidden prompt:

```bash
dropbear login --api-key dropbear_sk_...
dropbear login --api-key
```

Run robot-neutral setup checks:

```bash
dropbear doctor
```

SO-101 and simulation checks are explicit:

```bash
dropbear doctor so101
dropbear doctor sim
```

Install shell completion with:

```bash
dropbear --install-completion
```

Useful session commands:

```bash
dropbear sessions list
dropbear sessions stop <session-id>
dropbear sessions stop --all
```

Documentation: https://dropbear.dreamscalelabs.com/docs
