SDK mental model

The SDK is deliberately small at the top level:

async with sx.connect(project_id) as client:
    client.experience
    client.worlds
    client.autonomy
    client.fleet

One explicit project

Every client is bound to exactly one project. The project is the authorization and product boundary for one robotics application—not ambient global state.

async with sx.connect(project_id) as client:
    ...

For non-interactive workloads, provide a project-scoped key explicitly:

async with sx.connect(project_id, api_key=os.environ["SX_API_KEY"]) as client:
    ...

Values for facts, references for boundaries

Reads return complete domain values. Cross-process handoffs and lineage use exact references. Mutations that may outlive the caller return Operation[Result, Progress].

task = await client.experience.task(task_ref)       # TaskContract
application = await client.autonomy.application(application_ref)  # RobotApplication
operation = await client.worlds.evaluate(application, for_task=task)

Do not rebuild platform objects from loose dictionaries when the SDK already returns the canonical value. Do not pass display names where a content identity is required.

Four doors

Door	Reads and builds	Durable work
`experience`	tasks, embodiments, atlas, semantic search, dataset queries	capture
`worlds`	interactive sessions	generation and evaluation
`autonomy`	applications and approvals	training, deployment programs, improvement
`fleet`	deployment authority	rollout, rollback, supervised physical research

One operation model

operation = await client.worlds.evaluate(application, for_task=task)
print(operation.ref)

async for receipt in operation.watch():
    print(receipt.state, receipt.cursor)

result = await operation.result()

You can reattach in a later process:

async with sx.connect(project_id) as client:
    operation = client.operation("worlds/evaluation/01J...")
    status = await operation.status()
    result = await operation.result()

See durable operations and errors for cancellation, history gaps, and failure handling.

The client is asynchronous because capture, generation, training, evaluation, deployment, and research are networked operations. Use one client context across related calls so the transport and project authority stay coherent.

async def build_evidence(project_id, task_ref, application_ref):
    async with sx.connect(project_id) as client:
        task = await client.experience.task(task_ref)
        application = await client.autonomy.application(application_ref)
        evaluation = await (
            await client.worlds.evaluate(application, for_task=task, seed=7)
        )
        return evaluation

Keep the exact value moving

Pass the task, application, snapshot, evaluation, qualification, and approval values returned by the previous step. Their identities make the next gate reproducible and auditable.

Surface equivalence

The MCP tools use the same domain verbs as Python. The Console renders the same resources. Choose a different surface for ergonomics—not to bypass a gate or invent a second workflow.