Experience SDK

Experience owns what the work means and the evidence robots produced. Use it to resolve exact tasks and embodiments, gather data, search the governed corpus, and freeze inputs before compute.

Resolve governed inputs

async with sx.connect(project_id) as client:
    task = await client.experience.task("task:pick-mug@production")
    embodiment = await client.embodiment.get("piper")

The returned values are complete, validated domain objects. Carry them into later calls rather than reconstructing the same facts from names or local files.

Capture robot experience

async with sx.connect(project_id) as client:
    task = await client.experience.task(task_ref)
    embodiment = await client.embodiment.get("piper")

    capture = await client.experience.capture(
        task,
        with_embodiment=embodiment,
        episodes=100,
    )
    print(capture.ref)

    receipt = await capture

The operation persists independently of your process. Its terminal receipt identifies the exact capture session; downstream registration preserves task, embodiment, action-interface, and source lineage.

Search without freezing too early

Use the atlas for corpus shape and semantic search for discovery:

overview = await client.experience.atlas()
matches = await client.experience.search_frames(
    {
        "query": {
            "kind": "text",
            "text": "gripper closes around the mug handle",
        },
        "filters": {},
        "limit": 50,
    }
)

Search results are exploratory. They are not a reproducible training input until you freeze exact membership.

Freeze a training snapshot

task = await client.experience.task(task_ref)

snapshot = await (
    client.experience
    .dataset("captures.piper")
    .where(task=task)
    .snapshot()
)

print(snapshot)

DatasetQuery is immutable and performs no I/O until snapshot() is awaited. A snapshot binds the dataset selection to one exact task revision so a training run can be reproduced later.

A snapshot is ready when

Every member resolves to canonical episode evidence with its exact task, embodiment, action interface, and lineage—and the membership itself is immutable.

Embodiment workflows

parts = await client.embodiment.parts()
readiness = await client.embodiment.readiness()
scorecard = await client.embodiment.admissibility()
frontier = await client.embodiment.frontier()

Use validate(...) to dry-run a composed definition before register(...). Validation refusals name the incompatible part, contract, or URDF fact; they do not mint a partial body.

Use the right surface

Use Python for capture programs, data selection, repeatable snapshot creation, and integration with training pipelines.

Preserve evidence

Raw robot data is immutable. Processing creates a new derived artifact; an export or local array is never a second source of truth.