kiteml-cli 0.1.0__py3-none-any.whl

kite_cli/cli/commands/rl.py

@@ -0,0 +1,356 @@
+"""`kite rl` — train robot policies in simulation via the public /v1/rl_runs API: a task spec in, one run per seed,
+and a bundle out (the policy as ONNX and a checkpoint, the MuJoCo scene with a script that plays it, clips, and a
+report with a verdict).
+
+  kite rl catalog                                   robots, objectives with every parameter, hardware, budgets
+  kite rl plan     open_duck_mini_v2 "walk forward briskly" -o walk.json     English -> SPEC.json; creates nothing
+  kite rl validate walk.json                        free: what each reward term pays canned policies, and fixes
+  kite rl estimate walk.json                        minutes and tokens
+  kite rl train    walk.json [--seeds 3] [--budget probe] [--wait]            one run per seed (rlr_...)
+  kite rl list     [--limit 20] [--after rlr_...] [--group-id rlg_...]
+  kite rl status   rlr_...  [--wait]
+  kite rl metrics  rlr_...                          the training curve, every 5 iterations
+  kite rl report   rlr_...                          the verdict, its checks and metrics
+  kite rl files    rlr_...                          every file in the bundle (path, bytes, sha256)
+  kite rl download rlr_...  [-o DIR]                the bundle, unpacked to DIR/kiteml_<run_id>/
+  kite rl checkpoints rlr_...                       the iterations it saved
+  kite rl checkpoint  rlr_... 1200 [--format onnx|pt] [-o FILE]
+  kite rl cancel   rlr_...                          a run that trained keeps (and packages) its policy
+  kite rl fork     rlr_...  [--set sigma_lin=0.02 ...] [--seeds N]            its weights and schedule, new reward parameters
+  kite rl continue rlr_...  [--iterations N]        the same, also keeping its optimizer
+
+SPEC.json is a POST /v1/rl_runs body, {"robot", "task", "budget", ...}; `kite rl plan -o` writes one.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import uuid
+import zipfile
+from pathlib import Path, PurePosixPath
+from typing import List, Optional
+
+import httpx
+import typer
+
+from kite_cli.client import KiteAPIError, KiteClient, post_create
+from kite_cli.output import print_error, print_json
+from kite_cli.progress import wait_for_completion
+
+app = typer.Typer(no_args_is_help=True, help="RL training in simulation: a task spec -> a trained, verified policy")
+
+_TERMINAL = {"succeeded", "failed", "canceled"}
+_POLL_S = 30.0
+_SLOW_S = 180.0  # plan asks a model, validate rolls policies through the spec, create starts one job per seed
+_SPEC = typer.Argument(..., help="A create body (JSON), e.g. from `kite rl plan -o`")
+_RUN_ID = typer.Argument(..., help="Run id (rlr_...)")
+_KEY = typer.Option(None, "--idempotency-key", help="Safe retries: same key + body -> the same runs "
+                                                    "(default: a generated key)")
+
+
+@app.command()
+def catalog():
+    """Robots (with their verified command bands), objectives with every parameter's default and bounds, hardware
+    tiers and budget presets."""
+    try:
+        print_json(KiteClient().get("/v1/rl_runs/catalog"))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def plan(
+    robot: str = typer.Argument(..., help="Robot id, e.g. open_duck_mini_v2 (see `kite rl catalog`)"),
+    prompt: str = typer.Argument(..., help="The behavior, in plain words"),
+    out: Optional[Path] = typer.Option(None, "-o", "--out", help="Write the plan as a create body (SPEC.json)"),
+):
+    """A task spec from a plain-English description, with the reasoning behind it. Creates nothing."""
+    try:
+        planned = KiteClient(timeout=_SLOW_S).post("/v1/rl_runs/plan", json_data={"robot": robot, "prompt": prompt})
+        if out is None:
+            print_json(planned)
+            return
+        out.write_text(json.dumps({k: planned[k] for k in ("robot", "task", "budget")}, indent=2) + "\n")
+        print_json({"ok": True, "data": planned, "spec": str(out.resolve())})
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def validate(spec: Path = _SPEC):
+    """Free, in seconds: the spec compiled and rolled with canned policies (zero action, random, a verified policy
+    for this robot), what each reward term pays them, and warnings for rewards that pay for the wrong thing, each
+    with a `patch` for the spec."""
+    body = _read(spec)
+    try:
+        print_json(KiteClient(timeout=_SLOW_S).post("/v1/rl_runs/validate", json_data=body))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def estimate(spec: Path = _SPEC):
+    """Minutes and tokens per run; tokens are reserved at train and what training does not use is refunded."""
+    body = _read(spec)
+    try:
+        print_json(KiteClient().post("/v1/rl_runs/estimate", json_data=body))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def train(
+    spec: Path = _SPEC,
+    seeds: Optional[int] = typer.Option(None, "--seeds", help="Runs to start, one per seed (1-5)"),
+    budget: Optional[str] = typer.Option(
+        None, "--budget", help="probe (300 iterations, a first signal in minutes) or standard; replaces the "
+                               "spec's budget.iterations"
+    ),
+    wait: bool = typer.Option(False, "--wait", help="Poll every run until succeeded | failed | canceled"),
+    idempotency_key: Optional[str] = _KEY,
+):
+    """Train a policy: one queued run per seed, sharing a group_id. Tokens are reserved now and settled by the minute
+    when each run ends."""
+    body = _read(spec)
+    if seeds is not None:
+        body["seeds"] = seeds
+    if budget:  # iterations would override the preset
+        body["budget"] = {**{k: v for k, v in (body.get("budget") or {}).items() if k != "iterations"}, "preset": budget}
+    _start(body, idempotency_key, wait)
+
+
+@app.command("list")
+def list_runs(
+    limit: int = typer.Option(20, "--limit", help="Max rows (1-100)"),
+    after: Optional[str] = typer.Option(None, "--after", help="Cursor: the previous page's next_cursor"),
+    group_id: Optional[str] = typer.Option(None, "--group-id", help="Only the runs one train started (rlg_...)"),
+):
+    """List your runs (newest first, last status seen; `status` has live progress)."""
+    params = {k: v for k, v in (("limit", limit), ("after", after), ("group_id", group_id)) if v}
+    try:
+        print_json(KiteClient().get("/v1/rl_runs", params=params))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def status(
+    run_id: str = _RUN_ID,
+    wait: bool = typer.Option(False, "--wait", help="Poll until succeeded | failed | canceled"),
+):
+    """A run's live status, phase, progress and metrics; once packaged, its verdict and `output`."""
+    try:
+        client = KiteClient()
+        path = f"/v1/rl_runs/{run_id}"
+        if wait:
+            print_json(wait_for_completion(client, path, terminal_states=_TERMINAL, poll_interval=_POLL_S))
+        else:
+            print_json(client.get(path))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def metrics(run_id: str = _RUN_ID):
+    """The training curve, every 5 iterations: mean reward per step, the same by reward term, episode length and
+    throughput."""
+    try:
+        print_json(KiteClient().get(f"/v1/rl_runs/{run_id}/metrics"))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def report(run_id: str = _RUN_ID):
+    """The verdict and how it was reached: each check with its value and limit, the metrics, the judge's read of the
+    clip, and the checkpoint chosen. run_not_ready until the run is packaged."""
+    try:
+        print_json(KiteClient().get(f"/v1/rl_runs/{run_id}/report"))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def files(run_id: str = _RUN_ID):
+    """Every file in a packaged run's bundle (path, bytes, sha256), sorted by path, following the cursor."""
+    path, params = f"/v1/rl_runs/{run_id}/files", {"limit": 100}
+    try:
+        client = KiteClient()
+        data: list = []
+        while True:
+            page = client.get(path, params=params)
+            data.extend(page.get("data") or [])
+            if not page.get("has_more") or not page.get("next_cursor"):
+                break
+            params = {"limit": 100, "after": page["next_cursor"]}
+        print_json({"object": "list", "data": data, "has_more": False, "next_cursor": None})
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def download(
+    run_id: str = _RUN_ID,
+    out: Path = typer.Option(Path("."), "-o", "--out", help="Directory; the bundle unpacks to <out>/kiteml_<run_id>/"),
+):
+    """Download a packaged run's bundle and unpack it: <out>/kiteml_<run_id>/ with media/, policy/, mujoco/ and
+    training/."""
+    try:
+        print_json({"id": run_id, "path": str(_unzip(KiteClient(timeout=120), run_id, out.expanduser().resolve()))})
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def checkpoints(run_id: str = _RUN_ID):
+    """The iterations the run saved (about every tenth of its budget, and the last)."""
+    try:
+        print_json(KiteClient().get(f"/v1/rl_runs/{run_id}/checkpoints"))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def checkpoint(
+    run_id: str = _RUN_ID,
+    iteration: int = typer.Argument(..., help="A saved iteration (see `kite rl checkpoints`)"),
+    fmt: str = typer.Option("onnx", "--format", help="onnx (the deployable policy: raw observation in, action out) "
+                                                     "or pt (the training checkpoint)"),
+    out: Optional[Path] = typer.Option(None, "-o", "--out", help="File to write (default ./<run_id>_<iteration>.<format>)"),
+):
+    """Download one saved iteration of a run's policy."""
+    dest = (out or Path(f"{run_id}_{iteration}.{fmt}")).expanduser().resolve()
+    try:
+        KiteClient(timeout=120).download(f"/v1/rl_runs/{run_id}/checkpoints/{iteration}/download?format={fmt}", str(dest))
+        print_json({"id": run_id, "iteration": iteration, "format": fmt, "path": str(dest)})
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def cancel(run_id: str = _RUN_ID):
+    """Stop a run. One that has started training keeps its policy so far: it reads canceling while that is packaged,
+    then canceled with its outputs, charged for the minutes it trained. One that never started, or left nothing to
+    package, is refunded in full."""
+    try:
+        print_json(KiteClient().post(f"/v1/rl_runs/{run_id}/cancel"))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def fork(
+    run_id: str = _RUN_ID,
+    overrides: List[str] = typer.Option([], "--set", help="key=value: a reward or randomization parameter "
+                                                          "(repeatable; `kite rl catalog` lists them)"),
+    seeds: Optional[int] = typer.Option(None, "--seeds", help="Runs to start, one per seed (1-5)"),
+    idempotency_key: Optional[str] = _KEY,
+):
+    """Train from a run's weights: its robot, task and budget, with the parameters you --set."""
+    params = _params(overrides)
+    try:
+        body = from_run(KiteClient().get(f"/v1/rl_runs/{run_id}"), "fork", params=params)
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+        return
+    if seeds is not None:
+        body["seeds"] = seeds
+    _start(body, idempotency_key)
+
+
+@app.command("continue")
+def continue_run(
+    run_id: str = _RUN_ID,
+    iterations: Optional[int] = typer.Option(None, "--iterations", help="Iterations to train this time "
+                                                                        "(default: the run's own budget)"),
+    idempotency_key: Optional[str] = _KEY,
+):
+    """Keep training a run: its weights, schedule and optimizer, with its robot, task and budget."""
+    try:
+        body = from_run(KiteClient().get(f"/v1/rl_runs/{run_id}"), "continue", iterations=iterations)
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+        return
+    _start(body, idempotency_key)
+
+
+def from_run(run: dict, mode: str, params: Optional[dict] = None, iterations: Optional[int] = None) -> dict:
+    """A create body that starts from `run` (GET /v1/rl_runs/{id}): its robot, task, budget and description (what
+    the report's judge compares the clip against), with `params` overriding task.params and `iterations` the
+    budget's. Both resume its training schedule from its weights; `continue` also keeps its optimizer. Shared
+    with the MCP tool kite_rl_fork."""
+    task = {**run["task"], "params": {**(run["task"].get("params") or {}), **(params or {})}}
+    budget = {**(run.get("budget") or {}), **({"iterations": iterations} if iterations else {})}
+    body = {"robot": run["robot"], "task": task, "budget": budget, "from": {"run": run["id"], "mode": mode}}
+    if run.get("description"):
+        body["description"] = run["description"]
+    return body
+
+
+def _start(body: dict, key: Optional[str], wait: bool = False) -> None:
+    """POST /v1/rl_runs and print the runs it started (each polled until terminal with `wait`)."""
+    key = key or str(uuid.uuid4())
+    try:
+        client = KiteClient(timeout=_SLOW_S)
+        try:
+            page = post_create(client, "/v1/rl_runs", body, key)
+        except (httpx.TimeoutException, httpx.NetworkError) as e:
+            print_error(f"network error ({e}); re-run with --idempotency-key {key} to retry without training twice",
+                        code="network_error", details={"idempotency_key": key})
+            return
+        if wait:
+            page["data"] = [wait_for_completion(client, f"/v1/rl_runs/{r['id']}", terminal_states=_TERMINAL,
+                                                poll_interval=_POLL_S) for r in page.get("data") or []]
+        print_json(page)
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+def _read(spec: Path) -> dict:
+    """SPEC.json: a create body."""
+    try:
+        return json.loads(spec.read_text())
+    except (OSError, ValueError) as e:
+        print_error(f"could not read {spec}: {e}", code="invalid_spec")
+
+
+def _params(overrides: List[str]) -> dict:
+    """--set key=value, repeated -> task.params (every parameter is a number)."""
+    out = {}
+    for kv in overrides:
+        key, _, value = kv.partition("=")
+        try:
+            number = float(value)
+        except ValueError:
+            number = None
+        if not key or number is None:
+            raise typer.BadParameter(f"--set expects key=number, got '{kv}'")
+        out[key] = number
+    return out
+
+
+def _unzip(client: KiteClient, run_id: str, out: Path) -> Path:
+    """Fetch the run's archive (one zip, unpacking to kiteml_<run_id>/), check it against the run's sha256 and
+    unpack it into `out`; keeps no zip. A mismatch, or a file outside kiteml_<run_id>/, refuses the whole archive."""
+    if not re.fullmatch(r"[A-Za-z0-9_-]+", run_id):
+        raise KiteAPIError(400, f"unexpected run id {run_id!r}", code="parameter_invalid")
+    expected = str((client.get(f"/v1/rl_runs/{run_id}").get("output") or {}).get("sha256") or "").lower()
+    out.mkdir(parents=True, exist_ok=True)
+    part = out / f"{run_id}.zip.part"
+    try:
+        client.download(f"/v1/rl_runs/{run_id}/archive", str(part))
+        if expected and hashlib.sha256(part.read_bytes()).hexdigest() != expected:
+            raise KiteAPIError(502, f"{run_id}.zip does not match its sha256; download it again",
+                               code="archive_invalid")
+        with zipfile.ZipFile(part) as z:
+            top = {PurePosixPath(n).parts[0] for n in z.namelist()}
+            if top not in ({f"kiteml_{run_id}"}, {run_id}):     # <run_id>/: runs packaged before the kiteml_ name
+                raise KiteAPIError(502, f"{run_id}.zip holds files outside kiteml_{run_id}/", code="archive_invalid")
+            z.extractall(out)
+    except zipfile.BadZipFile as e:
+        raise KiteAPIError(502, f"{run_id}.zip: {e}", code="archive_invalid") from e
+    finally:
+        part.unlink(missing_ok=True)
+    return out / top.pop()

