morphic-hub 0.2.0__py3-none-any.whl

morphic/__init__.py

@@ -0,0 +1,18 @@
+"""Morphic - the embodied hub client library.
+
+    from morphic import Hub
+    hub = Hub()                                    # $MORPHIC_HUB, else the public hub https://hub.ruliax.com
+    triad = hub.pull("morphic/go2-trot")
+    run = triad.simulate(world="ice", seconds=5)   # needs `pip install "morphic-hub[sim]"` (MuJoCo)
+
+Physics (morphic.sim / morphic.gap / morphic.brain) imports MuJoCo lazily, so the
+HTTP client, telemetry tools and driver codecs work on machines without it.
+"""
+from .triad import Triad, TriadError, load_manifest  # noqa: F401
+from .hub import Hub, HubError  # noqa: F401
+from .telemetry import TelemetryRecorder, load_telemetry, save_telemetry, validate_telemetry  # noqa: F401
+from . import deploy, drivers  # noqa: F401
+
+__version__ = "0.2.0"
+__all__ = ["Triad", "TriadError", "load_manifest", "Hub", "HubError", "TelemetryRecorder",
+           "load_telemetry", "save_telemetry", "validate_telemetry", "deploy", "drivers"]

morphic/brain.py

@@ -0,0 +1,226 @@
+"""Brain loading and helpers for writing policies.
+
+A brain is either a Python file exposing `class Policy` (see docs/TRIAD.md) or an
+ONNX network (`type: onnx`) driven by a declarative observation spec.
+"""
+from __future__ import annotations
+
+import importlib.util
+import math
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+import numpy as np
+
+from .triad import Triad, TriadError
+
+# --------------------------------------------------------------------------- utils
+
+
+def quat_to_rotmat(q: Sequence[float]) -> np.ndarray:
+    """MuJoCo (w, x, y, z) quaternion -> 3x3 rotation matrix."""
+    w, x, y, z = q
+    return np.array([
+        [1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)],
+        [2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)],
+        [2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)],
+    ])
+
+
+def quat_to_euler(q: Sequence[float]) -> tuple[float, float, float]:
+    """MuJoCo (w, x, y, z) quaternion -> (roll, pitch, yaw) in radians."""
+    w, x, y, z = q
+    roll = math.atan2(2 * (w * x + y * z), 1 - 2 * (x * x + y * y))
+    s = max(-1.0, min(1.0, 2 * (w * y - z * x)))
+    pitch = math.asin(s)
+    yaw = math.atan2(2 * (w * z + x * y), 1 - 2 * (y * y + z * z))
+    return roll, pitch, yaw
+
+
+def gravity_in_body(q: Sequence[float]) -> np.ndarray:
+    """Unit gravity vector expressed in the body frame (what an IMU 'feels' when static)."""
+    return quat_to_rotmat(q).T @ np.array([0.0, 0.0, -1.0])
+
+
+class PolicyBase:
+    """Optional convenience base class for Python brains.
+
+    Gives name->index lookups for joints/actuators and a PD helper. Brains are free
+    to ignore it — the engine only needs `reset`, `act` and (optionally) `status`.
+    """
+
+    def __init__(self, model, spec: dict[str, Any]):
+        import mujoco
+
+        self.spec = spec or {}
+        self.params: dict[str, Any] = dict(self.spec.get("params") or {})
+        self.mj = mujoco
+        self.nu = model.nu
+        self.free_base = model.njnt > 0 and model.jnt_type[0] == mujoco.mjtJoint.mjJNT_FREE
+        self.actuator_names = [mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_ACTUATOR, i) for i in range(model.nu)]
+        # For joint-transmission actuators: the qpos / dof address of the driven joint.
+        self.act_qpos = np.full(model.nu, -1, dtype=int)
+        self.act_dof = np.full(model.nu, -1, dtype=int)
+        for i in range(model.nu):
+            if model.actuator_trntype[i] == mujoco.mjtTrn.mjTRN_JOINT:
+                j = model.actuator_trnid[i, 0]
+                self.act_qpos[i] = model.jnt_qposadr[j]
+                self.act_dof[i] = model.jnt_dofadr[j]
+        self.ctrl_lo = model.actuator_ctrlrange[:, 0].copy()
+        self.ctrl_hi = model.actuator_ctrlrange[:, 1].copy()
+        limited = model.actuator_ctrllimited.astype(bool)
+        self.ctrl_lo[~limited] = -np.inf
+        self.ctrl_hi[~limited] = np.inf
+
+    # ---- lookups
+    def joint_qpos(self, model, name: str) -> int:
+        j = self.mj.mj_name2id(model, self.mj.mjtObj.mjOBJ_JOINT, name)
+        if j < 0:
+            raise KeyError(f"joint {name!r} not in model")
+        return int(model.jnt_qposadr[j])
+
+    def joint_dof(self, model, name: str) -> int:
+        j = self.mj.mj_name2id(model, self.mj.mjtObj.mjOBJ_JOINT, name)
+        if j < 0:
+            raise KeyError(f"joint {name!r} not in model")
+        return int(model.jnt_dofadr[j])
+
+    def keyframe(self, model, name: str = "home") -> tuple[np.ndarray, np.ndarray] | None:
+        k = self.mj.mj_name2id(model, self.mj.mjtObj.mjOBJ_KEY, name)
+        if k < 0:
+            return None
+        return model.key_qpos[k].copy(), model.key_ctrl[k].copy()
+
+    # ---- state helpers
+    def actuated_pos(self, data) -> np.ndarray:
+        return data.qpos[self.act_qpos]
+
+    def actuated_vel(self, data) -> np.ndarray:
+        return data.qvel[self.act_dof]
+
+    def base_quat(self, data) -> np.ndarray:
+        return data.qpos[3:7] if self.free_base else np.array([1.0, 0.0, 0.0, 0.0])
+
+    def base_pos(self, data) -> np.ndarray:
+        return data.qpos[0:3] if self.free_base else np.zeros(3)
+
+    def base_angvel(self, data) -> np.ndarray:
+        return data.qvel[3:6] if self.free_base else np.zeros(3)
+
+    def base_linvel(self, data) -> np.ndarray:
+        return data.qvel[0:3] if self.free_base else np.zeros(3)
+
+    def pd(self, data, q_target: np.ndarray, kp, kd, qd_target: np.ndarray | None = None) -> np.ndarray:
+        """Joint-space PD torque for joint-transmission actuators."""
+        q = self.actuated_pos(data)
+        qd = self.actuated_vel(data)
+        if qd_target is None:
+            qd_target = np.zeros_like(qd)
+        return kp * (q_target - q) - kd * (qd - qd_target)
+
+    def clip(self, ctrl: np.ndarray) -> np.ndarray:
+        return np.clip(ctrl, self.ctrl_lo, self.ctrl_hi)
+
+    # ---- defaults
+    def reset(self, model, data) -> None:
+        kf = self.keyframe(model, "home")
+        if kf is not None:
+            data.qpos[:] = kf[0]
+            data.ctrl[:] = kf[1]
+
+    def status(self, model, data) -> dict[str, Any]:
+        return {"ok": True}
+
+
+# --------------------------------------------------------------------------- ONNX
+
+
+class OnnxPolicy(PolicyBase):
+    """Neural policy stored as ONNX. Observation = concatenation of the named blocks in
+    `spec.observation` (joint_pos, joint_vel, base_quat, base_angvel, base_linvel,
+    gravity, last_action, phase); output = ctrl (optionally scaled by `params.action_scale`
+    and offset by the home keyframe when `params.action_is_delta` is true)."""
+
+    def __init__(self, model, spec: dict[str, Any], path: Path):
+        super().__init__(model, spec)
+        try:
+            import onnxruntime as ort  # type: ignore
+        except ImportError as e:  # pragma: no cover
+            raise TriadError("brain type 'onnx' needs `pip install onnxruntime`") from e
+        self.session = ort.InferenceSession(str(path), providers=["CPUExecutionProvider"])
+        self.input_name = self.session.get_inputs()[0].name
+        self.blocks = list(spec.get("observation") or ["joint_pos", "joint_vel"])
+        self.last_action = np.zeros(model.nu, dtype=np.float32)
+        self.action_scale = float(self.params.get("action_scale", 1.0))
+        self.action_is_delta = bool(self.params.get("action_is_delta", False))
+        kf = self.keyframe(model, "home")
+        self.default_ctrl = kf[1] if kf is not None else np.zeros(model.nu)
+        self.period = float(self.params.get("gait_period", 0.5))
+
+    def observe(self, data, t: float) -> np.ndarray:
+        parts = []
+        for b in self.blocks:
+            if b == "joint_pos":
+                parts.append(self.actuated_pos(data))
+            elif b == "joint_vel":
+                parts.append(self.actuated_vel(data))
+            elif b == "base_quat":
+                parts.append(self.base_quat(data))
+            elif b == "base_angvel":
+                parts.append(self.base_angvel(data))
+            elif b == "base_linvel":
+                parts.append(self.base_linvel(data))
+            elif b == "gravity":
+                parts.append(gravity_in_body(self.base_quat(data)))
+            elif b == "last_action":
+                parts.append(self.last_action)
+            elif b == "phase":
+                ph = 2 * math.pi * t / self.period
+                parts.append(np.array([math.sin(ph), math.cos(ph)]))
+            else:
+                raise TriadError(f"unknown observation block {b!r}")
+        return np.concatenate(parts).astype(np.float32)
+
+    def act(self, model, data, t: float) -> np.ndarray:
+        obs = self.observe(data, t)[None, :]
+        out = self.session.run(None, {self.input_name: obs})[0][0].astype(np.float64)
+        self.last_action = out.astype(np.float32)
+        ctrl = out * self.action_scale
+        if self.action_is_delta:
+            ctrl = ctrl + self.default_ctrl
+        return self.clip(ctrl)
+
+
+# --------------------------------------------------------------------------- loader
+
+
+def load_policy(triad: Triad, model):
+    """Instantiate the repo's brain for `model` (a compiled world)."""
+    spec = triad.brain
+    entry = triad.brain_entry
+    if not entry.exists():
+        raise TriadError(f"{triad.id}: brain entry {entry} not found")
+    kind = spec.get("type", "python")
+    if kind == "onnx":
+        return OnnxPolicy(model, spec, entry)
+    if kind != "python":
+        raise TriadError(f"{triad.id}: unsupported brain type {kind!r}")
+
+    mod_name = "morphic_brain_" + triad.id.replace("/", "_").replace("-", "_")
+    mspec = importlib.util.spec_from_file_location(mod_name, entry)
+    if mspec is None or mspec.loader is None:  # pragma: no cover
+        raise TriadError(f"cannot import brain {entry}")
+    module = importlib.util.module_from_spec(mspec)
+    sys.modules[mod_name] = module
+    mspec.loader.exec_module(module)
+    cls = getattr(module, "Policy", None)
+    if cls is None:
+        raise TriadError(f"{entry}: must define class Policy")
+    policy = cls(model, spec)
+    for attr in ("reset", "act"):
+        if not callable(getattr(policy, attr, None)):
+            raise TriadError(f"{entry}: Policy must implement {attr}()")
+    if not callable(getattr(policy, "status", None)):
+        policy.status = lambda model, data: {"ok": True}  # type: ignore[attr-defined]
+    return policy

