lucen-cli 0.1.0__py3-none-any.whl

lucen/results.py

@@ -0,0 +1,885 @@
+"""What a call returns: small frozen records with the fields a script wants.
+
+Each one carries ids, URLs and counts as plain attributes, a `to_dict()` that
+is the same object `lucen … --json` prints where the CLI has one, and `raw` —
+the generated SDK model (or the CLI engine's own result) with every field the
+contract defines, for the one case the record does not cover.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from typing import Any
+
+from lucen_sdk.models import (
+    Episode as SdkEpisode,
+)
+from lucen_sdk.models import (
+    Me as SdkMe,
+)
+from lucen_sdk.models import (
+    Member as SdkMember,
+)
+from lucen_sdk.models import (
+    Org as SdkOrg,
+)
+from lucen_sdk.models import (
+    OrgMembership as SdkOrgMembership,
+)
+from lucen_sdk.models import (
+    Repo as SdkRepo,
+)
+from lucen_sdk.models import (
+    Rollout as SdkRollout,
+)
+from lucen_sdk.models import (
+    Run as SdkRun,
+)
+from lucen_sdk.models import (
+    RunEstimate as SdkRunEstimate,
+)
+from lucen_sdk.models import (
+    RunRecommendation as SdkRunRecommendation,
+)
+
+from lucen_cli.client import SseEvent, unset_to_none
+from lucen_cli.config import page_url
+from lucen_cli.local import human_bytes
+from lucen_cli.output import repo_dict, rollout_dict, run_dict
+from lucen_cli.pull import PullResult as CliPullResult
+from lucen_cli.push import PushResult as CliPushResult
+from lucen_cli.sim_words import passing, suite_label
+
+
+def _public(record: Any) -> dict[str, Any]:
+    """`asdict` without `raw` (an SDK model is not JSON)."""
+    data = asdict(record)
+    data.pop("raw", None)
+    return data
+
+
+# ---------------------------------------------------------------------------
+# Who you are
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Me:
+    """`GET /v1/auth/me`: the user and what the credential may do."""
+
+    username: str
+    display_name: str | None
+    #: `api_key` or `session`.
+    auth_kind: str
+    #: The nested scopes the key grants: `read` ⊂ `write` ⊂ `train`.
+    scopes: tuple[str, ...]
+    key_id: str | None
+    #: `lucen_sk_xxxxxxxx…` — never the whole key.
+    key_prefix: str
+    #: `env`, `file` or `argument`: where the key came from.
+    key_source: str
+    api_url: str
+    raw: SdkMe = field(repr=False, compare=False)
+
+    @classmethod
+    def from_sdk(cls, me: SdkMe, *, key_prefix: str, key_source: str, api_url: str) -> Me:
+        return cls(
+            username=me.user.username,
+            display_name=unset_to_none(me.user.display_name),
+            auth_kind=str(me.auth.kind),
+            scopes=tuple(str(scope) for scope in me.auth.scopes),
+            key_id=unset_to_none(me.auth.key_id),
+            key_prefix=key_prefix,
+            key_source=key_source,
+            api_url=api_url,
+            raw=me,
+        )
+
+    def can(self, scope: str) -> bool:
+        """Whether the credential grants `scope` (`read`, `write` or `train`)."""
+        return scope in self.scopes
+
+    def to_dict(self) -> dict[str, Any]:
+        return _public(self)
+
+    def __str__(self) -> str:
+        return (
+            f"{self.username} · key {self.key_prefix} from {self.key_source} · "
+            f"scopes {', '.join(self.scopes) or 'none'} · {self.api_url}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Repos, push, pull
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Repo:
+    """A dataset, model or robot repo as the hub lists it."""
+
+    id: str
+    full_name: str
+    owner: str
+    slug: str
+    #: `dataset`, `model` or `robot`.
+    kind: str
+    #: `public` or `private`.
+    visibility: str
+    description: str | None
+    tags: tuple[str, ...]
+    #: The repo's page on the hub's web app, when the hub names one.
+    url: str | None
+    created_at: datetime
+    updated_at: datetime
+    raw: SdkRepo = field(repr=False, compare=False)
+
+    @classmethod
+    def from_sdk(cls, repo: SdkRepo, *, web: str | None) -> Repo:
+        return cls(
+            id=repo.id,
+            full_name=repo.full_name,
+            owner=repo.owner.handle,
+            slug=repo.slug,
+            kind=str(repo.kind),
+            visibility=str(repo.visibility),
+            description=unset_to_none(repo.description),
+            tags=tuple(repo.tags),
+            url=page_url(web, f"/{repo.full_name}"),
+            created_at=repo.created_at,
+            updated_at=repo.updated_at,
+            raw=repo,
+        )
+
+    @property
+    def public(self) -> bool:
+        return self.visibility == "public"
+
+    def to_dict(self) -> dict[str, Any]:
+        """The row `lucen repo ls --json` prints."""
+        return repo_dict(self.raw)
+
+    def __str__(self) -> str:
+        return f"{self.full_name} ({self.kind}, {self.visibility})"
+
+
+@dataclass(frozen=True)
+class PushResult:
+    """What :meth:`lucen.Hub.push` did, in numbers a script can assert on."""
+
+    repo: str
+    url: str | None
+    #: True when the push created the repo.
+    created: bool
+    kind: str
+    visibility: str
+    files_total: int
+    #: Files the hub already held at that path with that sha256: untouched.
+    files_unchanged: int
+    #: Files the hub already held under another path or account: linked, no bytes.
+    files_linked: int
+    files_uploaded: int
+    parts_uploaded: int
+    bytes_uploaded: int
+    bytes_total: int
+    dry_run: bool
+    #: With `dry_run=True`: the paths that would have uploaded.
+    would_upload: tuple[str, ...]
+    raw: CliPushResult = field(repr=False, compare=False)
+
+    @classmethod
+    def from_cli(cls, result: CliPushResult) -> PushResult:
+        return cls(
+            repo=result.repo,
+            url=result.url,
+            created=result.created,
+            kind=result.kind,
+            visibility=result.visibility,
+            files_total=result.files_total,
+            files_unchanged=result.files_unchanged,
+            files_linked=result.files_linked,
+            files_uploaded=result.files_uploaded,
+            parts_uploaded=result.parts_uploaded,
+            bytes_uploaded=result.bytes_uploaded,
+            bytes_total=result.bytes_total,
+            dry_run=result.dry_run,
+            would_upload=tuple(result.would_upload),
+            raw=result,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """The object `lucen push --json` prints."""
+        return self.raw.to_dict()
+
+    def __str__(self) -> str:
+        verb = "Created and pushed" if self.created else "Pushed"
+        return (
+            f"{verb} {self.repo}: {self.files_total} file(s), {self.files_uploaded} uploaded "
+            f"({human_bytes(self.bytes_uploaded)}), {self.files_linked} deduped, "
+            f"{self.files_unchanged} unchanged"
+        )
+
+
+@dataclass(frozen=True)
+class PullResult:
+    """What :meth:`lucen.Hub.pull` did. Every downloaded file's sha256 was verified."""
+
+    repo: str
+    #: The destination directory, absolute.
+    path: str
+    files_total: int
+    files_downloaded: int
+    #: Files already on disk with the right size and sha256.
+    files_skipped: int
+    bytes_downloaded: int
+    bytes_total: int
+    raw: CliPullResult = field(repr=False, compare=False)
+
+    @classmethod
+    def from_cli(cls, result: CliPullResult) -> PullResult:
+        return cls(
+            repo=result.repo,
+            path=result.dest,
+            files_total=result.files_total,
+            files_downloaded=result.files_downloaded,
+            files_skipped=result.files_skipped,
+            bytes_downloaded=result.bytes_downloaded,
+            bytes_total=result.bytes_total,
+            raw=result,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """The object `lucen pull --json` prints."""
+        return self.raw.to_dict()
+
+    def __str__(self) -> str:
+        return (
+            f"Pulled {self.repo}: {self.files_total} file(s), {self.files_downloaded} downloaded "
+            f"({human_bytes(self.bytes_downloaded)}), {self.files_skipped} already local"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Runs
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Gate:
+    """A run's sim-gate count: `passed` of `total` cells PASS on its latest scorecard."""
+
+    passed: int
+    total: int
+
+    def __str__(self) -> str:
+        return f"{self.passed} / {self.total} PASS"
+
+
+@dataclass(frozen=True)
+class Run:
+    """A training run as the hub reads it back."""
+
+    id: str
+    #: `queued`, `running`, `succeeded`, `failed` or `canceled`.
+    status: str
+    #: `cloud` (executed), `external` (imported) or `orchestration`.
+    kind: str
+    template: str
+    #: `worker` (a runner you start) or `modal` (the hub's GPU backend).
+    executor: str | None
+    owner: str
+    parent_run_id: str | None
+    claimed_by: str | None
+    #: `owner/slug` of the model repo the run published, once it has.
+    output_model_repo: str | None
+    #: The last metrics line the runner reported.
+    latest_metrics: dict[str, Any] | None
+    #: The sim gate's count on the run's scorecard, when it has one.
+    gate: Gate | None
+    cost_usd: float | None
+    error: str | None
+    #: The run's page on the hub's web app, when the hub names one.
+    url: str | None
+    created_at: datetime
+    finished_at: datetime | None
+    #: On a create: whether this call made the run (False on an idempotent replay).
+    created: bool | None
+    raw: SdkRun = field(repr=False, compare=False)
+
+    @classmethod
+    def from_sdk(cls, run: SdkRun, *, web: str | None, created: bool | None = None) -> Run:
+        data = run_dict(run)
+        gate = unset_to_none(run.gate)
+        return cls(
+            id=run.id,
+            status=data["status"],
+            kind=data["kind"],
+            template=data["template"],
+            executor=data["executor"],
+            owner=data["owner"],
+            parent_run_id=data["parent_run_id"],
+            claimed_by=data["claimed_by"],
+            output_model_repo=data["output_model_repo"],
+            latest_metrics=data["latest_metrics"],
+            gate=Gate(gate.passed, gate.total) if gate is not None else None,
+            cost_usd=data["cost_usd"],
+            error=data["error"],
+            url=page_url(web, f"/runs/{run.id}"),
+            created_at=run.created_at,
+            finished_at=unset_to_none(run.finished_at),
+            created=created,
+            raw=run,
+        )
+
+    @property
+    def done(self) -> bool:
+        """True once the run is `succeeded`, `failed` or `canceled`."""
+        return self.status in ("succeeded", "failed", "canceled")
+
+    def to_dict(self) -> dict[str, Any]:
+        """The object `lucen runs show --json` prints."""
+        data = run_dict(self.raw)
+        data["url"] = self.url
+        if self.created is not None:
+            data["created"] = self.created
+        return data
+
+    def __str__(self) -> str:
+        bits = [f"{self.id} ({self.status}, {self.template}"]
+        if self.executor:
+            bits[0] += f" on {self.executor}"
+        bits[0] += ")"
+        if self.output_model_repo:
+            bits.append(f"model {self.output_model_repo}")
+        if self.gate is not None:
+            bits.append(f"gate {self.gate}")
+        if self.error:
+            bits.append(f"error: {self.error.splitlines()[0]}")
+        return " · ".join(bits)
+
+
+@dataclass(frozen=True)
+class LogEvent:
+    """One frame of a run's log stream.
+
+    `kind` is ``log`` (a line: `line`, with `stream` ``stdout`` for the
+    trainer's own output and ``stderr`` for a notice the hub wrote into the
+    log — a cancel request, a re-queue), ``metric`` (one `metrics.jsonl` line
+    as `metrics`, numbered by `index`), or ``end`` (the stream closed; `status`
+    is the run's status at that moment).
+    """
+
+    kind: str
+    line: str | None = None
+    stream: str | None = None
+    ts: str | None = None
+    metrics: dict[str, Any] | None = None
+    index: int | None = None
+    status: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_sse(cls, event: SseEvent) -> LogEvent:
+        data = event.data
+        metrics = data.get("metrics")
+        index = data.get("index")
+        return cls(
+            kind=event.event,
+            line=data.get("line") if event.event == "log" else None,
+            stream=data.get("stream") if event.event == "log" else None,
+            ts=data.get("ts"),
+            metrics=dict(metrics) if isinstance(metrics, Mapping) else None,
+            index=int(index) if isinstance(index, int) else None,
+            status=data.get("status") if event.event == "end" else None,
+            raw=dict(data),
+        )
+
+    @property
+    def is_notice(self) -> bool:
+        """True for a line the hub wrote, not the trainer (`stream == "stderr"`)."""
+        return self.kind == "log" and self.stream == "stderr"
+
+    @property
+    def text(self) -> str:
+        """The line as `lucen train --follow` prints it: `  | …` the runner, `  ! …` the hub."""
+        if self.kind == "log":
+            return f"  {'!' if self.is_notice else '|'} {self.line or ''}"
+        if self.kind == "end":
+            return f"-- {self.status}"
+        return f"  = {self.metrics}"
+
+    def __str__(self) -> str:
+        return self.text
+
+
+@dataclass(frozen=True)
+class RunEstimate:
+    """`POST /v1/runs/estimate`: the price of a recipe before anything is created."""
+
+    executor: str
+    tier: str | None
+    rate_usd_per_hour: float
+    #: C1: the Isaac host's share, on top of the GPU rate (0 elsewhere).
+    host_rate_usd_per_hour: float
+    max_hours: float
+    cost_usd_max: float
+    #: False on a `worker` run: your own machine, nothing billed.
+    priced: bool
+    budget_usd: float | None
+    capped_by_budget: bool
+    raw: SdkRunEstimate = field(repr=False, compare=False)
+
+    @classmethod
+    def from_sdk(cls, estimate: SdkRunEstimate) -> RunEstimate:
+        return cls(
+            executor=str(estimate.executor),
+            tier=estimate.tier,
+            rate_usd_per_hour=estimate.rate_usd_per_hour,
+            host_rate_usd_per_hour=float(unset_to_none(estimate.host_rate_usd_per_hour) or 0.0),
+            max_hours=estimate.max_hours,
+            cost_usd_max=estimate.cost_usd_max,
+            priced=estimate.priced,
+            budget_usd=unset_to_none(estimate.budget_usd),
+            capped_by_budget=bool(unset_to_none(estimate.capped_by_budget) or False),
+            raw=estimate,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return _public(self)
+
+    def __str__(self) -> str:
+        if not self.priced:
+            return f"{self.executor}: not priced (your own machine), up to {self.max_hours:g} h"
+        return (
+            f"{self.executor} on {self.tier}: ${self.rate_usd_per_hour:.4f}/h x "
+            f"{self.max_hours:g} h = at most ${self.cost_usd_max:.4f}"
+        )
+
+
+@dataclass(frozen=True)
+class RunRecommendation:
+    """`POST /v1/runs/recommend`: the hub's deterministic hardware planner, with its arithmetic."""
+
+    template: str
+    #: The smallest GPU tier that fits (`l4`, `a10g`, `a100`, `h100`, `l40s`), or None.
+    tier: str | None
+    vram_estimate_gb: float
+    vram_required_gb: float
+    fits_on: tuple[str, ...]
+    est_hours: float | None
+    cost_usd_est: float | None
+    cost_usd_max: float
+    priced: bool
+    #: `modelled` or `measured` (from succeeded runs of the same template).
+    basis: str
+    #: Whether the hub can execute the template, or only plan it.
+    implemented: bool
+    #: One line per step of the arithmetic.
+    why: tuple[str, ...]
+    warnings: tuple[str, ...]
+    raw: SdkRunRecommendation = field(repr=False, compare=False)
+
+    @classmethod
+    def from_sdk(cls, rec: SdkRunRecommendation) -> RunRecommendation:
+        return cls(
+            template=rec.template,
+            tier=rec.tier,
+            vram_estimate_gb=rec.vram_estimate_gb,
+            vram_required_gb=rec.vram_required_gb,
+            fits_on=tuple(rec.fits_on),
+            est_hours=rec.est_hours,
+            cost_usd_est=rec.cost_usd_est,
+            cost_usd_max=rec.cost_usd_max,
+            priced=rec.priced,
+            basis=str(rec.basis),
+            implemented=rec.implemented,
+            why=tuple(rec.why),
+            warnings=tuple(rec.warnings),
+            raw=rec,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return _public(self)
+
+    def __str__(self) -> str:
+        tier = self.tier or "no tier fits"
+        return (
+            f"{self.template}: {tier} — {self.vram_required_gb:g} GB required "
+            f"({self.vram_estimate_gb:g} GB {self.basis}), fits on {', '.join(self.fits_on) or '—'}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Rollouts (the sim gate)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Cell:
+    """One cell of a rollout's battery, with the hub's verdict."""
+
+    name: str
+    #: `PASS` or `FAIL`, or None while the rollout is not finished.
+    verdict: str | None
+    seeds: int
+    #: Seeds that stayed upright for the whole horizon.
+    alive: int
+    #: Per-axis tracking ratio (`vx`, `vy`, `yaw`), when the cell commands one.
+    tracking: dict[str, Any]
+    detail: str | None
+    #: `velocity`, `joint_target`, `reach`, `recovery`.
+    kind: str
+    #: Presigned URLs (an hour) for the mp4 and the trajectory JSON.
+    video_url: str | None
+    traj_url: str | None
+
+    @property
+    def passed(self) -> bool:
+        return self.verdict == "PASS"
+
+    def __str__(self) -> str:
+        return f"{self.name}: {self.verdict or '—'} ({self.alive}/{self.seeds} upright)"
+
+
+@dataclass(frozen=True)
+class Rollout:
+    """A rollout — a policy run in MuJoCo on a robot's own model, scored by the hub."""
+
+    id: str
+    #: `queued`, `running`, `succeeded`, `failed` or `canceled`.
+    status: str
+    #: `owner/slug` of the model repo.
+    model: str
+    #: `owner/slug` of the robot repo.
+    robot: str
+    battery: str | None
+    seed: int
+    horizon_s: float
+    #: The training run the scorecard is attached to, when one was named.
+    run_id: str | None
+    claimed_by: str | None
+    cells: tuple[Cell, ...]
+    #: Cells that PASS, out of all cells, once scored.
+    passed: int | None
+    total: int | None
+    warnings: tuple[str, ...]
+    cost_usd: float | None
+    priced: bool
+    error: str | None
+    url: str | None
+    created_at: datetime
+    finished_at: datetime | None
+    raw: SdkRollout = field(repr=False, compare=False)
+
+    @classmethod
+    def from_sdk(cls, rollout: SdkRollout, *, web: str | None) -> Rollout:
+        data = rollout_dict(rollout)
+        cells = tuple(
+            Cell(
+                name=cell["name"],
+                verdict=cell["status"],
+                seeds=cell["seeds"],
+                alive=cell["alive"],
+                tracking=dict(cell.get("tracking") or {}),
+                detail=cell.get("detail"),
+                kind=str(cell.get("kind") or "velocity"),
+                video_url=cell.get("video_url"),
+                traj_url=cell.get("traj_url"),
+            )
+            for cell in data["cells"]
+        )
+        return cls(
+            id=rollout.id,
+            status=data["status"],
+            model=data["model_repo"],
+            robot=data["robot_repo"],
+            battery=data["battery"],
+            seed=data["seed"],
+            horizon_s=data["horizon_s"],
+            run_id=data["run_id"],
+            claimed_by=data["claimed_by"],
+            cells=cells,
+            passed=data["gates_passed"],
+            total=data["gates_total"],
+            warnings=tuple(data["warnings"]),
+            cost_usd=data["cost_usd"],
+            priced=data["priced"],
+            error=data["error"],
+            url=page_url(web, f"/sim-tests/{rollout.id}"),
+            created_at=rollout.created_at,
+            finished_at=unset_to_none(rollout.finished_at),
+            raw=rollout,
+        )
+
+    @property
+    def done(self) -> bool:
+        return self.status in ("succeeded", "failed", "canceled")
+
+    @property
+    def scorecard(self) -> dict[str, str | None]:
+        """`{cell name: verdict}` — the hub's PASS/FAIL per cell."""
+        return {cell.name: cell.verdict for cell in self.cells}
+
+    def to_dict(self) -> dict[str, Any]:
+        """The object `lucen rollout show --json` prints."""
+        data = rollout_dict(self.raw)
+        data["url"] = self.url
+        return data
+
+    def __str__(self) -> str:
+        # Q9: the web's words; `to_dict()` and `scorecard()` keep PASS / FAIL and `battery`.
+        head = f"Sim test {self.id} ({self.status}): {self.model} on {self.robot}, "
+        head += suite_label(self.battery)
+        if self.total is not None:
+            head += f". {passing(self.passed, self.total)}"
+        return head + "."
+
+
+# ---------------------------------------------------------------------------
+# Organizations, datasets, robots
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Org:
+    """An organization: a handle a lab shares."""
+
+    slug: str
+    display_name: str | None
+    description: str | None
+    #: Your role in it (`owner` or `member`), when the call knows it.
+    role: str | None
+    url: str | None
+    raw: SdkOrg = field(repr=False, compare=False)
+
+    @classmethod
+    def from_sdk(cls, org: SdkOrg, *, web: str | None, role: str | None = None) -> Org:
+        return cls(
+            slug=org.slug,
+            display_name=unset_to_none(org.display_name),
+            description=unset_to_none(org.description),
+            role=role,
+            url=page_url(web, f"/{org.slug}"),
+            raw=org,
+        )
+
+    @classmethod
+    def from_membership(cls, membership: SdkOrgMembership, *, web: str | None) -> Org:
+        return cls.from_sdk(membership.org, web=web, role=str(membership.role))
+
+    def to_dict(self) -> dict[str, Any]:
+        return _public(self)
+
+    def __str__(self) -> str:
+        return f"{self.slug}" + (f" ({self.role})" if self.role else "")
+
+
+@dataclass(frozen=True)
+class Member:
+    """A person in an organization, by hub handle."""
+
+    username: str
+    display_name: str | None
+    #: `owner` or `member`.
+    role: str
+    added_at: datetime
+    raw: SdkMember = field(repr=False, compare=False)
+
+    @classmethod
+    def from_sdk(cls, member: SdkMember) -> Member:
+        return cls(
+            username=member.user.username,
+            display_name=unset_to_none(member.user.display_name),
+            role=str(member.role),
+            added_at=member.created_at,
+            raw=member,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return _public(self)
+
+    def __str__(self) -> str:
+        return f"{self.username} ({self.role})"
+
+
+@dataclass(frozen=True)
+class Episode:
+    """One episode of a LeRobot-format dataset, as the hub indexes it."""
+
+    index: int
+    num_frames: int
+    tasks: tuple[str, ...]
+    raw: SdkEpisode = field(repr=False, compare=False)
+
+    @classmethod
+    def from_sdk(cls, episode: SdkEpisode) -> Episode:
+        return cls(
+            index=episode.index,
+            num_frames=episode.num_frames,
+            tasks=tuple(unset_to_none(episode.tasks) or ()),
+            raw=episode,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return _public(self)
+
+    def __str__(self) -> str:
+        task = f" — {self.tasks[0]}" if self.tasks else ""
+        return f"episode {self.index}: {self.num_frames} frames{task}"
+
+
+@dataclass(frozen=True)
+class RobotDraft:
+    """What `lucen robot init` wrote: the card file and what you still have to declare."""
+
+    #: Absolute path of the drafted `robot_card.json`.
+    card_file: str
+    directory: str
+    mjcf_path: str
+    #: `mjcf` or `urdf` (converted).
+    source: str
+    joints: tuple[str, ...]
+    #: `fixed` or `floating`.
+    base: str
+    #: What the model file could not state: one entry per field, with a severity.
+    needs_you: tuple[dict[str, Any], ...]
+    #: The whole result, as `lucen robot init --json` prints it.
+    raw: dict[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_cli(cls, result: dict[str, Any]) -> RobotDraft:
+        model = result.get("model") or {}
+        return cls(
+            card_file=str(result["card_file"]),
+            directory=str(result["directory"]),
+            mjcf_path=str(result["mjcf_path"]),
+            source=str(result["source"]),
+            joints=tuple(str(name) for name in model.get("joints") or ()),
+            base=str(model.get("base") or ""),
+            needs_you=tuple(dict(item) for item in result.get("needs_you") or ()),
+            raw=result,
+        )
+
+    @property
+    def blocking(self) -> tuple[dict[str, Any], ...]:
+        """The `needs_you` entries that fail validation until declared."""
+        return tuple(item for item in self.needs_you if item.get("severity") == "blocking")
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self.raw)
+
+    def __str__(self) -> str:
+        return (
+            f"{self.card_file}: {len(self.joints)} joints, {self.base} base, "
+            f"{len(self.needs_you)} thing(s) to declare ({len(self.blocking)} blocking)"
+        )
+
+
+@dataclass(frozen=True)
+class RobotReport:
+    """`lucen robot validate`'s report: every check with its code, status and message."""
+
+    ok: bool
+    #: `pass`, `warn` or `fail`.
+    grade: str
+    #: `mujoco` (the CLI compiled it) or `hub` (the hub's static checks).
+    engine: str
+    checks: tuple[dict[str, Any], ...]
+    counts: dict[str, int]
+    interface_fingerprint: str | None
+    #: The whole report, as `lucen robot validate --json` prints it.
+    raw: dict[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_cli(cls, report: dict[str, Any]) -> RobotReport:
+        return cls(
+            ok=bool(report.get("ok")),
+            grade=str(report.get("grade") or ("pass" if report.get("ok") else "fail")),
+            engine=str(report.get("engine") or "mujoco"),
+            checks=tuple(dict(check) for check in report.get("checks") or ()),
+            counts=dict(report.get("counts") or {}),
+            interface_fingerprint=report.get("interface_fingerprint"),
+            raw=report,
+        )
+
+    def failed(self) -> tuple[dict[str, Any], ...]:
+        return tuple(check for check in self.checks if check.get("status") == "fail")
+
+    def warnings(self) -> tuple[dict[str, Any], ...]:
+        return tuple(check for check in self.checks if check.get("status") == "warn")
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self.raw)
+
+    def __str__(self) -> str:
+        counts = self.counts or {}
+        return (
+            f"{self.grade}: {counts.get('pass', 0)} pass · {counts.get('warn', 0)} warn · "
+            f"{counts.get('fail', 0)} fail"
+        )
+
+
+@dataclass(frozen=True)
+class RobotPublishResult:
+    """What `lucen robot publish` did: the repo, the push and the card the hub accepted."""
+
+    repo: str
+    url: str | None
+    created: bool
+    files_total: int
+    files_uploaded: int
+    bytes_uploaded: int
+    interface_fingerprint: str | None
+    #: The grade the CLI's own validation gave, and the hub's static one.
+    local_grade: str
+    hub_grade: str
+    raw: dict[str, Any] = field(repr=False, compare=False)
+
+    @classmethod
+    def from_cli(cls, result: dict[str, Any]) -> RobotPublishResult:
+        return cls(
+            repo=str(result["repo"]),
+            url=result.get("url"),
+            created=bool(result.get("created")),
+            files_total=int(result.get("files_total") or 0),
+            files_uploaded=int(result.get("files_uploaded") or 0),
+            bytes_uploaded=int(result.get("bytes_uploaded") or 0),
+            interface_fingerprint=result.get("interface_fingerprint"),
+            local_grade=str(result.get("local_grade") or ""),
+            hub_grade=str(result.get("hub_grade") or ""),
+            raw=result,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self.raw)
+
+    def __str__(self) -> str:
+        verb = "Created and published" if self.created else "Published"
+        return (
+            f"{verb} {self.repo}: {self.files_total} file(s), {self.files_uploaded} uploaded "
+            f"({human_bytes(self.bytes_uploaded)}); card set (local {self.local_grade}, "
+            f"hub {self.hub_grade})"
+        )
+
+
+__all__ = [
+    "Cell",
+    "Episode",
+    "Gate",
+    "LogEvent",
+    "Me",
+    "Member",
+    "Org",
+    "PullResult",
+    "PushResult",
+    "Repo",
+    "RobotDraft",
+    "RobotPublishResult",
+    "RobotReport",
+    "Rollout",
+    "Run",
+    "RunEstimate",
+    "RunRecommendation",
+]