> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hardlightsim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> Python interfaces for submit, wait, cancel, and artifact download.

The Python SDK is the customer-facing entry point for Hardsim.

## Install

```bash theme={null}
pip install hardsim
```

## Core Methods

* `submit(...)`: create a cloud simulation job.
* `submit_assets(...)`: strict real-mode submit using local files, managed URIs, or asset IDs.
* `step(...)`: alias for submit-oriented cloud simulation call.
* `status(job_id)`: get current job state.
* `wait(job_id)`: poll until terminal state.
* `watch_job(job_id)`: stream live terminal-friendly status updates.
* `download(job_id, out_dir)`: download generated artifacts.
* `cancel(job_id)`: cancel queued/running jobs.
* `upload_input(local_path)`: upload local files and return a managed input URI.
* `upload_input_asset(local_path)`: upload local file and return stable `asset_id`.
* `register_input_asset(...)`: register an existing managed input URI into asset catalog.
* `list_input_assets(...)` / `get_input_asset(asset_id)`: query catalog.
* `create_training_run(...)`: create a managed rollout-train run.
* `list_training_runs(limit=..., submission_group_id=...)`: list runs (optional group filter).
* `get_training_run(run_id)` / `wait_training_run(run_id)`: monitor managed run lifecycle.
* `watch_training_run(run_id)`: stream live run status + events.
* `pause_training_run(run_id)` / `resume_training_run(run_id)` / `cancel_training_run(run_id)`.
* `list_run_checkpoints(run_id)` / `get_latest_checkpoint(run_id)`.
* `submit_many_jobs(...)` / `submit_many_training_runs(...)`: batch submit with one group ID.
* `watch_submission_group(group_id)`: live group progress in terminal.

For custom Isaac Lab workloads, use `submit_assets(...)` with:

* `runtime_profile="isaac_lab_rollout"`
* an `isaac_lab={...}` config block
* a task package uploaded as `asset_kind="isaac_lab_task_package"`

## Terminal Monitoring Patterns

You can monitor from terminal in two ways:

1. **Manual status checks anytime**

```python theme={null}
job_state = client.status(job_id)
run_state = client.get_training_run(run_id)
events = client.list_training_events(run_id, limit=20)
```

2. **Live watch stream**

```python theme={null}
# Simulation job
client.watch_job(job_id, poll_interval_s=2.0, timeout_s=36000)

# Managed training run
client.watch_training_run(run_id, poll_interval_s=5.0, timeout_s=24*3600)
```

`timeout_s` is configurable. If you want a full watch, set a large timeout.

Submission group watch:

```python theme={null}
group = client.submit_many_jobs(name="batch-10", jobs=[...])
client.watch_submission_group(group["group_id"], poll_interval_s=2.0, timeout_s=3600)
```

## Environment Variables

* `HARDSIM_API_KEY` (required)
* `HARDSIM_API_URL` (production: `https://api-sim.hardlightsim.com`)
* `HARDSIM_HTTP_TIMEOUT_S`
* `HARDSIM_HTTP_RETRIES`
* `HARDSIM_HTTP_BACKOFF_S`

## Idempotent Submit (Recommended)

```python theme={null}
client = hs.HardsimClient.from_env()
robot_asset_id = client.upload_input_asset("./assets/franka.urdf", asset_kind="robot")
scene_asset_id = client.upload_input_asset("./assets/cabinet_scene.usd", asset_kind="scene")

job = client.submit_assets(
    robot_asset_id=robot_asset_id,
    scene_asset_id=scene_asset_id,
    robot_asset_type="urdf",
    num_envs=64,
    steps=2000,
    control={"task_mode": "fr3_pick_lift_block_v1", "fix_base": True},
    idempotency_key="train-run-42-shard-0001",
)
```

## One-Call Real Asset Submit

```python theme={null}
import hardsim as hs

client = hs.HardsimClient.from_env()
job = client.submit_assets(
    robot_asset="./assets/franka.urdf",      # local path or managed URI
    scene_usd="./assets/cabinet_scene.usd",  # local path or managed URI
    num_envs=64,
    steps=2000,
    scene_id="franka_cabinet_oige_v1",
    control={"task_mode": "fr3_pick_lift_block_v1", "fix_base": True},
)
```

`submit_assets(...)` auto-uploads local files through the presigned upload API and then submits the job with strict real asset references.

## Asset-ID Submit (Recommended For Repeat Workloads)

```python theme={null}
import hardsim as hs

client = hs.HardsimClient.from_env()

robot_asset_id = client.upload_input_asset("./assets/franka.urdf", asset_kind="robot")
scene_asset_id = client.upload_input_asset("./assets/cabinet_scene.usd", asset_kind="scene")

job = client.submit_assets(
    robot_asset_id=robot_asset_id,
    scene_asset_id=scene_asset_id,
    robot_asset_type="urdf",
    num_envs=64,
    steps=2000,
    control={"task_mode": "fr3_pick_lift_block_v1", "fix_base": True},
)
```

## Managed Training

For containerized trainer testing, use the reference image + payload in:

* `managed-training-quickstart`

`create_training_run(...)` also supports `checkpoint_init_asset_id`.

## More Detail

* [Getting Started](./getting-started)
* [API Overview](./api-overview)
* [Isaac Lab Jobs](./isaac-lab-jobs)
* [Artifacts and Diagnostics](./artifacts-and-diagnostics)
* [Managed Training Quickstart](./managed-training-quickstart)