morphic/cli.py

@@ -0,0 +1,418 @@
+"""``morphic`` — command-line interface (argparse only).
+
+    morphic ls
+    morphic pull morphic/go2-trot
+    morphic sim morphic/go2-trot --world ice --seconds 5 --out run.json
+    morphic deploy morphic/so-arm100-pick --driver feetech --port COM4 --record run.json
+    morphic gap morphic/so-arm100-pick run.json
+    morphic drivers arduino-sketch
+
+The hub URL comes from --hub, else $MORPHIC_HUB, else the public hub (https://hub.ruliax.com).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any, Callable, Sequence
+
+from . import __version__
+from .drivers import ARDUINO_SKETCH, DESCRIPTIONS, DRIVERS, DriverError, JointMap, make_driver
+from .hub import DEFAULT_URL, Hub, HubError, default_cache_dir
+from .telemetry import TelemetryError, load_telemetry
+from .triad import MANIFEST, Triad, TriadError
+
+
+class CLIError(Exception):
+    """User-facing failure; printed as ``error: ...`` with exit status 1."""
+
+
+# ---- repo resolution ---------------------------------------------------------------
+def registry_dirs(explicit: str | None = None) -> list[Path]:
+    """Candidate local registries: ``--registry``/``$MORPHIC_REGISTRY``, then ``hub/registry`` in cwd or its parents."""
+    out: list[Path] = []
+    for cand in (explicit, os.environ.get("MORPHIC_REGISTRY")):
+        if cand:
+            out.append(Path(cand))
+    cwd = Path.cwd()
+    for base in (cwd, *cwd.parents[:3]):
+        p = base / "hub" / "registry"
+        if p.is_dir():
+            out.append(p)
+    return out
+
+
+def resolve_repo(spec: str, hub_url: str, registry: str | None = None, pull: bool = True) -> Triad:
+    """Directory → local registry → pull cache → ``morphic pull`` from the hub."""
+    p = Path(spec)
+    if p.is_dir() and (p / MANIFEST).exists():
+        return Triad(p)
+    for reg in registry_dirs(registry):
+        if (reg / spec / MANIFEST).exists():
+            return Triad(reg / spec)
+    cached = default_cache_dir() / spec
+    if (cached / MANIFEST).exists():
+        return Triad(cached)
+    if "/" not in spec:
+        raise CLIError(f"'{spec}' is neither a directory nor an owner/name repo id")
+    if not pull:
+        raise CLIError(f"repo {spec!r} not found locally (run `morphic pull {spec}`)")
+    print(f"pulling {spec} from {hub_url} ...")
+    return Hub(hub_url).pull(spec)
+
+
+# ---- output helpers ---------------------------------------------------------------
+def fmt(v: Any, digits: int = 3) -> str:
+    if v is None:
+        return "-"
+    if isinstance(v, bool):
+        return "yes" if v else "no"
+    if isinstance(v, float):
+        return f"{v:.{digits}f}"
+    return str(v)
+
+
+def table(rows: Sequence[Sequence[Any]], headers: Sequence[str]) -> str:
+    cells = [[fmt(c) for c in r] for r in rows]
+    widths = [max(len(h), *(len(r[i]) for r in cells)) if cells else len(h) for i, h in enumerate(headers)]
+    line = "  ".join(h.ljust(w) for h, w in zip(headers, widths))
+    out = [line, "  ".join("-" * w for w in widths)]
+    out += ["  ".join(c.ljust(w) for c, w in zip(r, widths)) for r in cells]
+    return "\n".join(out)
+
+
+def print_gap_report(report: dict[str, Any]) -> None:
+    agg = report.get("aggregate") or {}
+    print(f"Sim-Gap report  {report.get('repo', '?')} · world {report.get('world', '?')} · "
+          f"source {report.get('source', '?')} · run {report.get('run_id', '-')}")
+    print(f"score {fmt(report.get('sim_gap_score'), 1)} / 100   grade {report.get('grade', '-')}   "
+          f"rmse {fmt(agg.get('rmse_rad'))} rad   lag {fmt(agg.get('lag_ms'), 0)} ms   "
+          f"drift {fmt(agg.get('drift_rad'))} rad   {agg.get('samples', '-')} samples / {fmt(agg.get('duration_s'), 1)} s")
+    per_joint = report.get("per_joint") or []
+    if per_joint:
+        print()
+        print(table([[j.get("joint"), j.get("rmse_rad"), j.get("max_err_rad"), j.get("lag_ms"), j.get("gain")]
+                     for j in per_joint], ["joint", "rmse_rad", "max_err_rad", "lag_ms", "gain"]))
+    diagnosis = report.get("diagnosis") or []
+    if diagnosis:
+        print()
+        print("diagnosis:")
+        for line in diagnosis:
+            print(f"  - {line}")
+
+
+def _dump(obj: Any, path: str | None) -> None:
+    if path:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        Path(path).write_text(json.dumps(obj, separators=(",", ":")), encoding="utf-8")
+        print(f"wrote {path}")
+
+
+def _mujoco_available() -> bool:
+    try:
+        import mujoco  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+# ---- commands --------------------------------------------------------------------------
+def cmd_ls(args: argparse.Namespace) -> int:
+    try:
+        repos = Hub(args.hub).list()
+    except HubError as e:
+        regs = [r for r in registry_dirs(args.registry) if r.is_dir()]
+        if not regs:
+            raise
+        print(f"{e}\nlisting local registry {regs[0]} instead\n")
+        rows = []
+        for manifest in sorted(regs[0].glob(f"*/*/{MANIFEST}")):
+            try:
+                t = Triad(manifest.parent)
+            except TriadError:
+                continue
+            rows.append([t.id, t.category, t.body.get("name"), len(t.worlds), "-", "-"])
+        print(table(rows, ["repo", "category", "body", "worlds", "sim_gap", "robustness"]))
+        return 0
+    rows = []
+    for r in repos:
+        body, stats = r.get("body") or {}, r.get("stats") or {}
+        rows.append([r.get("id"), r.get("category"), body.get("name"), body.get("actuators"),
+                     len(r.get("worlds") or []), stats.get("sim_gap"), stats.get("robustness")])
+    print(table(rows, ["repo", "category", "body", "nu", "worlds", "sim_gap", "robustness"]))
+    print(f"\n{len(rows)} repos on {args.hub}")
+    return 0
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    t = resolve_repo(args.repo, args.hub, args.registry)
+    m = t.manifest
+    print(f"{t.id}  —  {t.title}")
+    if m.get("summary"):
+        print(m["summary"])
+    print(f"root      {t.root}")
+    print(f"category  {t.category}   tags {', '.join(m.get('tags') or []) or '-'}   license {m.get('license')}")
+    b, br = t.body, t.brain
+    print(f"body      {b.get('name')} ({b.get('format')}, {b.get('entry')})  by {b.get('manufacturer', '-')}"
+          f"  license {b.get('license', '-')}  grade {b.get('grade', '-')}")
+    print(f"brain     {br.get('name')} ({br.get('type')}, {br.get('entry')}) @ {t.control_hz:g} Hz  "
+          f"action: {br.get('action', '-')}")
+    print(f"worlds    {', '.join(t.worlds)}  (default {t.default_world})")
+    build = m.get("build") or {}
+    if build:
+        print(f"build     {build.get('kind', '-')}  bom {build.get('bom', '-')}  assembly {build.get('assembly', '-')}")
+    bom = t.bom()
+    if bom:
+        print(f"bom       {len(bom.get('items') or [])} items, est. {bom.get('total_estimate', '-')} {bom.get('currency', '')}")
+    deploy = m.get("deploy") or {}
+    if deploy:
+        print(f"deploy    driver {deploy.get('driver', '-')}  port {deploy.get('port', '-')}  "
+              f"baud {deploy.get('baud', '-')}  mapped actuators {len(deploy.get('map') or {})}")
+    if _mujoco_available():
+        try:
+            insp = t.inspect()
+        except Exception as e:  # inspection is best-effort: the body may not compile on this machine
+            print(f"\n(inspection unavailable: {e})")
+            return 0
+        print(f"\nnq {insp.get('nq')}  nv {insp.get('nv')}  nu {insp.get('nu')}  bodies {insp.get('nbody')}  "
+              f"mass {fmt(insp.get('mass_kg'), 2)} kg  timestep {insp.get('timestep')}  free base {fmt(insp.get('free_base'))}")
+        joints = insp.get("joints") or []
+        if joints:
+            print()
+            print(table([[j.get("name"), j.get("type"), fmt(j.get("range")), j.get("actuator")] for j in joints],
+                        ["joint", "type", "range", "actuator"]))
+        acts = insp.get("actuators") or []
+        if acts:
+            print()
+            print(table([[a.get("name"), a.get("type"), a.get("joint"), fmt(a.get("ctrlrange")), _gear(a.get("gear"))]
+                         for a in acts], ["actuator", "type", "joint", "ctrlrange", "gear"]))
+    return 0
+
+
+def _gear(gear: Any) -> Any:
+    """MuJoCo's 6-vector gear reduced to its first (transmission) component for display."""
+    if isinstance(gear, (list, tuple)):
+        return gear[0] if gear else None
+    return gear
+
+
+def cmd_pull(args: argparse.Namespace) -> int:
+    t = Hub(args.hub).pull(args.repo, dest=args.dest)
+    print(f"pulled {t.id} → {t.root}  ({len(t.files())} files)")
+    return 0
+
+
+def cmd_worlds(args: argparse.Namespace) -> int:
+    t = resolve_repo(args.repo, args.hub, args.registry)
+    rows = [[wid + (" *" if wid == t.default_world else ""), w.get("title"), w.get("file"), w.get("description")]
+            for wid, w in t.worlds.items()]
+    print(table(rows, ["world", "title", "file", "description"]))
+    return 0
+
+
+def cmd_sim(args: argparse.Namespace) -> int:
+    use_local = args.local or (args.remote is None and _mujoco_available())
+    if use_local:
+        t = resolve_repo(args.repo, args.hub, args.registry)
+        run = t.simulate(world=args.world, seconds=args.seconds)
+        where = f"local MuJoCo ({t.root})"
+    else:
+        url = args.remote if isinstance(args.remote, str) else args.hub
+        run = Hub(url).simulate(args.repo, world=args.world, seconds=args.seconds)
+        where = f"hub {url}"
+    s = run.get("summary") or {}
+    print(f"simulated {args.repo} · world {run.get('world')} · {run.get('seconds')} s · {len(run.get('frames') or [])} frames · {where}")
+    print(f"ok {fmt(s.get('ok'))}   score {fmt(s.get('score'))}   fell_at {fmt(s.get('fell_at'), 2)}   "
+          f"mean_speed {fmt(s.get('mean_speed'))} m/s   energy {fmt(s.get('energy_j'), 1)} J")
+    _dump(run, args.out)
+    return 0
+
+
+def _make_deploy_driver(args: argparse.Namespace, t: Triad) -> Any:
+    deploy_cfg = t.manifest.get("deploy") or {}
+    name = args.driver
+    if name == "mock":
+        kwargs: dict[str, Any] = {"triad": t, "world": args.world, "latency_ticks": args.latency,
+                                  "noise_std": args.noise}
+    elif name == "ros2":
+        kwargs = {"topic": args.topic or deploy_cfg.get("topic") or "/morphic/joint_commands",
+                  "dry_run": args.dry_run, "joint_map": JointMap.from_manifest(t.manifest)}
+    else:
+        port = args.port or deploy_cfg.get("port")
+        dry_run = args.dry_run or not port
+        if not port and not args.dry_run:
+            print("no --port given and no deploy.port in the manifest — running dry (frames are logged, not sent)")
+        kwargs = {"port": port, "dry_run": dry_run, "joint_map": JointMap.from_manifest(t.manifest)}
+        baud = args.baud or deploy_cfg.get("baud")
+        if baud:
+            kwargs["baud"] = int(baud)
+    return make_driver(name, **kwargs)
+
+
+def cmd_deploy(args: argparse.Namespace) -> int:
+    from . import deploy
+
+    t = resolve_repo(args.repo, args.hub, args.registry)
+    driver = _make_deploy_driver(args, t)
+    world = args.world or t.default_world
+    print(f"deploying {t.id} · brain {t.brain.get('name')} @ {t.control_hz:g} Hz · world {world} · driver {driver.name}")
+    result = deploy.run(t, driver, world=args.world, seconds=args.seconds, record=args.record, verbose=args.verbose)
+    st = result["status"]
+    print(f"done: {result['ticks']} ticks / {result['duration_s']:.2f} s (wall {result['wall_s']:.2f} s)   "
+          f"ok {fmt(st.get('ok', True))}")
+    extra = {k: v for k, v in st.items() if k != "ok"}
+    if extra:
+        print("status " + "  ".join(f"{k}={fmt(v)}" for k, v in extra.items()))
+    if result["log_tail"]:
+        print("\nlast packets on the wire:")
+        for rec in result["log_tail"]:
+            print("  " + _packet_line(rec))
+    if result["record"]:
+        print(f"\ntelemetry → {result['record']}   ({len(result['telemetry']['t'])} samples)")
+        print(f"next: morphic gap {args.repo} {result['record']}")
+    return 0
+
+
+def _packet_line(rec: dict[str, Any]) -> str:
+    kind = rec.get("kind", "?")
+    if "frame" in rec:
+        frame = rec["frame"]
+        return f"{kind:<14} {frame[:60]}{'…' if len(frame) > 60 else ''}"
+    if "applied" in rec:
+        return f"{kind:<14} tick {rec.get('tick')} t={rec.get('t')}  cmd {rec.get('cmd')}  applied {rec.get('applied')}"
+    if "data" in rec:
+        return f"{kind:<14} {rec.get('topic')} {rec.get('data')}"
+    return f"{kind:<14} " + "  ".join(f"{k}={v}" for k, v in rec.items() if k != "kind")
+
+
+def _report_local(t: Triad, telemetry: dict[str, Any]) -> dict[str, Any]:
+    try:
+        from .gap import score
+    except ImportError as e:
+        raise CLIError("local Sim-Gap scoring needs morphic.gap (and mujoco); drop --local to score on the hub") from e
+    return score(t, telemetry, world=telemetry.get("world"))
+
+
+def cmd_gap(args: argparse.Namespace) -> int:
+    telemetry = load_telemetry(args.run)
+    if args.local:
+        t = resolve_repo(args.repo, args.hub, args.registry)
+        report = _report_local(t, telemetry)
+    else:
+        report = Hub(args.hub).push_telemetry(args.repo, args.run)
+    print_gap_report(report)
+    _dump(report, args.out)
+    return 0
+
+
+def cmd_push(args: argparse.Namespace) -> int:
+    load_telemetry(args.run)  # fail fast with a clear message before uploading
+    report = Hub(args.hub).push_telemetry(args.repo, args.run)
+    print(f"uploaded {args.run} to {args.hub}")
+    print_gap_report(report)
+    return 0
+
+
+def cmd_drivers(args: argparse.Namespace) -> int:
+    if args.what == "arduino-sketch":
+        print(ARDUINO_SKETCH)
+        return 0
+    print(table([[name, DESCRIPTIONS.get(name, "")] for name in DRIVERS], ["driver", "description"]))
+    print("\nusage: morphic deploy <repo> --driver <name> [--port COM3] [--dry-run] [--record run.json]")
+    print("map model units to device units with a `deploy:` section in morphic.yaml (see python/README.md)")
+    return 0
+
+
+# ---- parser --------------------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="morphic", description="Morphic — pull, simulate and deploy Triad repos.")
+    p.add_argument("--hub", default=DEFAULT_URL, help="hub URL (default: $MORPHIC_HUB, else the public hub baked into morphic.hub.DEFAULT_URL)")
+    p.add_argument("--registry", default=None, help="local registry dir (env MORPHIC_REGISTRY)")
+    p.add_argument("--version", action="version", version=f"morphic {__version__}")
+    sub = p.add_subparsers(dest="command", metavar="<command>")
+    sub.required = True
+
+    sub.add_parser("ls", help="list repos on the hub").set_defaults(func=cmd_ls)
+
+    s = sub.add_parser("info", help="show a repo (manifest, joints, actuators, BOM)")
+    s.add_argument("repo")
+    s.set_defaults(func=cmd_info)
+
+    s = sub.add_parser("pull", help="download a Triad into the local cache")
+    s.add_argument("repo")
+    s.add_argument("--dest", default=None, help="target directory (default ~/.morphic/cache/<owner>/<name>)")
+    s.set_defaults(func=cmd_pull)
+
+    s = sub.add_parser("worlds", help="list a repo's world variants")
+    s.add_argument("repo")
+    s.set_defaults(func=cmd_worlds)
+
+    s = sub.add_parser("sim", help="roll the brain out in a world")
+    s.add_argument("repo")
+    s.add_argument("--world", "-w", default=None)
+    s.add_argument("--seconds", "-s", type=float, default=5.0)
+    s.add_argument("--out", "-o", default=None, help="write the full trajectory JSON here")
+    g = s.add_mutually_exclusive_group()
+    g.add_argument("--local", action="store_true", help="simulate with local MuJoCo (default when installed)")
+    g.add_argument("--hub", dest="remote", nargs="?", const=True, default=None, metavar="URL",
+                   help="simulate on the hub (optionally at URL)")
+    s.set_defaults(func=cmd_sim)
+
+    s = sub.add_parser("deploy", help="run the brain through a hardware driver")
+    s.add_argument("repo")
+    s.add_argument("--driver", "-d", required=True, choices=list(DRIVERS))
+    s.add_argument("--port", "-p", default=None, help="serial port (COM3, /dev/ttyACM0); default from manifest deploy.port")
+    s.add_argument("--baud", type=int, default=None, help="serial baud rate; default from manifest or driver")
+    s.add_argument("--topic", default=None, help="ros2: command topic")
+    s.add_argument("--world", "-w", default=None)
+    s.add_argument("--seconds", "-s", type=float, default=5.0)
+    s.add_argument("--record", "-r", default=None, help="write morphic-telemetry/1 JSON here")
+    s.add_argument("--dry-run", action="store_true", help="encode packets but never open a port / publish")
+    s.add_argument("--latency", type=int, default=2, help="mock: command latency in control ticks")
+    s.add_argument("--noise", type=float, default=0.003, help="mock: encoder noise std (rad)")
+    s.add_argument("--verbose", "-v", action="store_true")
+    s.set_defaults(func=cmd_deploy)
+
+    s = sub.add_parser("gap", help="score a telemetry run against the simulator (Sim-Gap)")
+    s.add_argument("repo")
+    s.add_argument("run", help="telemetry JSON from `morphic deploy --record`")
+    s.add_argument("--local", action="store_true", help="score locally with morphic.gap instead of uploading")
+    s.add_argument("--out", "-o", default=None, help="write the report JSON here")
+    s.set_defaults(func=cmd_gap)
+
+    s = sub.add_parser("push", help="upload a telemetry run to the hub")
+    s.add_argument("repo")
+    s.add_argument("run")
+    s.set_defaults(func=cmd_push)
+
+    s = sub.add_parser("drivers", help="list drivers, or print firmware: `drivers arduino-sketch`")
+    s.add_argument("what", nargs="?", choices=["arduino-sketch"], default=None)
+    s.set_defaults(func=cmd_drivers)
+    return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    # Windows consoles default to a legacy code page; make sure arrows and middle dots print.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except (ValueError, OSError):
+                pass
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    func: Callable[[argparse.Namespace], int] = args.func
+    try:
+        return func(args)
+    except (CLIError, HubError, TriadError, DriverError, TelemetryError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("interrupted", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())