lucen-cli 0.1.0__py3-none-any.whl

lucen/hub.py

@@ -0,0 +1,889 @@
+"""`Hub` — the MouseMouse hub from a Python script, on the CLI's own engine.
+
+Nothing here talks to the hub on its own: every method is one of the CLI's
+functions (`lucen_cli.client.HubClient`, `push.run_push`, `pull.run_pull`,
+the runner's `follow_run` stream, the rollout engine) called with the same
+arguments the command line would pass, so a script and a terminal cannot
+disagree about what a push uploads or what a 404 means. The module adds three
+things a script wants and a terminal does not:
+
+- **credentials resolved the CLI's way, or passed explicitly** —
+  ``Hub()`` reads `LUCEN_API_URL` / `LUCEN_API_KEY`, then
+  `~/.config/lucen/credentials` (the file `lucen auth login` writes, refused
+  when another user can read it); ``Hub(url=…, key=…)`` overrides either. No
+  key is ever read from a file a script wrote or an argument it did not pass;
+- **results as records** (:mod:`lucen.results`): frozen dataclasses with the
+  ids, URLs and counts a script asserts on, `to_dict()` for what
+  `lucen … --json` would have printed, and `raw` for the whole SDK model;
+- **refusals as one exception family** (:mod:`lucen.errors`): the CLI's three
+  lines — what happened, what the hub said, the fix — as attributes, with the
+  subclass chosen by status.
+
+Progress is silent unless asked for: ``Hub(progress=True)`` prints exactly the
+CLI's stderr lines; ``Hub(on_progress=callback)`` hands every milestone, byte
+count and followed log line to a function of yours (:mod:`lucen.progress`).
+"""
+
+from __future__ import annotations
+
+import builtins
+import dataclasses
+import os
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+
+import httpx
+from lucen_sdk.models import OrgRole, RepoKind, Visibility
+
+from lucen.errors import LOGIN_FIX_PYTHON, HubError, HubUnreachable, NotFound, NotSignedIn
+from lucen.errors import from_cli_error as _from_cli_error
+from lucen.progress import CallbackReporter, ProgressCallback, make_reporter
+from lucen.results import (
+    Episode,
+    LogEvent,
+    Me,
+    Member,
+    Org,
+    PullResult,
+    PushResult,
+    Repo,
+    RobotDraft,
+    RobotPublishResult,
+    RobotReport,
+    Rollout,
+    Run,
+    RunEstimate,
+    RunRecommendation,
+)
+from lucen_cli.client import HubClient, RepoTarget, unset_to_none
+from lucen_cli.cmd_hub import page_path
+from lucen_cli.config import (
+    ENV_WEB_URL,
+    NO_HUB_URL_MESSAGE,
+    Credentials,
+    load_cached_web_url,
+    load_credentials,
+    page_url,
+    save_cached_web_url,
+    web_url_for,
+)
+from lucen_cli.errors import CLIError
+from lucen_cli.errors import HubUnreachable as _CLIHubUnreachable
+from lucen_cli.progress import Reporter
+from lucen_cli.pull import run_pull
+from lucen_cli.push import run_push
+from lucen_cli.sim_words import created_line
+
+#: How a script configures the hub's address when nothing else does.
+NO_HUB_URL_FIX_PYTHON = (
+    "Pass Hub(url='https://…'), set LUCEN_API_URL, or store the address once with "
+    "`lucen auth login --url <API URL>`."
+)
+
+#: The sentence `hub.robots` and a local rollout refuse with when MuJoCo is absent.
+ENGINE_FIX = (
+    "Install the rollout extra into this environment: "
+    'uv pip install --index lucen=<hub>/install/simple/ "lucen-cli[rollout]" '
+    '(or, from a checkout: uv pip install ./packages/sdk/py "./packages/cli[rollout]").'
+)
+
+#: `recipe` as a script hands it over: a mapping, or the path of a YAML/JSON file.
+RecipeLike = Mapping[str, Any] | str | os.PathLike[str]
+LogCallback = Callable[[LogEvent], None]
+
+
+def _target(repo: str) -> RepoTarget:
+    try:
+        return RepoTarget.parse(repo)
+    except CLIError as exc:
+        raise _from_cli_error(exc) from exc
+
+
+def _engine_available() -> bool:
+    for module in ("mujoco", "numpy", "defusedxml", "onnxruntime"):
+        try:
+            __import__(module)
+        except ImportError:
+            return False
+    return True
+
+
+def _require_engine(what: str) -> None:
+    """An `ImportError` with the install line, before anything is created on the hub."""
+    if not _engine_available():
+        raise ImportError(
+            f"{what} runs real MuJoCo on this machine, and it is not installed. {ENGINE_FIX}"
+        )
+
+
+def _recipe(recipe: RecipeLike) -> tuple[dict[str, Any], str | None, str | None]:
+    """A mapping, or a file -> `(recipe, owner, parent_run_id)` as `lucen train -f` reads it."""
+    if isinstance(recipe, Mapping):
+        body = dict(recipe)
+        owner = body.pop("owner", None)
+        parent = body.pop("parent_run_id", None)
+        if "template" not in body:
+            raise HubError(
+                "The recipe has no `template`.",
+                fix="Give it one: {'template': 'ppo_mujoco', 'robot': 'you/robot'} "
+                "(or smolvla_lora, ppo_isaac).",
+            )
+        body.setdefault("dataset", [])
+        return body, (str(owner) if owner else None), (str(parent) if parent else None)
+    from lucen_cli.cmd_runs import load_recipe_file
+
+    path = Path(recipe).expanduser()
+    if not path.is_file():
+        raise HubError(
+            f"{path} is not a recipe file.",
+            fix="Pass the recipe as a dict, or the path of a YAML/JSON file that exists.",
+        )
+    try:
+        return load_recipe_file(path)
+    except CLIError as exc:
+        raise _from_cli_error(exc) from exc
+
+
+class Hub:
+    """One hub, one credential, one connection pool. See the module docstring."""
+
+    def __init__(
+        self,
+        url: str | None = None,
+        key: str | None = None,
+        *,
+        progress: bool = False,
+        on_progress: ProgressCallback | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        try:
+            credentials = load_credentials(url.strip() if url else None)
+        except CLIError as exc:
+            if exc.message == NO_HUB_URL_MESSAGE:
+                raise HubError(NO_HUB_URL_MESSAGE, fix=NO_HUB_URL_FIX_PYTHON) from exc
+            raise _from_cli_error(exc) from exc
+        if key:
+            credentials = dataclasses.replace(
+                credentials, api_key=key.strip(), key_source="argument"
+            )
+        self._credentials: Credentials = credentials
+        self._client = HubClient(credentials, timeout=timeout)
+        self._progress = progress
+        self._on_progress = on_progress
+        self.repos = Repos(self)
+        self.runs = Runs(self)
+        self.rollouts = Rollouts(self)
+        self.robots = Robots(self)
+        self.orgs = Orgs(self)
+        self.datasets = Datasets(self)
+
+    # -- plumbing ----------------------------------------------------------
+
+    @property
+    def api_url(self) -> str:
+        return self._credentials.api_url
+
+    @property
+    def signed_in(self) -> bool:
+        """Whether a key is configured (not whether the hub accepts it: that is `me()`)."""
+        return self._credentials.is_authenticated
+
+    @property
+    def web_url(self) -> str | None:
+        """The hub's web app, or None when the hub names none (one `/healthz`, cached)."""
+        return self._client.web_url
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Hub:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        key = self._credentials.key_display if self.signed_in else "none"
+        return f"Hub({self.api_url!r}, key={key})"
+
+    @contextmanager
+    def _calls(self) -> Iterator[None]:
+        """The CLI's exceptions become this module's; a transport error is `HubUnreachable`."""
+        try:
+            yield
+        except CLIError as exc:
+            raise _from_cli_error(exc) from exc
+        except httpx.TransportError as exc:
+            error = _CLIHubUnreachable(self.api_url, exc)
+            raise HubUnreachable(error.message, fix=error.hint) from exc
+
+    def _auth(self) -> HubClient:
+        """The client, for a call that needs a key; `NotSignedIn` when there is none."""
+        if not self.signed_in:
+            raise NotSignedIn(
+                f"Not signed in: this call needs an API key, and none is configured for "
+                f"{self.api_url}.",
+                fix=LOGIN_FIX_PYTHON,
+            )
+        return self._client
+
+    def _reporter(self, on_progress: ProgressCallback | None = None) -> Reporter:
+        return make_reporter(progress=self._progress, on_progress=on_progress or self._on_progress)
+
+    def _web(self) -> str | None:
+        return self._client.web_url
+
+    # -- the five things a script does -------------------------------------
+
+    def me(self) -> Me:
+        """Who the credential is, and the scopes it grants (`GET /v1/auth/me`)."""
+        client = self._auth()
+        with self._calls():
+            me = client.me()
+        return Me.from_sdk(
+            me,
+            key_prefix=self._credentials.key_display,
+            key_source=self._credentials.key_source,
+            api_url=self.api_url,
+        )
+
+    def push(
+        self,
+        path: str | os.PathLike[str],
+        repo: str,
+        *,
+        kind: str = "dataset",
+        public: bool = False,
+        rehash: bool = False,
+        description: str | None = None,
+        jobs: int = 8,
+        dry_run: bool = False,
+        on_progress: ProgressCallback | None = None,
+    ) -> PushResult:
+        """Upload a directory to `repo` (`owner/slug`), creating it as `kind` if it is new.
+
+        Exactly `lucen push`: a file the hub already holds at that path with
+        that sha256 is skipped, bytes the hub already stores are linked and
+        not sent, a killed push resumes by the parts that never landed.
+        `public` applies only when the repo is created; `rehash` ignores the
+        local digest cache; `dry_run` reports what would upload and changes
+        nothing (and needs no key).
+        """
+        try:
+            repo_kind = RepoKind(kind)
+        except ValueError as exc:
+            raise HubError(
+                f"{kind!r} is not a repo kind.", fix="Use 'dataset', 'model' or 'robot'."
+            ) from exc
+        root = Path(path).expanduser()
+        if not root.is_dir():
+            raise HubError(f"{root} is not a directory.", fix="Pass the directory to push.")
+        client = self._client if dry_run else self._auth()
+        with self._calls():
+            result = run_push(
+                client,
+                _target(repo),
+                root,
+                kind=repo_kind,
+                private=False if public else None,
+                description=description,
+                jobs=jobs,
+                rehash=rehash,
+                reporter=self._reporter(on_progress),
+                dry_run=dry_run,
+            )
+        return PushResult.from_cli(result)
+
+    def pull(
+        self,
+        repo: str,
+        path: str | os.PathLike[str] | None = None,
+        *,
+        prefix: str | None = None,
+        force: bool = False,
+        jobs: int = 8,
+        on_progress: ProgressCallback | None = None,
+    ) -> PullResult:
+        """Download a repo's files into `path` (default `./<slug>`), verifying every sha256.
+
+        Exactly `lucen pull`: files stream in parallel, are hashed while they
+        are written and take their name only when the digest matches the
+        tree's; one already on disk with the right size and digest is skipped
+        (`force` re-downloads it). A public repo needs no key.
+        """
+        target = _target(repo)
+        dest = Path(path).expanduser() if path is not None else Path(target.slug)
+        with self._calls():
+            result = run_pull(
+                self._client,
+                target,
+                dest,
+                prefix=prefix,
+                jobs=jobs,
+                force=force,
+                reporter=self._reporter(on_progress),
+            )
+        return PullResult.from_cli(result)
+
+    def open(self, target: str | None = None) -> str:
+        """The web address of a repo (`owner/slug`), a run, a rollout, an endpoint or a plan.
+
+        The origin is `LUCEN_WEB_URL`, else what the hub answered last time
+        (`~/.config/lucen/hub.json`, the file `lucen open` keeps), else
+        `/healthz` now — then cached. Nothing is opened; the string is returned.
+        """
+        with self._calls():
+            path = page_path(target)
+        web = self._web_origin()
+        url = page_url(web, path)
+        assert url is not None
+        return url
+
+    def _web_origin(self) -> str:
+        if os.environ.get(ENV_WEB_URL):
+            origin = web_url_for(None)
+            assert origin is not None
+            return origin
+        cached = load_cached_web_url(self.api_url)
+        if cached:
+            return cached
+        with self._calls():
+            health = self._client.health()
+        origin = web_url_for(unset_to_none(health.web_url))
+        save_cached_web_url(self.api_url, origin)
+        if origin is None:
+            raise HubError(
+                f"The hub at {self.api_url} names no web address.",
+                fix=f"Set {ENV_WEB_URL} to the web app's origin (https://…), or ask the hub's "
+                "operator to set API_CORS_ORIGINS.",
+            )
+        return origin
+
+
+class Repos:
+    """`hub.repos`: list, read, create and delete dataset / model / robot repos."""
+
+    def __init__(self, hub: Hub) -> None:
+        self._hub = hub
+
+    def list(
+        self,
+        *,
+        kind: str | None = None,
+        owner: str | None = None,
+        q: str | None = None,
+        limit: int = 20,
+    ) -> builtins.list[Repo]:
+        """The repos this credential can see: public ones, yours, your organizations'."""
+        repo_kind = RepoKind(kind) if kind else None
+        with self._hub._calls():
+            repos = self._hub._client.list_repos(query=q, kind=repo_kind, owner=owner, limit=limit)
+            web = self._hub._web() if repos else None
+        return [Repo.from_sdk(repo, web=web) for repo in repos]
+
+    def get(self, repo: str) -> Repo:
+        """One repo; `NotFound` when it does not exist or is private and not yours."""
+        target = _target(repo)
+        with self._hub._calls():
+            found = self._hub._client.get_repo(target)
+            if found is None:
+                raise NotFound(
+                    f"Reading {target.full_name}: no such repo, or not yours.",
+                    status=404,
+                    fix="`hub.repos.list()` shows the ones this credential can see; a private "
+                    "one you are not a member of looks the same as none.",
+                )
+            return Repo.from_sdk(found, web=self._hub._web())
+
+    def create(
+        self,
+        repo: str,
+        *,
+        kind: str = "dataset",
+        public: bool = False,
+        description: str | None = None,
+        tags: Sequence[str] = (),
+    ) -> Repo:
+        """An empty repo under your handle or an organization you belong to."""
+        client = self._hub._auth()
+        with self._hub._calls():
+            created = client.create_repo(
+                _target(repo),
+                kind=RepoKind(kind),
+                visibility=Visibility.PUBLIC if public else Visibility.PRIVATE,
+                description=description,
+                tags=tags,
+            )
+            return Repo.from_sdk(created, web=self._hub._web())
+
+    def delete(self, repo: str) -> None:
+        """Delete a repo; `Conflict` names the run or rollout whose history still needs it."""
+        client = self._hub._auth()
+        with self._hub._calls():
+            client.delete_repo(_target(repo))
+
+
+class Runs:
+    """`hub.runs`: submit, price, plan, read, follow and cancel training runs."""
+
+    def __init__(self, hub: Hub) -> None:
+        self._hub = hub
+
+    def create(
+        self,
+        recipe: RecipeLike,
+        *,
+        executor: str | None = None,
+        robot: str | None = None,
+        parent: str | None = None,
+        owner: str | None = None,
+        idempotency_key: str | None = None,
+        follow: bool = False,
+        on_log: LogCallback | None = None,
+    ) -> Run:
+        """Submit a run (`POST /v1/runs`); with `follow=True`, stay until it ends.
+
+        `recipe` is a mapping (`template`, `dataset`, `hyperparams`, `gpu`,
+        `max_hours`, `executor`, `budget_usd`, `robot`) or the path of the
+        YAML/JSON file `lucen train -f` reads. `executor` is `worker` (the
+        default: it runs when a `lucen worker run` you start claims it) or
+        `modal`. With `follow=True` every log line goes to `on_log` as a
+        :class:`~lucen.results.LogEvent` (or to the hub's progress reporter),
+        and the run returned is its final state — `status` is `succeeded`,
+        `failed` or `canceled`. Ctrl-C detaches; the run keeps going.
+        """
+        body, file_owner, file_parent = _recipe(recipe)
+        if executor is not None:
+            body["executor"] = executor
+        if robot is not None:
+            body["robot"] = robot
+        client = self._hub._auth()
+        with self._hub._calls():
+            run, created = client.create_run(
+                body,
+                owner=owner or file_owner,
+                parent_run_id=parent or file_parent,
+                idempotency_key=idempotency_key,
+            )
+            if not follow:
+                return Run.from_sdk(run, web=self._hub._web(), created=created)
+            for event in self._stream(run.id, follow=True, tail=None):
+                self._emit(event, on_log)
+            final = client.get_run(run.id)
+            return Run.from_sdk(final, web=self._hub._web(), created=created)
+
+    def _stream(self, run_id: str, *, follow: bool, tail: int | None) -> Iterator[LogEvent]:
+        client = self._hub._auth()
+        with self._hub._calls():
+            for event in client.stream_logs(run_id, follow=follow, tail=tail):
+                yield LogEvent.from_sse(event)
+
+    def _emit(self, event: LogEvent, on_log: LogCallback | None) -> None:
+        if on_log is not None:
+            on_log(event)
+            return
+        if event.kind != "log":
+            return
+        reporter = self._hub._reporter()
+        if isinstance(reporter, CallbackReporter):
+            reporter.log(event.line or "", stream=event.stream or "stdout")
+        else:
+            reporter.step(event.text)
+
+    def list(
+        self,
+        *,
+        status: str | None = None,
+        executor: str | None = None,
+        owner: str | None = None,
+        limit: int = 20,
+    ) -> builtins.list[Run]:
+        """The runs this credential can see, newest first (no run is public)."""
+        client = self._hub._auth()
+        with self._hub._calls():
+            runs = client.list_runs(owner=owner, status=status, executor=executor, limit=limit)
+            web = self._hub._web() if runs else None
+        return [Run.from_sdk(run, web=web) for run in runs]
+
+    def get(self, run_id: str) -> Run:
+        client = self._hub._auth()
+        with self._hub._calls():
+            return Run.from_sdk(client.get_run(run_id), web=self._hub._web())
+
+    def logs(
+        self, run_id: str, *, follow: bool = False, tail: int | None = None
+    ) -> Iterator[LogEvent]:
+        """The run's log as it was written (`follow=True`: and as it is written, until the end).
+
+        Yields :class:`~lucen.results.LogEvent`s — `log` lines, every `metric`
+        line, and one `end` carrying the run's status.
+        """
+        return self._stream(run_id, follow=follow, tail=tail)
+
+    def cancel(self, run_id: str) -> Run:
+        """Cancel: a queued run ends now; a running one is stopped by its runner."""
+        client = self._hub._auth()
+        with self._hub._calls():
+            return Run.from_sdk(client.cancel_run(run_id), web=self._hub._web())
+
+    def estimate(
+        self, recipe: RecipeLike, *, owner: str | None = None, parent: str | None = None
+    ) -> RunEstimate:
+        """The price of a recipe before anything is created (`POST /v1/runs/estimate`)."""
+        body, file_owner, file_parent = _recipe(recipe)
+        client = self._hub._auth()
+        with self._hub._calls():
+            estimate = client.estimate_run(
+                body, owner=owner or file_owner, parent_run_id=parent or file_parent
+            )
+        return RunEstimate.from_sdk(estimate)
+
+    def recommend(
+        self, recipe: RecipeLike, *, owner: str | None = None, parent: str | None = None
+    ) -> RunRecommendation:
+        """Which GPU tier a recipe needs, with the arithmetic (`POST /v1/runs/recommend`)."""
+        body, file_owner, file_parent = _recipe(recipe)
+        client = self._hub._auth()
+        with self._hub._calls():
+            rec = client.recommend_run(
+                body, owner=owner or file_owner, parent_run_id=parent or file_parent
+            )
+        return RunRecommendation.from_sdk(rec)
+
+
+class Rollouts:
+    """`hub.rollouts`: the sim gate — a policy in MuJoCo on a robot, scored by the hub."""
+
+    def __init__(self, hub: Hub) -> None:
+        self._hub = hub
+
+    def create(
+        self,
+        model: str,
+        robot: str,
+        *,
+        battery: str | Mapping[str, Any] = "smoke",
+        seed: int = 0,
+        seeds: int | None = None,
+        horizon_s: float | None = None,
+        run: str | None = None,
+        conditions: Mapping[str, Any] | None = None,
+        checkpoint: int | None = None,
+        executor: str = "worker",
+        local: bool = False,
+        name: str | None = None,
+        work_dir: str | os.PathLike[str] | None = None,
+        video: bool = True,
+        keep: bool = False,
+        on_progress: ProgressCallback | None = None,
+    ) -> Rollout:
+        """Queue a rollout of `model` on `robot`; with `local=True`, run it here and report.
+
+        `battery` is a name (`smoke`, `full`, `c_matrix`, `robust`, `recovery`,
+        `watch`, `stand`) or a `BatterySpec` mapping. `run` attaches the
+        scorecard to that training run. Without `local` the rollout waits
+        `queued` for a `lucen rollout worker`; with it, this machine claims
+        and executes it (the `rollout` extra), the hub scores it, and the
+        rollout returned is its final state. A local rollout that did not
+        succeed raises `HubError` with the reason, as `lucen rollout` exits 1.
+        """
+        if executor not in ("worker", "modal"):
+            raise HubError(f"executor={executor!r}: expected 'worker' or 'modal'.")
+        if local and executor == "modal":
+            raise HubError(
+                "local=True runs the rollout here; executor='modal' asks the hub to run it on "
+                "Modal.",
+                fix="Pick one.",
+            )
+        if local:
+            _require_engine("A local rollout")
+        client = self._hub._auth()
+        body: dict[str, Any] = {
+            "model_repo": _target(model).full_name,
+            "robot_repo": _target(robot).full_name,
+            "seed": seed,
+            "battery": dict(battery) if isinstance(battery, Mapping) else battery,
+            "executor": executor,
+        }
+        if horizon_s is not None:
+            body["horizon_s"] = horizon_s
+        if run:
+            body["run_id"] = run
+        if seeds is not None:
+            body["seeds"] = seeds
+        if checkpoint is not None:
+            body["checkpoint_step"] = checkpoint
+        if conditions:
+            body["conditions"] = dict(conditions)
+        reporter = self._hub._reporter(on_progress)
+        with self._hub._calls():
+            rollout = client.create_rollout(body)
+            spec = unset_to_none(rollout.battery_spec)
+            if spec is not None:
+                reporter.step(
+                    created_line(
+                        rollout.id,
+                        unset_to_none(rollout.battery),
+                        len(spec.cells),
+                        unset_to_none(spec.seeds) or 0,
+                        unset_to_none(spec.horizon_s) or 0.0,
+                    )
+                )
+            if not local:
+                return Rollout.from_sdk(rollout, web=self._hub._web())
+            import socket
+            import tempfile
+
+            from lucen_cli.rollout.worker import RolloutWorkerConfig, execute_rollout
+
+            config = RolloutWorkerConfig(
+                name=(name or socket.gethostname() or "lucen-rollout")[:128],
+                work_dir=(
+                    Path(work_dir).expanduser()
+                    if work_dir is not None
+                    else Path(tempfile.gettempdir()) / "lucen-rollout"
+                ),
+                keep_work=keep,
+                render=video,
+            )
+            claimed = client.claim_rollout(rollout.id, config.name)
+            reporter.step(f"Running the test suite on this machine, as {config.name}")
+            outcome = execute_rollout(client, claimed, config, reporter)
+            final = Rollout.from_sdk(client.get_rollout(rollout.id), web=self._hub._web())
+        if outcome.status != "succeeded":
+            reason = (outcome.error or "no reason recorded").splitlines()[0]
+            raise HubError(
+                f"Sim test {rollout.id} failed: {reason}",
+                detail=outcome.error,
+                fix=f"`hub.rollouts.get({rollout.id!r})` has the full reason; fix it and run "
+                "the same call again (the hub keeps the failed one).",
+            )
+        return final
+
+    def get(self, rollout_id: str) -> Rollout:
+        client = self._hub._auth()
+        with self._hub._calls():
+            return Rollout.from_sdk(client.get_rollout(rollout_id), web=self._hub._web())
+
+    def list(
+        self,
+        *,
+        status: str | None = None,
+        model: str | None = None,
+        run: str | None = None,
+        limit: int = 20,
+    ) -> builtins.list[Rollout]:
+        client = self._hub._auth()
+        with self._hub._calls():
+            rollouts = client.list_rollouts(
+                status=status, model_repo=model, run_id=run, limit=limit
+            )
+            web = self._hub._web() if rollouts else None
+        return [Rollout.from_sdk(rollout, web=web) for rollout in rollouts]
+
+    def cancel(self, rollout_id: str) -> Rollout:
+        client = self._hub._auth()
+        with self._hub._calls():
+            return Rollout.from_sdk(client.cancel_rollout(rollout_id), web=self._hub._web())
+
+
+class Robots:
+    """`hub.robots`: `lucen robot init | validate | publish`, and a robot's card.
+
+    The three local commands compile the model with real MuJoCo, so they need
+    the `rollout` extra and raise `ImportError` naming the install line
+    without it; `card()` needs only the hub.
+    """
+
+    def __init__(self, hub: Hub) -> None:
+        self._hub = hub
+
+    def init(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        control_hz: float,
+        action: str,
+        base: str | None = None,
+        action_scale: float | None = None,
+        action_clip: float | None = None,
+        kp: float | None = None,
+        kd: float | None = None,
+        armature: float | None = None,
+        friction_loss: float | None = None,
+        proprioception: Sequence[str] | None = None,
+        command: str | None = None,
+        keyframe: str | None = None,
+        default_pose: Mapping[str, float] | None = None,
+        discard_visual: bool = False,
+        root: str | os.PathLike[str] | None = None,
+        force: bool = False,
+    ) -> RobotDraft:
+        """Compile an MJCF or URDF and draft `robot_card.json` beside it (`lucen robot init`)."""
+        _require_engine("hub.robots.init")
+        from lucen_cli.cmd_robot import run_init
+
+        with self._hub._calls():
+            result = run_init(
+                Path(path).expanduser(),
+                control_hz=control_hz,
+                action=action,
+                base=base,
+                action_scale=action_scale,
+                action_clip=action_clip,
+                kp=kp,
+                kd=kd,
+                armature=armature,
+                friction_loss=friction_loss,
+                proprioception=",".join(proprioception) if proprioception else None,
+                command=command,
+                keyframe=keyframe,
+                default_pose=dict(default_pose) if default_pose else None,
+                discard_visual=discard_visual,
+                root=Path(root).expanduser() if root is not None else None,
+                force=force,
+            )
+        return RobotDraft.from_cli(result)
+
+    def validate(
+        self,
+        directory: str | os.PathLike[str] = ".",
+        *,
+        card: str | os.PathLike[str] | None = None,
+        settle_s: float = 3.0,
+        dynamics: bool = True,
+    ) -> RobotReport:
+        """The compile report on a directory's card (`lucen robot validate`); a fail is a value."""
+        _require_engine("hub.robots.validate")
+        from lucen_cli.robot.checks import validate as run_validate
+
+        with self._hub._calls():
+            report = run_validate(
+                Path(directory).expanduser().resolve(),
+                card_path=Path(card).expanduser() if card is not None else None,
+                settle_s=settle_s,
+                dynamics=dynamics,
+            )
+        return RobotReport.from_cli(report.to_dict())
+
+    def publish(
+        self,
+        repo: str,
+        directory: str | os.PathLike[str] = ".",
+        *,
+        public: bool = False,
+        description: str | None = None,
+        force: bool = False,
+        thumbnails: bool = True,
+        settle_s: float = 3.0,
+        jobs: int = 8,
+        on_progress: ProgressCallback | None = None,
+    ) -> RobotPublishResult:
+        """Validate, create the robot repo if missing, push the files, set the card. Idempotent."""
+        _require_engine("hub.robots.publish")
+        from lucen_cli.robot.checks import load_card, validate_card
+        from lucen_cli.robot.publish import publish as run_publish
+
+        client = self._hub._auth()
+        root = Path(directory).expanduser().resolve()
+        with self._hub._calls():
+            card, needs = load_card(root)
+            report = validate_card(root, card, needs, settle_s=settle_s)
+            result = run_publish(
+                client,
+                _target(repo),
+                root,
+                card,
+                report,
+                private=False if public else None,
+                description=description,
+                jobs=jobs,
+                reporter=self._hub._reporter(on_progress),
+                force=force,
+                thumbnails=thumbnails,
+            )
+        return RobotPublishResult.from_cli({"ok": True, **result.to_dict()})
+
+    def card(self, repo: str) -> dict[str, Any]:
+        """A robot repo's card as the hub stores it (`GET /v1/robots/{owner}/{repo}/card`)."""
+        with self._hub._calls():
+            return self._hub._client.get_robot_card(_target(repo)).to_dict()
+
+
+class Orgs:
+    """`hub.orgs`: the organizations a lab shares (`lucen org`)."""
+
+    def __init__(self, hub: Hub) -> None:
+        self._hub = hub
+
+    def list(self) -> builtins.list[Org]:
+        """Every organization you belong to, with your role in each."""
+        client = self._hub._auth()
+        with self._hub._calls():
+            memberships = client.list_my_orgs()
+            web = self._hub._web() if memberships else None
+        return [Org.from_membership(membership, web=web) for membership in memberships]
+
+    def create(self, slug: str, *, name: str | None = None, description: str | None = None) -> Org:
+        """Create an organization; you become its first owner."""
+        client = self._hub._auth()
+        with self._hub._calls():
+            org = client.create_org(slug, display_name=name, description=description)
+            return Org.from_sdk(org, web=self._hub._web(), role="owner")
+
+    def members(self, org: str) -> builtins.list[Member]:
+        """An organization's members, owners first (members only)."""
+        client = self._hub._auth()
+        with self._hub._calls():
+            rows = client.list_org_members(org)
+        return sorted(
+            (Member.from_sdk(row) for row in rows),
+            key=lambda member: (member.role != "owner", member.username),
+        )
+
+    def add(self, org: str, username: str, *, role: str = "member") -> Member:
+        """Add a person by hub handle (they must have signed up first), or change their role."""
+        try:
+            org_role = OrgRole(role)
+        except ValueError as exc:
+            raise HubError(f"role={role!r}: expected 'member' or 'owner'.") from exc
+        client = self._hub._auth()
+        with self._hub._calls():
+            return Member.from_sdk(client.put_org_member(org, username, org_role))
+
+    def remove(self, org: str, username: str) -> None:
+        """Remove a member (owners only); `leave()` is how you remove yourself."""
+        client = self._hub._auth()
+        with self._hub._calls():
+            client.remove_org_member(org, username)
+
+    def leave(self, org: str) -> None:
+        """Leave an organization; the last owner must make someone else an owner first."""
+        client = self._hub._auth()
+        with self._hub._calls():
+            me = client.me().user.username
+            client.remove_org_member(org, me, leaving=True)
+
+
+class Datasets:
+    """`hub.datasets`: what the hub reads out of a LeRobot-format dataset repo."""
+
+    def __init__(self, hub: Hub) -> None:
+        self._hub = hub
+
+    def episodes(self, repo: str) -> list[Episode]:
+        """Every episode of a dataset repo (index, frames, tasks); a public one needs no key."""
+        with self._hub._calls():
+            rows = self._hub._client.list_episodes(_target(repo))
+        return [Episode.from_sdk(row) for row in rows]
+
+
+__all__ = ["ENGINE_FIX", "Datasets", "Hub", "Orgs", "Repos", "Robots", "Rollouts", "Runs"]