Add entry-point adapter discovery (real plugin hub)

External pip packages can now register World Model backends under the
`world_model_ros2.adapters` entry-point group; load_model() / `world-model list`
discover them with no edits to this repo. Built-ins take precedence (an entry
point can't hijack dummy/remote/ijepa/vjepa2); a failing entry point warns
instead of breaking the registry.

- registry.py: built-in + register() + cached entry-point discovery.
- test_registry.py: 6 tests (builtins, register, discovery, precedence, bad EP),
  added to the ROS-free CI unit job.
- CONTRIBUTING + CHANGELOG: document shipping an adapter from your own package.

Author: rsasaki0109

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
         run: >-
           python -m pytest
           test/test_adapters.py test/test_jepa.py test/test_bench.py
-          test/test_wire.py test/test_remote_server.py -q
+          test/test_registry.py test/test_wire.py test/test_remote_server.py -q
 
   # Full ROS 2 Jazzy build + colcon test inside the official container.
   colcon:

CHANGELOG.md

@@ -7,6 +7,9 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 ### Added
+- **Entry-point adapter discovery** — external pip packages can add World Model
+  backends under the `world_model_ros2.adapters` group; `load_model()` /
+  `world-model list` pick them up with no edits to this repo.
 - **`vjepa2` adapter** — real V-JEPA 2 video encoder via `torch.hub`
   (`facebookresearch/vjepa2`): rolling-clip latent + temporal surprise. Verified
   on a 16 GB GPU (ViT-L, fp16). torch stays optional/lazy-imported.

CONTRIBUTING.md

@@ -60,6 +60,19 @@ register("mymodel", MyAdapter)
 Add unit tests with a fake backend so they run in CI without the real weights
 (see `test/test_jepa.py`), and a `gpu_verify_*.py` script for the real model.
 
+**Ship an adapter from your own package** — no edits here needed. Expose it
+under the `world_model_ros2.adapters` entry-point group:
+
+```toml
+# pyproject.toml in your package
+[project.entry-points."world_model_ros2.adapters"]
+mymodel = "my_pkg.adapter:make_my_adapter"
+```
+
+Once installed, `load_model("mymodel")` and `world-model list` pick it up
+automatically. Built-in names take precedence, so an entry point can't hijack
+`dummy`/`remote`/`ijepa`/`vjepa2`.
+
 ## Pull requests
 
 - Branch off `main`; keep PRs focused.

world_model_py/test/test_registry.py

@@ -0,0 +1,73 @@
+"""Registry: built-ins, register(), and entry-point discovery. No ROS/GPU."""
+import numpy as np
+
+from world_model_py import registry
+from world_model_py.adapters import DummyAdapter
+from world_model_py.adapters.base import FuturePrediction, Observation, WorldModelAdapter
+
+
+class _Toy(WorldModelAdapter):
+    name = "toy"
+
+    def predict_future(self, obs, action=None, horizon=8):
+        return FuturePrediction(dt=0.1, latents=[np.zeros(2, np.float32)] * horizon, risk=0.5)
+
+
+def _reset():
+    registry._EXTRA.clear()
+    registry._DISCOVERED = None
+
+
+def test_builtins_present():
+    _reset()
+    for name in ("dummy", "remote", "ijepa", "vjepa2"):
+        assert name in registry.available_models()
+
+
+def test_register_adds_and_loads():
+    _reset()
+    registry.register("toy", _Toy)
+    assert "toy" in registry.available_models()
+    assert isinstance(registry.load_model("toy"), _Toy)
+
+
+def test_unknown_raises():
+    _reset()
+    try:
+        registry.load_model("nope")
+        assert False
+    except KeyError:
+        pass
+
+
+def test_entry_point_discovery(monkeypatch):
+    _reset()
+    monkeypatch.setattr(registry, "_discover_entry_points", lambda: {"toy_ep": _Toy})
+    assert "toy_ep" in registry.available_models()
+    assert isinstance(registry.load_model("toy_ep"), _Toy)
+
+
+def test_builtin_beats_entry_point(monkeypatch):
+    _reset()
+    # an entry point cannot hijack a built-in name
+    monkeypatch.setattr(registry, "_discover_entry_points", lambda: {"dummy": _Toy})
+    assert isinstance(registry.load_model("dummy"), DummyAdapter)
+
+
+def test_bad_entry_point_is_skipped(monkeypatch):
+    _reset()
+    from importlib import metadata
+
+    class _BadEP:
+        name = "broken"
+
+        def load(self):
+            raise RuntimeError("boom")
+
+    monkeypatch.setattr(metadata, "entry_points", lambda **k: [_BadEP()])
+    import warnings
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        models = registry.available_models()  # must not raise
+    assert "dummy" in models

world_model_py/world_model_py/registry.py

@@ -1,15 +1,28 @@
 """Adapter registry: ``load_model("dummy")`` -> a WorldModelAdapter.
 
-This is the ``transformers``-style entry point for the project. New backends
-register a factory here (or, later, via package entry points) and become
-reachable by name from the CLI, the runtime node and the benchmark.
+This is the ``transformers``-style entry point for the project. Backends become
+reachable by name from the CLI, the runtime node and the benchmark in three ways:
+
+1. built-in adapters (dummy / remote / ijepa / vjepa2),
+2. in-process ``register("name", factory)``,
+3. **package entry points** — an external pip package exposes adapters under the
+   ``world_model_ros2.adapters`` group, so installing it makes new World Models
+   available with no edits here. This is what makes it an adapter *hub*.
+
+   In your package's pyproject.toml:
+
+       [project.entry-points."world_model_ros2.adapters"]
+       mymodel = "my_pkg.adapter:make_my_adapter"
 """
 from __future__ import annotations
 
+import warnings
 from typing import Callable, Dict
 
 from .adapters import DummyAdapter, RemoteAdapter, WorldModelAdapter
 
+ENTRY_POINT_GROUP = "world_model_ros2.adapters"
+
 
 def _make_ijepa(**kwargs) -> WorldModelAdapter:
     # Lazy: importing jepa pulls torch/transformers only when actually used.
@@ -25,32 +38,64 @@ def _make_vjepa2(**kwargs) -> WorldModelAdapter:
     return make_vjepa2_adapter(**kwargs)
 
 
-# name -> factory(**kwargs) -> adapter
-_REGISTRY: Dict[str, Callable[..., WorldModelAdapter]] = {
+# built-in name -> factory(**kwargs) -> adapter
+_BUILTIN: Dict[str, Callable[..., WorldModelAdapter]] = {
     "dummy": DummyAdapter,
     "remote": RemoteAdapter,
     "ijepa": _make_ijepa,
     "vjepa2": _make_vjepa2,
 }
 
+# adapters added at runtime via register()
+_EXTRA: Dict[str, Callable[..., WorldModelAdapter]] = {}
+
+# cache of entry-point-discovered factories (None until first discovery)
+_DISCOVERED: Dict[str, Callable[..., WorldModelAdapter]] | None = None
+
+
+def _discover_entry_points() -> Dict[str, Callable[..., WorldModelAdapter]]:
+    """Load adapter factories advertised by installed packages. Cached; a single
+    bad entry point warns rather than breaking the whole registry."""
+    from importlib.metadata import entry_points
+
+    found: Dict[str, Callable[..., WorldModelAdapter]] = {}
+    try:
+        eps = entry_points(group=ENTRY_POINT_GROUP)
+    except TypeError:  # very old importlib.metadata
+        eps = entry_points().get(ENTRY_POINT_GROUP, [])  # type: ignore[attr-defined]
+    for ep in eps:
+        try:
+            found[ep.name] = ep.load()
+        except Exception as exc:  # noqa: BLE001
+            warnings.warn(f"failed to load adapter entry point '{ep.name}': {exc}")
+    return found
+
+
+def _registry() -> Dict[str, Callable[..., WorldModelAdapter]]:
+    global _DISCOVERED
+    if _DISCOVERED is None:
+        _DISCOVERED = _discover_entry_points()
+    # precedence: discovered < built-in < explicit register()
+    return {**_DISCOVERED, **_BUILTIN, **_EXTRA}
+
 
 def register(name: str, factory: Callable[..., WorldModelAdapter]) -> None:
     """Register a new adapter factory under ``name`` (overwrites if present)."""
-    _REGISTRY[name] = factory
+    _EXTRA[name] = factory
 
 
 def available_models() -> list[str]:
-    return sorted(_REGISTRY)
+    return sorted(_registry())
 
 
 def load_model(name: str, **kwargs) -> WorldModelAdapter:
     """Instantiate the adapter registered under ``name``.
 
-    Extra keyword arguments are passed to the adapter constructor, e.g.
+    Extra keyword arguments are passed to the adapter factory, e.g.
     ``load_model("remote", url="http://gpu-box:8080/predict_future")``.
     """
     try:
-        factory = _REGISTRY[name]
+        factory = _registry()[name]
     except KeyError:
         raise KeyError(
             f"unknown world model '{name}'. available: {available_models()}"