kite_cli/cli/commands/twin.py

@@ -0,0 +1,322 @@
+"""`kite twin` — digital twins via the public /v1/twins API: one robot episode in, an interactable
+MuJoCo scene out (about 100 minutes per twin).
+
+  kite twin validate lerobot/svla_so101_pickplace [--camera side]    free: cameras, episodes, time estimate
+  kite twin create   lerobot/svla_so101_pickplace --wait --out ./twins    -> ./twins/twin_.../scene.xml
+  kite twin status   twin_01K...   [--wait]
+  kite twin list     [--limit 20] [--after twin_...]
+  kite twin files    twin_01K...   [--limit 20] [--after PATH] [--all]    what the archive holds, once succeeded
+  kite twin cancel   twin_01K...   -> canceling, then canceled once the build has stopped
+  kite twin resume   twin_01K...
+  kite twin download twin_01K...   [--out DIR] [--no-extract]
+
+DATASET is a Hugging Face repo id; the API takes it as {"source": {"type": "huggingface", "repo_id": DATASET}}.
+Where twins go: --out DIR, else $KITE_TWINS_DIR, else ./twins (`~` works). Paths printed are absolute.
+
+A signed storage URL is fetched with a plain HTTP client, never with the Kite key; the API's own archive
+route (download.requires_auth) goes through KiteClient. Every archive is sha256-verified before it is kept,
+and unpacked only inside <out>/<twin_id>/.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import tarfile
+import uuid
+from pathlib import Path, PurePosixPath
+from typing import Optional
+
+import httpx
+import typer
+
+from kite_cli.client import KiteAPIError, KiteClient, post_create
+from kite_cli.output import print_error, print_json
+from kite_cli.progress import wait_for_completion
+
+app = typer.Typer(no_args_is_help=True, help="Digital twins: one robot episode -> an interactable MuJoCo scene")
+
+_TERMINAL = {"succeeded", "failed", "canceled"}  # not canceling: the cancel was accepted, the build has not stopped
+_POLL_S = 30.0
+_SLOW_S = 180.0  # validate/create check the dataset server-side (the API allows the builder 120 s)
+_DATA_FILTER = hasattr(tarfile, "data_filter")  # Python >= 3.10.12 / 3.11.4 / 3.12
+
+
+@app.command()
+def validate(
+    dataset: str = typer.Argument(..., help="Hugging Face dataset id or URL, e.g. lerobot/svla_so101_pickplace"),
+    camera: Optional[str] = typer.Option(None, "--camera", help="Substring of the camera that seeds the room"),
+    wrist_camera: Optional[str] = typer.Option(None, "--wrist-camera", help="Substring of the wrist camera"),
+):
+    """Free dry run of a create: cameras, episodes, fps, and a time estimate. Creates nothing."""
+    try:
+        client = KiteClient(timeout=_SLOW_S)
+        body = _body(source=_source(dataset), camera=camera, wrist_camera=wrist_camera)
+        print_json(client.post("/v1/twins/validate", json_data=body))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def create(
+    dataset: str = typer.Argument(..., help="Hugging Face dataset id or URL, e.g. lerobot/svla_so101_pickplace"),
+    name: Optional[str] = typer.Option(None, "--name", help="A short name for the twin"),
+    task: Optional[str] = typer.Option(None, "--task", help="Which objects to author: the ones the robot manipulates"),
+    prompt: Optional[str] = typer.Option(None, "--prompt", help="How to describe the room to the reconstructor"),
+    camera: Optional[str] = typer.Option(None, "--camera", help="Substring of the camera that seeds the room"),
+    wrist_camera: Optional[str] = typer.Option(None, "--wrist-camera", help="Substring of the wrist camera"),
+    ceiling_m: Optional[float] = typer.Option(
+        None, "--ceiling-m", help="Floor-to-ceiling height in m, the scale anchor (default 2.90)"
+    ),
+    idempotency_key: Optional[str] = typer.Option(
+        None, "--idempotency-key", help="Safe retries: same key + body -> same twin (default: a generated key)"
+    ),
+    wait: bool = typer.Option(False, "--wait", help="Poll until succeeded | failed | canceled (about 100 min)"),
+    out: Optional[Path] = typer.Option(
+        None, "-o", "--out", help="When it succeeds, download, verify and unpack the scene into DIR (implies --wait); "
+                                  "default location for `kite twin download` is $KITE_TWINS_DIR, else ./twins"
+    ),
+):
+    """Build a twin from one episode of a LeRobot dataset (queued; about 100 minutes)."""
+    key = idempotency_key or str(uuid.uuid4())
+    body = _body(source=_source(dataset), name=name, task=task, prompt=prompt, camera=camera,
+                 wrist_camera=wrist_camera, ceiling_m=ceiling_m)
+    try:
+        client = KiteClient(timeout=_SLOW_S)
+        try:
+            twin = post_create(client, "/v1/twins", body, key)
+        except (httpx.TimeoutException, httpx.NetworkError) as e:
+            print_error(f"network error ({e}); re-run with --idempotency-key {key} to retry without building twice",
+                        code="network_error", details={"idempotency_key": key})
+            return
+        if (wait or out) and twin.get("id"):
+            twin = wait_for_completion(
+                client, f"/v1/twins/{twin['id']}", terminal_states=_TERMINAL, poll_interval=_POLL_S
+            )
+        if out is None:
+            print_json(twin)
+        elif twin.get("status") != "succeeded":
+            print_json(twin, success=False)
+            raise typer.Exit(1)
+        else:
+            saved = _save(client, twin, _out_dir(out), extract=True)
+            print_json({"ok": True, "data": twin, "scene": saved["scene"], "archive": saved["archive"]})
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def status(
+    twin_id: str = typer.Argument(..., help="Twin id (twin_...)"),
+    wait: bool = typer.Option(False, "--wait", help="Poll until succeeded | failed | canceled"),
+):
+    """A twin's live status, progress, stage and stage measurements; `download` once succeeded."""
+    try:
+        client = KiteClient()
+        path = f"/v1/twins/{twin_id}"
+        if wait:
+            print_json(wait_for_completion(client, path, terminal_states=_TERMINAL, poll_interval=_POLL_S))
+        else:
+            print_json(client.get(path))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command("list")
+def list_twins(
+    limit: int = typer.Option(20, "--limit", help="Max rows (1-100)"),
+    after: Optional[str] = typer.Option(None, "--after", help="Cursor: the previous page's next_cursor"),
+):
+    """List your twins (newest first, last status seen; `status` has live progress)."""
+    params: dict = {"limit": limit}
+    if after:
+        params["after"] = after
+    try:
+        print_json(KiteClient().get("/v1/twins", params=params))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command("files")
+def list_files(
+    twin_id: str = typer.Argument(..., help="Twin id (twin_...)"),
+    limit: Optional[int] = typer.Option(None, "--limit", help="Files per page, 1-100 (default 20; 100 with --all)"),
+    after: Optional[str] = typer.Option(None, "--after", help="Cursor: the previous page's next_cursor (a file path)"),
+    all_pages: bool = typer.Option(False, "--all", help="Follow next_cursor through every page; print one list"),
+):
+    """The files in a succeeded twin's archive (path, bytes, sha256), sorted by path; twin_not_ready before that."""
+    path = f"/v1/twins/{twin_id}/files"
+    size = limit if limit is not None else (100 if all_pages else 20)
+    try:
+        client = KiteClient()
+        if not all_pages:
+            print_json(client.get(path, params=_page(size, after)))
+            return
+        data: list = []
+        while True:
+            page = client.get(path, params=_page(size, after))
+            items = page.get("data") or []
+            data.extend(items)
+            after = page.get("next_cursor") or (items[-1].get("path") if items else None)
+            if not page.get("has_more") or not after:
+                break
+        print_json({"object": "list", "data": data, "has_more": False, "next_cursor": None})
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def cancel(twin_id: str = typer.Argument(..., help="Twin id (twin_...)")):
+    """Stop a queued or processing twin: it reads canceling until the build has stopped, then canceled. The
+    stages it finished stay cached for a resume."""
+    try:
+        print_json(KiteClient().post(f"/v1/twins/{twin_id}/cancel"))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def resume(twin_id: str = typer.Argument(..., help="Twin id (twin_...)")):
+    """Re-queue a failed or canceled twin; only the stages that did not finish run again."""
+    try:
+        print_json(KiteClient().post(f"/v1/twins/{twin_id}/resume"))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+@app.command()
+def download(
+    twin_id: str = typer.Argument(..., help="Twin id (twin_...)"),
+    out: Optional[Path] = typer.Option(None, "-o", "--out", help="Output directory (default: $KITE_TWINS_DIR, else ./twins)"),
+    extract: bool = typer.Option(
+        True, "--extract/--no-extract", help="Unpack into <out>/<twin_id>/, or keep only the .tar.gz"
+    ),
+):
+    """Download a succeeded twin: <out>/<twin_id>.tar.gz, sha256-verified, unpacked to <out>/<twin_id>/scene.xml."""
+    try:
+        client = KiteClient(timeout=120)
+        print_json(_save(client, client.get(f"/v1/twins/{twin_id}"), _out_dir(out), extract=extract))
+    except KiteAPIError as e:
+        print_error(e.message, code=e.code, details=e.details)
+
+
+def _body(**fields) -> dict:
+    return {k: v for k, v in fields.items() if v not in (None, "")}
+
+
+def _source(dataset: str) -> dict:
+    """The positional DATASET as the API takes it: the `source` object /v1/augmentations takes too."""
+    return {"type": "huggingface", "repo_id": dataset}
+
+
+def _page(limit: int, after: Optional[str]) -> dict:
+    return {"limit": limit, "after": after} if after else {"limit": limit}
+
+
+def _out_dir(out: Optional[Path]) -> Path:
+    """--out, else $KITE_TWINS_DIR, else ./twins; absolute, so what is printed says exactly where the twin is."""
+    return Path(out or os.environ.get("KITE_TWINS_DIR") or "./twins").expanduser().resolve()
+
+
+def _save(client: KiteClient, twin: dict, out: Path, *, extract: bool) -> dict:
+    """Fetch a succeeded twin's archive to <out>/<twin_id>.tar.gz, verify its sha256, and (extract) unpack it
+    into <out>/<twin_id>/. An archive already there that still verifies is reused."""
+    tid, d = str(twin.get("id") or ""), twin.get("download")
+    if twin.get("status") != "succeeded" or not d:
+        raise KiteAPIError(409, f"Twin '{tid}' is {twin.get('status')}, not succeeded.", code="twin_not_ready")
+    if not re.fullmatch(r"[A-Za-z0-9_-]+", tid):
+        raise KiteAPIError(502, f"unexpected twin id {tid!r}", code="archive_invalid")
+    expected = str(d.get("sha256") or "").lower()
+    if not expected:
+        raise KiteAPIError(502, f"Twin '{tid}' has no download.sha256 to verify against.", code="checksum_missing")
+    out.mkdir(parents=True, exist_ok=True)
+    archive = out / f"{tid}.tar.gz"
+    if not (archive.is_file() and _sha256(archive) == expected):
+        part = out / f"{tid}.tar.gz.part"
+        try:
+            _fetch(client, d, part)
+            got = _sha256(part)
+            if got != expected:
+                raise KiteAPIError(502, f"{archive.name}: sha256 {got} != expected {expected}; the file was discarded, "
+                                        f"retry the download", code="checksum_mismatch",
+                                   details={"expected": expected, "actual": got, "bytes": part.stat().st_size})
+            part.replace(archive)
+        finally:
+            part.unlink(missing_ok=True)
+    saved = {"id": tid, "archive": str(archive), "bytes": archive.stat().st_size, "sha256": expected}
+    if extract:
+        scene = _relpath(d.get("scene") or f"{tid}/scene.xml")
+        _unpack(archive, out, top=tid)
+        if not (out / scene).is_file():
+            raise KiteAPIError(502, f"{archive.name} has no {scene.as_posix()}", code="archive_invalid")
+        saved["scene"] = str(out / scene)
+    return saved
+
+
+def _fetch(client: KiteClient, d: dict, dest: Path) -> None:
+    """Stream the archive to `dest`. The Kite key goes to the Kite API only: the archive route through
+    KiteClient, a signed storage URL through a plain client that has no key to send."""
+    url = str(d.get("url") or "")
+    if not url:
+        raise KiteAPIError(502, "the twin has no download.url", code="download_failed")
+    u = httpx.URL(url)
+    if u.is_relative_url or _origin(u) == _origin(httpx.URL(client.base_url)):
+        client.download(url, str(dest))
+        return
+    if d.get("requires_auth"):
+        raise KiteAPIError(502, f"download.url is on {u.host}, not the Kite API; refusing to send it the Kite key",
+                           code="download_failed")
+    with _storage_client() as http, http.stream("GET", url, headers={"Accept-Encoding": "identity"}) as r:
+        if not r.is_success:
+            r.read()
+            raise KiteAPIError(r.status_code, f"GET {u.host} answered HTTP {r.status_code}: {r.text[:200]}",
+                               code="download_failed")
+        with open(dest, "wb") as f:
+            for chunk in r.iter_bytes(1 << 20):
+                f.write(chunk)
+
+
+def _storage_client() -> httpx.Client:
+    """A plain client for signed storage URLs: it has no Kite credentials to send."""
+    return httpx.Client(timeout=httpx.Timeout(120.0, connect=30.0), follow_redirects=True)
+
+
+def _origin(u: httpx.URL) -> tuple:
+    return u.scheme, u.host, u.port or {"https": 443, "http": 80}.get(u.scheme)
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _relpath(p: str) -> Path:
+    rel = PurePosixPath(p)
+    if rel.is_absolute() or ".." in rel.parts or not rel.parts:
+        raise KiteAPIError(502, f"unsafe path in download.scene: {p!r}", code="archive_invalid")
+    return Path(*rel.parts)
+
+
+def _unpack(archive: Path, dest: Path, *, top: str) -> None:
+    """Extract into `dest`. Every member must sit under `<top>/` (the twin id), with no absolute path or `..`.
+    Python's tarfile "data" filter, where present, also refuses links out of `dest` and device files; without
+    it (Python < 3.10.12), links and special files are refused outright."""
+    with tarfile.open(archive, "r:gz") as tar:
+        members = tar.getmembers()
+        for m in members:
+            parts = PurePosixPath(m.name).parts
+            if (parts and parts[0] != top) or ".." in parts or not (_DATA_FILTER or m.isfile() or m.isdir()):
+                raise KiteAPIError(502, f"{archive.name}: refusing to extract {m.name!r}", code="archive_invalid")
+        try:
+            if _DATA_FILTER:
+                tar.extractall(dest, members=members, filter="data")
+            else:
+                for m in members:
+                    m.mode = 0o755 if m.isdir() else (m.mode | 0o600) & 0o755
+                tar.extractall(dest, members=members)
+        except tarfile.TarError as e:  # includes the data filter's refusals
+            raise KiteAPIError(502, f"{archive.name}: {e}", code="archive_invalid") from e