dexos-lite 0.0.8

Python client for dexos lite model inference and robot control.

dexos_lite

Command-line client for Dexos lite dataset upload and robot inference.

Installation

Install from PyPI:

pip3 install dexos-lite

Hardware-specific SDKs are loaded only when a robot controller starts. Install the SDK required by your robot before running robot inference.

Common Options

--api-key can be passed as a command option or provided through an environment variable.

export DEXOS_API_KEY=ak_xxx

Upload A Dataset

dexos-lite dataset upload /data/yellow_pepper \
  --api-key ak_xxx \
  --dataset-name yellow_pepper_dataset

Dataset uploads should use the lerobot_v3 format. For the concrete layout, see the data format section.

Optional flags:

dexos-lite dataset upload /data/yellow_pepper \
  --dataset-name yellow_pepper_dataset \
  --dataset-format lerobot_v3 \
  --description "yellow pepper pick dataset"

The upload command validates the dataset, packages a directory as tar.gz, uploads it with progress display, retries the direct upload request, and prints a final success or failure message.

Generate Robot Config

Generate config.py in the current directory:

dexos-lite robot config --robot-id mirror

Generate a config at a specific path:

dexos-lite robot config \
  --robot-id mirror \
  --path ./configs/mirror_config.py

Overwrite an existing config:

dexos-lite robot config \
  --robot-id mirror \
  --path ./config.py \
  --force

Supported robot_id values:

• mirror
• cobot_magic

Edit the generated config before inference to set controller ports, sensor serial numbers, and robot-specific options. Inference requires at least one camera sensor image. Each image must be a JPEG or PNG data URL. Images larger than 448 * 448 are centered on a black square canvas and resized to 448 * 448 before the request is sent.

Mirror Arm Service

For mirror, start the Mirror arm service before running inference. Use the mirror documentation as the source of truth for exact service options.

conda activate airbot && sleep 1 && airbot_server -i can_left -p 50051
conda activate airbot && sleep 1 && airbot_server -i can_right -p 50053

Run Robot Inference

dexos-lite robot infer \
  --api-key ak_xxx \
  --robot-config ./config.py \
  --prompt "pick up the red cube"

--robot-config accepts path.py or path.py:attribute. If no attribute is provided, robot is used.

robot infer runs for up to 600 seconds by default. Use --time-limit to set a different limit in seconds.

--continue starts inference from the robot's current pose by skipping the initial robot.reset_to_home() call. The CLI still calls robot.start() first to start hardware resources.

When inference ends because of Ctrl+C or the time limit, the CLI asks for a score from 0 to 10 and an optional feedback message, then submits it to service. When inference is interrupted with Ctrl+C, the CLI calls robot.reset_to_home() again before closing the robot.

Use Ctrl+C to stop the inference loop.

Joint-space controller commands use a fixed default interpolation step of 0.02. Set the uppercase DEXOS_INTERPOLATION_STEP environment variable to a positive float to override it, or to 0 to disable interpolation:

export DEXOS_INTERPOLATION_STEP=0

Use A Custom Robot

--robot-config can point to any Python file that exposes a BaseRobot instance or factory. If no attribute is provided, robot is used.

Custom robots must implement action_type, start(), get(), set(actions), reset_to_home(), and close().

get() must return a dict with:

• state: required. JSON-serializable current robot state sent to service as top-level state; for common arm models this is usually a flat list such as [j1, j2, j3, j4, j5, j6, gripper]. Refer to the /api/v1/action API docs for state element ordering.
• sensors: required. Dict of camera name to base64-encoded JPEG or PNG data URL. infer_robot sends this to the service as top-level images. Provide at least one image. Images larger than 448 * 448 are centered on a black square canvas and resized to 448 * 448 before the request is sent. It supports at most three keys: cam_high, cam_left_wrist, and cam_right_wrist.

Each call to set(actions) receives and executes one model action step from an action horizon. The layout and element order of the action match the state returned by get(). The inference API may return multiple steps at once as an action horizon. The CLI passes each step to set() in order and requests the next inference result after the current action horizon has finished.

Continuous CLI inference does not impose an additional action rate limit. Therefore, set() must pace the hardware and return only after the current action has completed safely.

reset_to_home() is called once before inference starts and again when inference is interrupted with Ctrl+C. Custom robots should move the hardware to a safe home pose there; if there is no real home action, still return a JSON-serializable result such as {"ok": True}.

Create custom_robot.py:

from __future__ import annotations

from typing import Any, Dict

from dexos_lite import ActionType
from dexos_lite.robot import BaseRobot


class CustomRobot(BaseRobot):
    @property
    def action_type(self) -> ActionType:
        return ActionType.JOINT

    def start(self) -> None:
        # Initialize SDKs, connect hardware, or start external services here.
        pass

    def get(self, *, sensor_timeout: float = 1.0) -> Dict[str, Any]:
        current_state = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
        # Read cameras within sensor_timeout.
        # sensors requires at least one image and supports at most these three fields.
        sensors = {
            "cam_high": "data:image/jpeg;base64,...",
            # "cam_high": "data:image/png;base64,...",
            # "cam_left_wrist": "data:image/jpeg;base64,...",
            # "cam_right_wrist": "data:image/jpeg;base64,...",
        }
        return {"state": current_state, "sensors": sensors}

    def set(self, actions: Any) -> Dict[str, Any]:
        # Send actions to your robot SDK or hardware service here.
        return {"ok": True}

    def reset_to_home(self) -> Dict[str, Any]:
        # Move the robot to a safe home pose here.
        return {"ok": True}

    def close(self) -> None:
        pass


robot = CustomRobot()

Run inference with it:

dexos-lite robot infer \
  --api-key ak_xxx \
  --robot-config ./custom_robot.py:robot \
  --prompt "pick up the red cube"

You can also expose a factory, for example def build_robot() -> CustomRobot: ..., and pass --robot-config ./custom_robot.py:build_robot.