V-Modal Robotics / Physical AI SDK

vmodal-robotics moves finalized LeRobot dataset artifacts off a robot without turning the recording process into a distributed system. The producer closes its files and atomically publishes one .ready.json manifest. The SDK verifies the handoff, copies the exact bytes into a durable local spool, and tracks every artifact until it is durably acknowledged or explicitly blocked.

The base runtime is CPython plus Fire. It does not import LeRobot, PyTorch, pandas, ROS, GStreamer, or a database server. SQLite is provided by the Python standard library.

Robot-grade invariants

flowchart LR
    R[LeRobot recorder] -->|close + hash| D[(LeRobot v3 dataset)]
    R -->|atomic rename| M[*.ready.json]
    M --> A[LeRobot adapter]
    D --> A
    A -->|verify + immutable copy| S[(SQLite WAL<br/>checksum-keyed objects)]
    S --> V[video lane]
    S --> X[aux lane<br/>Parquet / metadata / opaque]
    V --> T[Transport]
    X --> T
    T -->|durable receipts| S
    S -->|all artifacts ACK| P[revision publish]

Boot it on a robot

Python 3.10 through 3.13 is supported. Install the tagged public source with the V-Modal cloud transport:

python -m pip install \
  "vmodal-robotics[vmodal] @ git+https://github.com/v-modal/vmodal_sdk_robotics.git@v0.1.0"

For a custom transport, install the lean core:

python -m pip install \
  "vmodal-robotics @ git+https://github.com/v-modal/vmodal_sdk_robotics.git@v0.1.0"

Configure the standard VMODAL_* variables used by the V-Modal Python SDK, then point the daemon at the producer handoff directory and a persistent local disk:

export VMODAL_ROBOT_READY_DIR=/data/lerobot/vmodal-ready
export VMODAL_ROBOT_SPOOL_DIR=/var/lib/vmodal-robot

vmodal-robot run

Inspect the queue or drain it during a controlled shutdown:

vmodal-robot status --spool_dir=/var/lib/vmodal-robot
vmodal-robot flush --spool_dir=/var/lib/vmodal-robot --deadline_seconds=120

run catches SIGINT and SIGTERM, stops admission, and flushes the existing backlog for up to --shutdown_deadline seconds.

The handoff protocol

The ready manifest is a commit record. Publish it only after every referenced file and the metadata snapshot are closed and immutable. Its filename must end in .ready.json.

{
  "contract_version": 1,
  "source_format": "lerobot",
  "source_version": "v3",
  "source_id": "arm-cell-07",
  "dataset_key": "gearbox/insertion",
  "dataset_root": "../dataset",
  "destination": "robot-data/arm-cell-07",
  "source_revision": "capture-000042",
  "complete": true,
  "artifacts": [
    {
      "path": "videos/chunk-000/observation.images.wrist.mp4",
      "kind": "video",
      "content_type": "video/mp4",
      "size_bytes": 73400320,
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "source_refs": {
        "camera_key": "observation.images.wrist",
        "episodes": [40, 41],
        "video_offsets": [0.0, 8.42]
      },
      "timing": {
        "source_clock": "lerobot.timestamp",
        "start": 0.0,
        "end": 16.81
      }
    },
    {
      "path": "data/chunk-000/file-000.parquet",
      "kind": "telemetry",
      "content_type": "application/vnd.apache.parquet",
      "size_bytes": 8192,
      "sha256": "123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0",
      "source_refs": {
        "episodes": [40, 41],
        "row_ranges": [[0, 252], [252, 504]]
      },
      "timing": {
        "source_clock": "lerobot.timestamp",
        "start": 0.0,
        "end": 16.81
      }
    },
    {
      "path": "meta/info.json",
      "kind": "metadata",
      "content_type": "application/json",
      "size_bytes": 2048,
      "sha256": "23456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01",
      "source_refs": {"snapshot": "capture-000042"}
    }
  ]
}

Replace the example sizes and hashes with values computed from the closed files. Every revision requires at least one metadata artifact. Supported artifact kinds are video, telemetry, metadata, and opaque; LeRobot videos must be MP4 and telemetry files must be Parquet.

A robust producer handoff is deliberately boring:

1. Close the MP4, Parquet, and metadata snapshot.
2. Compute each byte length and SHA-256.
3. Write the manifest under a temporary filename in the ready directory.
4. Flush it, fsync it, and atomically rename it to *.ready.json.
5. Leave the referenced bytes immutable.

Absolute artifact paths, .. escapes, symlinks, duplicate paths, missing files, changing files, invalid checksums, and unsupported dataset versions are rejected and recorded in the spool database.

State machine and failure semantics

                         transient failure
                    ┌────────────────────────┐
                    ▼                        │
READY ──claim──▶ SENDING ──ACK────────▶ ACKNOWLEDGED
                    │
                    ├──retry──────────▶ RETRY_WAIT
                    │                     │
                    │                     └──backoff elapsed──▶ SENDING
                    │
                    └──terminal / max attempts──────────────▶ BLOCKED

startup: SENDING ──reconcile──▶ ACKNOWLEDGED | READY | BLOCKED

Retries use exponential backoff with jitter: one second initially, capped at five minutes, with ten attempts by default. A transport receipt is accepted only when it carries the expected item identity, ACKNOWLEDGED state, a stable remote reference, and a non-conflicting checksum.

Scheduling and storage bounds

The video lane and auxiliary lane each claim one item per cycle and execute concurrently. Dataset revisions are serialized behind their artifacts. Default limits are intentionally finite:

Use a spool path on persistent storage. status emits machine-readable JSON with queue depth and bytes per lane, oldest item age, disk headroom, retry and rejection counts, blocked items, and the latest durable receipt:

vmodal-robot status --spool_dir=/var/lib/vmodal-robot | python -m json.tool

Transport boundary

The runner depends on three async transport operations:

class Transport:
    async def deliver(self, artifact, destination): ...
    async def reconcile(self, artifact, destination): ...
    async def publish_revision(self, revision): ...

This narrow seam makes S3, R2, an on-prem object store, or a lab receiver easy to integrate without importing those clients into the recorder. A successful operation returns a Receipt with a stable remote_ref and status ACKNOWLEDGED.

Current V-Modal cloud support is explicit:

Until the generic artifact and revision endpoints are qualified, the built-in transport places those operations in BLOCKED. It never routes original Parquet or metadata bytes through a video-description endpoint.

Hack on it

Clone the public repository and run the complete fake-data suite:

git clone https://github.com/v-modal/vmodal_sdk_robotics.git
cd vmodal_sdk_robotics
bash test.sh test

The suite uses tiny synthetic MP4, Parquet, metadata, and opaque payloads. It exercises byte-for-byte delivery, multi-camera and multi-episode references, lane independence, quota rejection, retry backoff, lost responses, process restart reconciliation, cleanup, the custom adapter seam, packaging, and a clean public install. No robot, camera, ROS graph, or cloud account is needed.

src/vmodal_robot/
├── adapters/lerobot.py      # strict LeRobot v3 ready-manifest parser
├── contracts.py             # adapter, artifact, revision, receipt, transport
├── runner.py                # scheduler, retries, recovery, graceful drain
├── spool.py                 # durable state machine + content-addressed objects
├── transports/vmodal.py     # optional V-Modal cloud bridge
└── utils.py                 # hashing, safe paths, atomic durable copies

Useful entry points:

vmodal-robot --help
vmodal-robot run --help
vmodal-robot status --help
vmodal-robot flush --help
bash test.sh package

If you are integrating a new recorder or transport, keep the invariant that matters most: the recorder owns mutable files; the uploader owns immutable bytes.