morphic-hub 0.2.0__tar.gz

morphic_hub-0.2.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: morphic-hub
+Version: 0.2.0
+Summary: Morphic - the embodied hub. Pull Triad repos (Brain + Body + World) from a Morphic hub, simulate them locally, deploy brains to hardware.
+License: Apache-2.0
+Project-URL: Hub, https://hub.ruliax.com
+Project-URL: Source, https://github.com/Ruliax-AI/Morphic
+Keywords: robotics,mujoco,simulation,physical-ai,sim2real
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyyaml>=6
+Requires-Dist: httpx>=0.27
+Provides-Extra: sim
+Requires-Dist: mujoco<3.13,>=3.12; extra == "sim"
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: mujoco<3.13,>=3.12; extra == "dev"
+
+# `morphic` — the Python client, driver layer and CLI
+
+Pull a Triad (Brain + Body + World) from a Morphic hub, simulate it locally, deploy the brain
+to real actuators through one driver layer, and send the telemetry back for a Sim-Gap score.
+
+Licence: Apache-2.0. Dependencies are all free/OSS: numpy (BSD-3), PyYAML (MIT),
+httpx (BSD-3), MuJoCo (Apache-2.0, optional), pyserial (BSD-3, optional), pytest (MIT, dev).
+
+## Quickstart
+
+```bash
+pip install "morphic-hub[sim]"       # client + CLI + MuJoCo (drop [sim] for the pure HTTP client)
+
+morphic ls                              # what's on the hub (https://hub.ruliax.com by default)
+morphic info morphic/go2-trot           # manifest, joints, actuators, BOM
+morphic pull morphic/go2-trot           # -> ~/.morphic/cache/morphic/go2-trot   ($MORPHIC_HOME overrides ~/.morphic)
+morphic sim  morphic/go2-trot --world ice --seconds 5 --out run.json
+```
+
+The distribution is `morphic-hub` (the name `morphic` on PyPI belongs to an unrelated project);
+the import and the command are both `morphic`. Every command talks to the public hub unless you
+pass `--hub URL` or set `$MORPHIC_HUB` (e.g. `http://127.0.0.1:8000` for a local `python -m morphic_hub`).
+
+`<repo>` is resolved in this order: an existing directory → `hub/registry/<repo>`
+(relative to the cwd or `$MORPHIC_REGISTRY`) → the pull cache → `morphic pull` from the hub.
+
+```python
+from morphic import Hub
+hub = Hub()                                           # or Hub("http://127.0.0.1:8000")
+triad = hub.pull("morphic/go2-trot")
+run = triad.simulate(world="ice", seconds=5)          # local MuJoCo
+report = hub.push_telemetry("morphic/go2-trot", "hw.json")
+```
+
+## Advanced: the driver layer — one policy output, any actuator brand
+
+A policy emits a control vector in *model units* (radians for position servos,
+N·m for torque motors — whatever the MJCF actuators expect). A `Driver` turns that
+into wire packets; a `JointMap` does the per-actuator unit conversion. Swapping
+hardware is swapping the driver:
+
+```python
+from morphic import Triad, deploy
+from morphic.drivers import FeetechDriver, DynamixelDriver, JointMap
+
+triad = Triad("~/.morphic/cache/morphic/so-arm100-pick")
+jm = JointMap.from_manifest(triad.manifest)                 # ids / signs / offsets from morphic.yaml
+
+arm  = FeetechDriver("COM4", joint_map=jm)                  # STS3215 bus (SO-ARM100)
+deploy.run(triad, arm, seconds=5, record="so100_feetech.json")
+
+arm  = DynamixelDriver("COM5", joint_map=jm)                # same brain, XL330 bus instead
+deploy.run(triad, arm, seconds=5, record="so100_dynamixel.json")
+```
+
+Nothing about the brain changed. The deploy loop keeps the nominal simulation as a
+digital twin: when the driver reports encoder state, the twin is corrected to it
+(it is the state estimator); when the device is write-only, the twin runs open loop.
+
+| driver      | class             | wire format                                                     | feedback |
+|-------------|-------------------|-----------------------------------------------------------------|----------|
+| `mock`      | `MockDriver`      | none — perturbed MuJoCo twin with command latency + encoder noise | yes |
+| `serial`    | `SerialPWMDriver` | `'M' n {id u8, pwm_us u16 LE}… xor` to an Arduino/ESP32/STM32 running `morphic drivers arduino-sketch` | no |
+| `feetech`   | `FeetechDriver`   | Feetech STS protocol, SYNC WRITE goal position (0x2A), 4096 ticks/rev | present position + speed (0x38) |
+| `dynamixel` | `DynamixelDriver` | DYNAMIXEL Protocol 2.0, SYNC WRITE goal position (116), CRC-16   | present velocity + position (128..135) |
+| `ros2`      | `ROS2Driver`      | `std_msgs/Float64MultiArray` on `/morphic/joint_commands`          | `sensor_msgs/JointState` |
+
+Every driver honours `dry_run=True` (and the serial/ROS drivers fall back to it when
+pyserial/rclpy are absent): packets are encoded exactly as they would be sent and kept
+in `driver.log` as hex, so `morphic deploy … --dry-run` shows "what went over the wire"
+with nothing plugged in. The drivers have been verified at the protocol level and against
+the emulator, not on physical buses.
+
+Feedback contract: `read()` returns `{"qpos": (nq,), "qvel": (nv,)}` in model units with
+`NaN` for anything the hardware does not measure, or `None` for write-only devices.
+
+### The `MockDriver` (hardware emulator)
+
+A second MuJoCo instance compiled with deliberately different parameters — by default
+`{damping ×1.6, frictionloss ×2.0, mass ×1.08, actuator gain ×0.85, floor friction ×0.7}` —
+plus a 2-tick command FIFO and 3 mrad Gaussian encoder noise. Deploying against it
+yields telemetry with a realistic sim-to-real gap, which is what the Sim-Gap scorer
+is for.
+
+## `deploy:` section of `morphic.yaml`
+
+Optional. Tells `morphic deploy` how the model's actuators map onto physical devices.
+
+```yaml
+deploy:
+  driver: feetech               # mock | serial | feetech | dynamixel | ros2   (default for --driver)
+  port: COM4                    # serial port; --port overrides
+  baud: 1000000                 # driver default if omitted (feetech/dynamixel 1 000 000, serial 115200)
+  topic: /morphic/joint_commands   # ros2 only
+  map:                          # per actuator (MJCF actuator name); missing actuators get identity entries
+    shoulder_pan:  {id: 1, sign: 1,  offset: 2048}
+    shoulder_lift: {id: 2, sign: -1, offset: 2048, min: 300, max: 3800}
+    elbow_flex:    3            # shorthand: just the bus id
+```
+
+Entry keys (all optional except that each actuator needs an `id`):
+
+| key      | meaning                                                   | default            |
+|----------|-----------------------------------------------------------|--------------------|
+| `id`     | bus / channel id                                          | 1..n in actuator order |
+| `sign`   | `1` or `-1` — flips direction                             | `1`                |
+| `scale`  | device units per model unit                               | driver: ticks/rad (`4096/2π`) for servo buses, µs/rad (`1000/π`) for PWM, `1` for ROS 2 |
+| `offset` | device units at model zero                                | driver: `2048` ticks, `1500` µs, `0` |
+| `min`, `max` | clamp in device units                                 | driver: `0..4095` ticks, `1000..2000` µs |
+| `unit`   | model unit of the actuator: `rad`, `m`, `N`, `Nm`, `norm`  | `rad`              |
+
+Conversion: `device = clamp(sign · value · scale + offset, min, max)`; readings come back
+through the inverse. Manifest entries override driver defaults, which override identity.
+
+## Telemetry
+
+`morphic deploy --record run.json` writes `morphic-telemetry/1` (schema in
+`docs/TRIAD.md`): joint positions/velocities of the hinge/slide joints, the commanded
+`ctrl`, the floating-base pose when there is one, and `meta` describing the driver
+(for the emulator: the perturbation it used). `morphic gap <repo> run.json` uploads it
+and prints the Sim-Gap report; `--local` scores with `morphic.gap` instead.
+
+```python
+from morphic.telemetry import TelemetryRecorder, load_telemetry, validate_telemetry
+rec = TelemetryRecorder("owner/name", "flat", joints, actuators, dt=0.02, source="hardware", driver="feetech")
+rec.add(t, qpos, qvel, ctrl)
+rec.save("run.json")
+```
+
+## CLI reference
+
+```
+morphic [--hub URL] [--registry DIR] <command>
+  ls                               list repos (falls back to the local registry when the hub is down)
+  info <repo>                      manifest, joints, actuators, BOM, deploy section
+  pull <repo> [--dest DIR]         download a Triad
+  worlds <repo>                    world variants
+  sim <repo> [--world W] [--seconds S] [--out run.json] [--local|--hub]
+  deploy <repo> --driver mock|serial|feetech|dynamixel|ros2 [--port COM3] [--baud N]
+         [--world W] [--seconds S] [--record run.json] [--dry-run] [--latency T] [--noise STD] [-v]
+  gap <repo> run.json [--local] [--out report.json]
+  push <repo> run.json
+  drivers [arduino-sketch]
+```
+
+## Tests
+
+```bash
+cd python && python -m pytest -q
+```
+
+`tests/` builds a one-joint Triad on the fly, so the suite runs without the registry
+and without hardware. Packet encoders are checked against the vendors' documented
+example packets (ROBOTIS e-manual for DYNAMIXEL Protocol 2.0).

