qualia-sdk — Python client for Qualia robot data: upload, curate, version, export

Status: beta pre-release (0.8.0rc14) · Published: qualia-sdk wheels for Python 3.10+

Qualia keeps robot recordings (MCAP or LeRobot) as datasets of episodes. From Python you upload a folder of takes and read what preparation found in it. You link the episodes to a Task (what the robot was asked to do), run checks that flag failed or broken takes, and keep or reject each take. The kept takes become an immutable version, which downloads as LeRobot v3 or v2.1, ROS 2 MCAP or a partner layout. The upload engine is compiled into the wheel, so there is nothing else to install. The qualia command line is the separate qualia-cli package.

Install

pip install --pre qualia-sdk

The client and the deployment it talks to negotiate the upload protocol exactly, so pin the version your deployment's docs name, for example pip install 'qualia-sdk==0.8.0rc14'. client.preparation first shipped in 0.8.0rc12; 0.8.0rc11 raises AttributeError. client.preparation.wait first shipped in 0.8.0rc14.

Usage

Set QUALIA_API_KEY (and QUALIA_BASE_URL for a deployment other than the default), or log in once with qualia auth login. An API key names its account, so no account setting is needed.

from qualia import Qualia

client = Qualia()

dataset = client.data.upload("./takes", "box-pick")["dataset_id"]
# Preparation starts by itself. Wait for it to end.
prep = client.preparation.wait(dataset)
print(prep.state, prep.warnings)  # what preparation found

# The VLM check reads each episode against the published Task it is linked to.
task = client.tasks.create(
    "Pick a box", draft={"description": "Move the box from the crate to the table"}
)
task = client.tasks.update(task.id, success="The box stands on the table")
client.tasks.publish(task.id, etag=task.etag)
client.datasets.update(dataset, linked_task=task.id)

estimate = client.checks.estimate(dataset)  # free: nothing is reserved
started = client.checks.run(dataset, max_cost=estimate.credits)
client.checks.wait(started.check_runs[0])  # a VLM check starts one run
for issue in client.checks.findings(dataset).items:
    print(issue.text)

client.episodes.reject(dataset, ["<episode-id>"], reason="the box slipped")
client.episodes.keep(dataset, filter="state = UNREVIEWED")
client.versions.create(dataset, "1.0")  # the takes a person kept
client.data.download(f"{dataset}:1.0", "./box-pick-1.0", format="lerobot_v2_1")

An API key names its account automatically. Set an account override only when needed; the API guide describes the server requirement and release history. An account= (or QUALIA_ACCOUNT) that is not an account UUID is refused with a ValueError; leave it unset to use the key's own account. Publishing a preview (client.versions.create(dataset, tag, preview=...), or qualia dataset pin <dataset> <tag> --preview <preview>) needs no override either: the tag the server answers under the key's account UUID is the one asked for.

client.data.download("<dataset>") with no version takes stable, the newest tag. A fresh upload has no tag yet, so it takes the newest version, v0 (the upload as it arrived), and reports {"step": "newest", "version": "<slug>:v0"} to on_progress. Only a dataset with no version at all is refused. The API guide's Data section has the examples.

A handheld (UMI) recording converts at a UMI rig of its workspace. Make one from a gripper template with client.robots.make_umi_rig(template, name) (or qualia gripper umi-rig), then give it its calibration with client.robots.import_gripper_calibration(rig.name, "tcp_calibration.json"); a workspace may have several. Name the rig with rig= on upload. Without it, an upload into a merged dataset whose uploads agree on one rig takes it, and a tree that declares [rig] kind = "umi-handheld" takes the workspace's one UMI rig: none is refused (404), several are refused asking which (409). client.datasets.resolve_poses(dataset, gripper="<name>") names the rig a resolve uses, and asks which when there are several and none is named. The API guide's Data section has the example.

An upload sends its transfer session id when it begins, so the UMI rig composed for it stays its own. In a workspace with several UMI rigs, an upload from an SDK too old to send it reads as not composed and is refused, so upgrade. Against a gateway that predates the field, the SDK drops it and begins again (QDS service: UMI rigs).

client.datasets.setup() takes no solver: a dataset follows its robot's solver, set on the robot's Solver page (setting a dataset up).

Upgrading from 0.3.6: fine-tuning (client.finetune, client.jobs) is gone, removed in 0.8.0rc11.

Catalog checks

Use client.checks.estimate(dataset, kind="heuristic", categories=["heuristic"]) to see which free checks would run, then client.checks.run(dataset, kind="heuristic", all=True) to start them without a credit ceiling. kind can also be "vlm"; without it the catalog selects runnable heuristics (VLM catalog checks are unavailable here). A run contains only one kind. VLM runs need max_cost covering the estimated bound.

Automatic checks

Free quality checks default on, paid video checks default off. An organization Admin/Owner can set the org default, a workspace Admin/Owner its default, and a dataset writer an override. Each half inherits independently from dataset → workspace → org → platform. Reading returns the effective on/off value and its source. Switching on starts nothing; existing episodes need a manual run.

client.checks.automatic_policy("<ORG_UUID>", org=True)
client.checks.set_automatic_policy("<ORG_UUID>", org=True, graph=False)
client.checks.set_automatic_policy("<WORKSPACE_UUID>", workspace=True, heuristic=False)
client.checks.set_automatic_policy("<DATASET_UUID>", reset=("graph",))

Automatic policy contract and permissions.

API

• SDK docs: every resource, with examples

In the repository (these links do not resolve on PyPI):

• API guide, examples and release history
• Upload preparation: waiting for it, what prepare found, and confirming task names (client.preparation)
• Episode drafts and version publication
• Server contracts and operations

License

MIT