examples: runnable external adapter (entry-point hub demo)

A standalone pip package (wm-example-adapter) that adds a GPU-free histogram
"surprise" backend purely via the world_model_ros2.adapters entry point — no
edits to the main repo. Copy-paste template for shipping your own World Model.

- wm_example_adapter: numpy-only HistogramAdapter + make_example_adapter.
- pyproject.toml wires the entry point; README shows pip install -e -> world-model list.
- test_example.py (4 logic tests). examples/COLCON_IGNORE keeps colcon out.

Verified end-to-end: installed to a temp target, `world-model list` and
`world-model info --adapter example` discover it via the entry point.

Author: rsasaki0109

README.md

@@ -345,6 +345,11 @@ Contributions are welcome — especially new **adapters** (model backends) and
 for the build/test flow and the design rules that keep adapters ROS-free and
 GPU-optional.
 
+Adapters can even live in a **separate pip package** and register via an entry
+point — see the runnable
+[example adapter](examples/world_model_adapter_example/) (`pip install -e .` →
+`world-model list` shows it, no edits to this repo).
+
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE).

examples/COLCON_IGNORE

@@ -0,0 +1,35 @@
+# Example external World Model adapter
+
+A tiny, **separate** pip package that adds a World Model backend to
+`world_model_ros2` **without editing the main repo** — the entry-point hub in
+action. The adapter (`example`) encodes each frame as an RGB colour histogram
+and reports surprise as the histogram change (a GPU-free appearance-novelty
+signal). Copy this layout to ship your own model.
+
+## Try it
+
+```bash
+source /opt/ros/jazzy/setup.bash
+source ../../install/setup.bash          # provides world_model_py
+pip install -e .                         # registers the entry point
+
+world-model list                         # -> ... example ...
+world-model info --adapter example
+```
+
+In ROS 2 it then works like any backend:
+
+```bash
+ros2 run world_model_py runtime_node --ros-args -p adapter:=example
+```
+
+## The wiring
+
+```toml
+# pyproject.toml
+[project.entry-points."world_model_ros2.adapters"]
+example = "wm_example_adapter:make_example_adapter"
+```
+
+`make_example_adapter(**kwargs)` returns a `WorldModelAdapter`. That's the whole
+contract — see `wm_example_adapter/__init__.py`.

examples/world_model_adapter_example/README.md

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wm-example-adapter"
+version = "0.1.0"
+description = "Example external World Model adapter for world_model_ros2 (entry-point demo)"
+requires-python = ">=3.10"
+dependencies = ["numpy"]
+# world_model_py is provided by the ROS 2 workspace, not PyPI, so it is not
+# listed here; source the workspace before using this adapter.
+
+[project.entry-points."world_model_ros2.adapters"]
+example = "wm_example_adapter:make_example_adapter"
+
+[tool.setuptools]
+packages = ["wm_example_adapter"]

examples/world_model_adapter_example/pyproject.toml

@@ -0,0 +1,37 @@
+"""Logic test for the example adapter (no ROS, no GPU)."""
+import numpy as np
+
+from wm_example_adapter import HistogramAdapter, color_histogram
+from world_model_py.adapters.base import Observation
+
+
+def _img(color):
+    return np.tile(np.array(color, np.uint8), (16, 16, 1))
+
+
+def test_histogram_normalized():
+    h = color_histogram(_img([255, 0, 0]))
+    assert abs(h.sum() - 1.0) < 1e-5
+    assert h.shape == (64,)
+
+
+def test_first_frame_zero_surprise():
+    wm = HistogramAdapter()
+    pred = wm.predict_future(Observation(image=_img([10, 10, 10])), horizon=3)
+    assert pred.risk == 0.0
+    assert pred.horizon == 3
+    assert pred.risk_label == "example-hist"
+
+
+def test_same_image_low_surprise():
+    wm = HistogramAdapter()
+    wm.predict_future(Observation(image=_img([10, 200, 10])))
+    pred = wm.predict_future(Observation(image=_img([10, 200, 10])))
+    assert pred.risk < 1e-6
+
+
+def test_color_change_high_surprise():
+    wm = HistogramAdapter()
+    wm.predict_future(Observation(image=_img([255, 0, 0])))
+    pred = wm.predict_future(Observation(image=_img([0, 0, 255])))
+    assert pred.risk > 0.9  # entirely different colour bin

examples/world_model_adapter_example/test/test_example.py

@@ -0,0 +1,75 @@
+"""Example external World Model adapter for world_model_ros2.
+
+A GPU-free, numpy-only backend that demonstrates how an *outside* package adds a
+World Model: it encodes each camera frame as a normalized RGB colour histogram
+(the "latent") and reports surprise as the L1 distance between successive
+histograms — a cheap appearance-change / novelty signal.
+
+It is wired in via a package entry point (see pyproject.toml), so installing
+this package makes ``load_model("example")`` and ``world-model list`` work with
+no changes to world_model_ros2 itself.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+from world_model_py.adapters.base import (
+    ActionCondition,
+    FuturePrediction,
+    Observation,
+    WorldModelAdapter,
+)
+
+_BINS = 4  # per channel -> 64-d histogram
+
+
+def color_histogram(image_hwc_uint8: np.ndarray) -> np.ndarray:
+    px = np.asarray(image_hwc_uint8).reshape(-1, 3).astype(np.int64)
+    q = np.clip(px // (256 // _BINS), 0, _BINS - 1)
+    idx = q[:, 0] * _BINS * _BINS + q[:, 1] * _BINS + q[:, 2]
+    h = np.bincount(idx, minlength=_BINS ** 3).astype(np.float32)
+    return h / (h.sum() + 1e-8)
+
+
+class HistogramAdapter(WorldModelAdapter):
+    name = "example"
+
+    def __init__(self, dt: float = 0.1):
+        self.dt = float(dt)
+        self._prev: Optional[np.ndarray] = None
+
+    def predict_future(
+        self,
+        obs: Observation,
+        action: Optional[ActionCondition] = None,
+        horizon: int = 8,
+    ) -> FuturePrediction:
+        if obs.image is None or getattr(obs.image, "size", 0) == 0:
+            raise ValueError("example adapter needs obs.image")
+        if action is not None and action.horizon > 0:
+            horizon = action.horizon
+        horizon = max(1, int(horizon))
+
+        hist = color_histogram(obs.image)
+        if self._prev is None:
+            risk, conf = 0.0, 0.0
+        else:
+            risk = float(np.clip(0.5 * np.abs(hist - self._prev).sum(), 0.0, 1.0))
+            conf = 0.8
+        self._prev = hist
+        return FuturePrediction(
+            dt=self.dt,
+            latents=[hist.copy() for _ in range(horizon)],
+            risk=risk,
+            risk_confidence=conf,
+            risk_label="example-hist",
+        )
+
+    def reset(self) -> None:
+        self._prev = None
+
+
+def make_example_adapter(**kwargs) -> HistogramAdapter:
+    return HistogramAdapter(**kwargs)