morphic_hub-0.2.0/README.md

@@ -0,0 +1,154 @@
+# `morphic` — the Python client, driver layer and CLI
+
+Pull a Triad (Brain + Body + World) from a Morphic hub, simulate it locally, deploy the brain
+to real actuators through one driver layer, and send the telemetry back for a Sim-Gap score.
+
+Licence: Apache-2.0. Dependencies are all free/OSS: numpy (BSD-3), PyYAML (MIT),
+httpx (BSD-3), MuJoCo (Apache-2.0, optional), pyserial (BSD-3, optional), pytest (MIT, dev).
+
+## Quickstart
+
+```bash
+pip install "morphic-hub[sim]"       # client + CLI + MuJoCo (drop [sim] for the pure HTTP client)
+
+morphic ls                              # what's on the hub (https://hub.ruliax.com by default)
+morphic info morphic/go2-trot           # manifest, joints, actuators, BOM
+morphic pull morphic/go2-trot           # -> ~/.morphic/cache/morphic/go2-trot   ($MORPHIC_HOME overrides ~/.morphic)
+morphic sim  morphic/go2-trot --world ice --seconds 5 --out run.json
+```
+
+The distribution is `morphic-hub` (the name `morphic` on PyPI belongs to an unrelated project);
+the import and the command are both `morphic`. Every command talks to the public hub unless you
+pass `--hub URL` or set `$MORPHIC_HUB` (e.g. `http://127.0.0.1:8000` for a local `python -m morphic_hub`).
+
+`<repo>` is resolved in this order: an existing directory → `hub/registry/<repo>`
+(relative to the cwd or `$MORPHIC_REGISTRY`) → the pull cache → `morphic pull` from the hub.
+
+```python
+from morphic import Hub
+hub = Hub()                                           # or Hub("http://127.0.0.1:8000")
+triad = hub.pull("morphic/go2-trot")
+run = triad.simulate(world="ice", seconds=5)          # local MuJoCo
+report = hub.push_telemetry("morphic/go2-trot", "hw.json")
+```
+
+## Advanced: the driver layer — one policy output, any actuator brand
+
+A policy emits a control vector in *model units* (radians for position servos,
+N·m for torque motors — whatever the MJCF actuators expect). A `Driver` turns that
+into wire packets; a `JointMap` does the per-actuator unit conversion. Swapping
+hardware is swapping the driver:
+
+```python
+from morphic import Triad, deploy
+from morphic.drivers import FeetechDriver, DynamixelDriver, JointMap
+
+triad = Triad("~/.morphic/cache/morphic/so-arm100-pick")
+jm = JointMap.from_manifest(triad.manifest)                 # ids / signs / offsets from morphic.yaml
+
+arm  = FeetechDriver("COM4", joint_map=jm)                  # STS3215 bus (SO-ARM100)
+deploy.run(triad, arm, seconds=5, record="so100_feetech.json")
+
+arm  = DynamixelDriver("COM5", joint_map=jm)                # same brain, XL330 bus instead
+deploy.run(triad, arm, seconds=5, record="so100_dynamixel.json")
+```
+
+Nothing about the brain changed. The deploy loop keeps the nominal simulation as a
+digital twin: when the driver reports encoder state, the twin is corrected to it
+(it is the state estimator); when the device is write-only, the twin runs open loop.
+
+| driver      | class             | wire format                                                     | feedback |
+|-------------|-------------------|-----------------------------------------------------------------|----------|
+| `mock`      | `MockDriver`      | none — perturbed MuJoCo twin with command latency + encoder noise | yes |
+| `serial`    | `SerialPWMDriver` | `'M' n {id u8, pwm_us u16 LE}… xor` to an Arduino/ESP32/STM32 running `morphic drivers arduino-sketch` | no |
+| `feetech`   | `FeetechDriver`   | Feetech STS protocol, SYNC WRITE goal position (0x2A), 4096 ticks/rev | present position + speed (0x38) |
+| `dynamixel` | `DynamixelDriver` | DYNAMIXEL Protocol 2.0, SYNC WRITE goal position (116), CRC-16   | present velocity + position (128..135) |
+| `ros2`      | `ROS2Driver`      | `std_msgs/Float64MultiArray` on `/morphic/joint_commands`          | `sensor_msgs/JointState` |
+
+Every driver honours `dry_run=True` (and the serial/ROS drivers fall back to it when
+pyserial/rclpy are absent): packets are encoded exactly as they would be sent and kept
+in `driver.log` as hex, so `morphic deploy … --dry-run` shows "what went over the wire"
+with nothing plugged in. The drivers have been verified at the protocol level and against
+the emulator, not on physical buses.
+
+Feedback contract: `read()` returns `{"qpos": (nq,), "qvel": (nv,)}` in model units with
+`NaN` for anything the hardware does not measure, or `None` for write-only devices.
+
+### The `MockDriver` (hardware emulator)
+
+A second MuJoCo instance compiled with deliberately different parameters — by default
+`{damping ×1.6, frictionloss ×2.0, mass ×1.08, actuator gain ×0.85, floor friction ×0.7}` —
+plus a 2-tick command FIFO and 3 mrad Gaussian encoder noise. Deploying against it
+yields telemetry with a realistic sim-to-real gap, which is what the Sim-Gap scorer
+is for.
+
+## `deploy:` section of `morphic.yaml`
+
+Optional. Tells `morphic deploy` how the model's actuators map onto physical devices.
+
+```yaml
+deploy:
+  driver: feetech               # mock | serial | feetech | dynamixel | ros2   (default for --driver)
+  port: COM4                    # serial port; --port overrides
+  baud: 1000000                 # driver default if omitted (feetech/dynamixel 1 000 000, serial 115200)
+  topic: /morphic/joint_commands   # ros2 only
+  map:                          # per actuator (MJCF actuator name); missing actuators get identity entries
+    shoulder_pan:  {id: 1, sign: 1,  offset: 2048}
+    shoulder_lift: {id: 2, sign: -1, offset: 2048, min: 300, max: 3800}
+    elbow_flex:    3            # shorthand: just the bus id
+```
+
+Entry keys (all optional except that each actuator needs an `id`):
+
+| key      | meaning                                                   | default            |
+|----------|-----------------------------------------------------------|--------------------|
+| `id`     | bus / channel id                                          | 1..n in actuator order |
+| `sign`   | `1` or `-1` — flips direction                             | `1`                |
+| `scale`  | device units per model unit                               | driver: ticks/rad (`4096/2π`) for servo buses, µs/rad (`1000/π`) for PWM, `1` for ROS 2 |
+| `offset` | device units at model zero                                | driver: `2048` ticks, `1500` µs, `0` |
+| `min`, `max` | clamp in device units                                 | driver: `0..4095` ticks, `1000..2000` µs |
+| `unit`   | model unit of the actuator: `rad`, `m`, `N`, `Nm`, `norm`  | `rad`              |
+
+Conversion: `device = clamp(sign · value · scale + offset, min, max)`; readings come back
+through the inverse. Manifest entries override driver defaults, which override identity.
+
+## Telemetry
+
+`morphic deploy --record run.json` writes `morphic-telemetry/1` (schema in
+`docs/TRIAD.md`): joint positions/velocities of the hinge/slide joints, the commanded
+`ctrl`, the floating-base pose when there is one, and `meta` describing the driver
+(for the emulator: the perturbation it used). `morphic gap <repo> run.json` uploads it
+and prints the Sim-Gap report; `--local` scores with `morphic.gap` instead.
+
+```python
+from morphic.telemetry import TelemetryRecorder, load_telemetry, validate_telemetry
+rec = TelemetryRecorder("owner/name", "flat", joints, actuators, dt=0.02, source="hardware", driver="feetech")
+rec.add(t, qpos, qvel, ctrl)
+rec.save("run.json")
+```
+
+## CLI reference
+
+```
+morphic [--hub URL] [--registry DIR] <command>
+  ls                               list repos (falls back to the local registry when the hub is down)
+  info <repo>                      manifest, joints, actuators, BOM, deploy section
+  pull <repo> [--dest DIR]         download a Triad
+  worlds <repo>                    world variants
+  sim <repo> [--world W] [--seconds S] [--out run.json] [--local|--hub]
+  deploy <repo> --driver mock|serial|feetech|dynamixel|ros2 [--port COM3] [--baud N]
+         [--world W] [--seconds S] [--record run.json] [--dry-run] [--latency T] [--noise STD] [-v]
+  gap <repo> run.json [--local] [--out report.json]
+  push <repo> run.json
+  drivers [arduino-sketch]
+```
+
+## Tests
+
+```bash
+cd python && python -m pytest -q
+```
+
+`tests/` builds a one-joint Triad on the fly, so the suite runs without the registry
+and without hardware. Packet encoders are checked against the vendors' documented
+example packets (ROBOTIS e-manual for DYNAMIXEL Protocol 2.0).

morphic_hub-0.2.0/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_hub-0.2.0/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