Metadata-Version: 2.4
Name: qualia-sdk
Version: 0.8.0rc13
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Dist: httpx[http2]>=0.25.0,<1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0
Summary: Python SDK for Qualia robot data curation: upload, curate, version and export datasets
Keywords: qualia,robotics,datasets,data-curation,lerobot,mcap
Author: Qualia Studios
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://docs.qualiastudios.dev
Project-URL: Homepage, https://qualiastudios.dev

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

**Status:** beta pre-release (0.8.0rc13) · **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

<!-- pre-release until the first stable release on prod; drop --pre then -->

```sh
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.0rc13'`. `client.preparation`
first shipped in 0.8.0rc12; 0.8.0rc11 raises `AttributeError`.

## 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.

```python
from qualia import Qualia

client = Qualia()

dataset = client.data.upload("./takes", "box-pick")["dataset_id"]
print(client.preparation.get(dataset).state)  # 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](docs/api-guide.md#data) 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](docs/api-guide.md#data) 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](../../docs/operations/qds-service.md)).

`client.datasets.setup()` takes no solver: a dataset follows its robot's solver, set on
the robot's Solver page ([setting a dataset up](docs/api-guide.md#080rc6-set-a-handheld-dataset-up-from-a-script)).

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.

## API

- [SDK docs: every resource, with examples](https://docs.qualiastudios.dev/sdk/overview/)

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

- [API guide, examples and release history](docs/api-guide.md)
- [Upload preparation: what prepare found, and confirming task names](docs/api-guide.md#preparation-qualiav1) (`client.preparation`)
- [Episode drafts and version publication](docs/version-publication.md)
- [Server contracts and operations](../../docs/qds/api-reference.md)

## License

MIT

