Run predicators envs in the browser via Pyodide + pybullet WASM

.github/workflows/predicators.yml

@@ -24,7 +24,7 @@ jobs:
         restore-keys: |
           pip-${{ matrix.python-version }}-
     - run: |
-        pip install -e .
+        pip install -e .[ml]
         pip install pytest-cov==2.12.1 pytest-split
     - name: Pytest (group ${{ matrix.group }}/8)
       run: |
@@ -84,7 +84,7 @@ jobs:
           pip-${{ matrix.python-version }}-
     - name: Install dependencies
       run: |
-        pip install -e .
+        pip install -e .[ml]
         pip install mypy==1.8.0
     - name: Mypy
       run: |
@@ -109,7 +109,7 @@ jobs:
           pip-${{ matrix.python-version }}-
     - name: Install dependencies
       run: |
-        pip install -e .
+        pip install -e .[ml]
         pip install pytest-pylint==0.18.0
     - name: Pylint
       run: |

.github/workflows/web.yml

@@ -0,0 +1,61 @@
+name: web
+
+on: [push]
+
+jobs:
+  import-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.10.14
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10.14"
+
+    - name: Cache pip packages
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pip
+        key: pip-3.10.14-${{ hashFiles('setup.py') }}
+        restore-keys: |
+          pip-3.10.14-
+
+    - name: Set up Node 24
+      uses: actions/setup-node@v4
+      with:
+        node-version: "24"
+
+    - name: Install predicators + build tools
+      run: |
+        pip install -e .
+        pip install build
+
+    - name: Build predicators + gym shim wheels
+      run: |
+        PYTHON=$(which python) ./web/app/bundle.sh
+
+    # Pre-built pybullet WASM wheel from BasisResearch/pybullet-pyodide.
+    # That repo's CI builds the wheel as a release asset; we just
+    # download it. Override `PYBULLET_WASM_WHEEL_URL` via a repo
+    # variable to bump the version without editing this file.
+    - name: Download pybullet WASM wheel
+      env:
+        WHEEL_URL: ${{ vars.PYBULLET_WASM_WHEEL_URL || 'https://github.com/BasisResearch/pybullet-pyodide/releases/latest/download/pybullet-3.2.7-cp313-cp313-pyemscripten_2025_0_wasm32.whl' }}
+      run: |
+        curl -L --fail -o web/wheels/pybullet-3.2.7-cp313-cp313-pyemscripten_2025_0_wasm32.whl \
+          "$WHEEL_URL"
+        ls -lh web/wheels/
+
+    - name: Install Node deps (pyodide + puppeteer-core)
+      working-directory: web
+      run: |
+        npm ci
+
+    # The cheap gate: boot Pyodide in Node, install the three wheels,
+    # and verify every env named in the dropdown shows up as a
+    # registered BaseEnv subclass. No Chromium, no env construction,
+    # no asset extraction. ~30 s wall, vs. ~12 min for per-env smoke.
+    - name: Pyodide import check
+      run: |
+        node web/app/import_check.mjs

.predicators_pylintrc

@@ -10,7 +10,7 @@ extension-pkg-whitelist=numpy,pybullet,torch,tensorflow,pyrealsense2
 ignore=CVS
 
 # Add paths to the blacklist.
-ignore-paths=predicators/envs/assets,predicators/third_party,venv
+ignore-paths=predicators/envs/assets,predicators/third_party,venv,web
 
 # Add files or directories matching the regex patterns to the blacklist. The
 # regex matches against base names, not paths.

mypy.ini

@@ -2,7 +2,7 @@
 strict_equality = True
 disallow_untyped_calls = True
 warn_unreachable = True
-exclude = (predicators/envs/assets|venv|prompts|logs)
+exclude = (predicators/envs/assets|venv|prompts|logs|web)
 
 [mypy-predicators.*]
 disallow_untyped_defs = True

predicators/envs/__init__.py

@@ -3,14 +3,15 @@
 import logging
 from typing import Any
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs.base_env import BaseEnv
 
 __all__ = ["BaseEnv"]
 _MOST_RECENT_ENV_INSTANCE = {}
 
-# Find the subclasses.
-utils.import_submodules(__path__, __name__)
+# Find the subclasses. Tolerate missing optional deps so constrained
+# runtimes (e.g. Pyodide) can still load the envs that don't need them.
+utils.import_submodules(__path__, __name__, tolerate_import_errors=True)
 
 
 def create_new_env(name: str,

predicators/envs/ball_and_cup_sticky_table.py

@@ -6,7 +6,7 @@
 import numpy as np
 from gym.spaces import Box
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, EnvironmentTask, GroundAtom, Object, \

predicators/envs/base_env.py

@@ -10,8 +10,7 @@
 import numpy as np
 from gym.spaces import Box
 
-from predicators import utils
-from predicators.pretrained_model_interface import OpenAILLM
+from predicators import utils_lite as utils
 from predicators.settings import CFG
 from predicators.structs import Action, DefaultEnvironmentTask, \
     EnvironmentTask, GroundAtom, Object, Observation, Predicate, State, Task, \
@@ -319,6 +318,8 @@ def _parse_language_goal_from_json(
         object_names = set(id_to_obj)
         prompt_prefix = self._get_language_goal_prompt_prefix(object_names)
         prompt = prompt_prefix + f"\n# {language_goal}"
+        from predicators.pretrained_model_interface import \
+            OpenAILLM  # pylint: disable=import-outside-toplevel
         llm = OpenAILLM(CFG.llm_model_name)
         responses = llm.sample_completions(prompt,
                                            None,

predicators/envs/blocks.py

@@ -19,7 +19,7 @@
 from gym.spaces import Box
 from matplotlib import patches
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, Array, EnvironmentTask, GroundAtom, \

predicators/envs/burger.py

@@ -18,7 +18,7 @@
 from gym.spaces import Box
 from PIL import Image
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, DefaultEnvironmentTask, \

predicators/envs/cluttered_table.py

@@ -11,7 +11,7 @@
 import numpy as np
 from gym.spaces import Box
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, Array, EnvironmentTask, GroundAtom, \

predicators/envs/coffee.py

@@ -8,7 +8,7 @@
 import numpy as np
 from gym.spaces import Box
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.pybullet_helpers.objects import \
     sample_collision_free_2d_positions

predicators/envs/cover.py

@@ -11,7 +11,7 @@
 import numpy as np
 from gym.spaces import Box
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, Array, EnvironmentTask, GroundAtom, \

predicators/envs/doors.py

@@ -10,12 +10,12 @@
 from gym.spaces import Box
 from numpy.typing import NDArray
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, Array, EnvironmentTask, GroundAtom, \
     Object, Predicate, State, Type
-from predicators.utils import Rectangle, StateWithCache, _Geom2D
+from predicators.utils_lite import Rectangle, StateWithCache, _Geom2D
 
 
 class DoorsEnv(BaseEnv):

predicators/envs/exit_garage.py

@@ -9,12 +9,12 @@
 import numpy as np
 from gym.spaces import Box
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, EnvironmentTask, GroundAtom, Object, \
     Predicate, State, Type
-from predicators.utils import _Geom2D
+from predicators.utils_lite import _Geom2D
 
 
 class ExitGarageEnv(BaseEnv):

predicators/envs/grid_row.py

@@ -7,7 +7,7 @@
 import numpy as np
 from gym.spaces import Box
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, EnvironmentTask, GroundAtom, Object, \

predicators/envs/gymnasium_wrapper.py

@@ -44,7 +44,8 @@ def _ensure_cfg_initialized() -> None:
     required fields like ``seed`` are missing and ``BaseEnv.__init__``
     would crash.
     """
-    from predicators import utils  # pylint: disable=import-outside-toplevel
+    from predicators import \
+        utils_lite as utils  # pylint: disable=import-outside-toplevel
     from predicators.settings import \
         CFG  # pylint: disable=import-outside-toplevel
     if not hasattr(CFG, "seed"):
@@ -88,7 +89,7 @@ def __init__(
         _ensure_cfg_initialized()
         if cfg_overrides:
             from predicators import \
-                utils  # pylint: disable=import-outside-toplevel
+                utils_lite as utils  # pylint: disable=import-outside-toplevel
             utils.update_config(cfg_overrides)
         resolved_cls = _resolve_cls(env_cls)
         self._env = resolved_cls(use_gui=use_gui, **env_kwargs)

predicators/envs/kitchen.py

@@ -17,7 +17,7 @@
     _MJKITCHEN_IMPORTED = True
 except (ImportError, RuntimeError):
     _MJKITCHEN_IMPORTED = False
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, EnvironmentTask, Image, Object, \

predicators/envs/narrow_passage.py

@@ -7,12 +7,12 @@
 import numpy as np
 from gym.spaces import Box
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, EnvironmentTask, GroundAtom, Object, \
     Predicate, State, Type
-from predicators.utils import _Geom2D
+from predicators.utils_lite import _Geom2D
 
 
 class NarrowPassageEnv(BaseEnv):

predicators/envs/noisy_button.py

@@ -17,7 +17,7 @@
 import numpy as np
 from gym.spaces import Box
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.settings import CFG
 from predicators.structs import Action, EnvironmentTask, GroundAtom, Object, \

predicators/envs/painting.py

@@ -20,7 +20,8 @@
 from predicators.settings import CFG
 from predicators.structs import Action, EnvironmentTask, GroundAtom, Object, \
     Predicate, State, Type
-from predicators.utils import EnvironmentFailure, HumanDemonstrationFailure
+from predicators.utils_lite import EnvironmentFailure, \
+    HumanDemonstrationFailure
 
 
 class PaintingEnv(BaseEnv):

predicators/envs/pddl_env.py

@@ -19,7 +19,7 @@
 from pyperplan.pddl.pddl import Domain as PyperplanDomain
 from pyperplan.pddl.pddl import Type as PyperplanType
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs import BaseEnv
 from predicators.envs.pddl_procedural_generation import \
     create_blocks_pddl_generator, create_delivery_pddl_generator, \

predicators/envs/playroom.py

@@ -8,7 +8,7 @@
 from gym.spaces import Box
 from matplotlib import patches
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs.blocks import BlocksEnv, BlocksEnvClear
 from predicators.settings import CFG
 from predicators.structs import Action, Array, EnvironmentTask, GroundAtom, \

predicators/envs/pybullet_ants.py

@@ -4,7 +4,7 @@
 import numpy as np
 import pybullet as p
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs.pybullet_env import PyBulletEnv
 from predicators.pybullet_helpers.objects import create_object, \
     create_pybullet_block, sample_collision_free_2d_positions, update_object

predicators/envs/pybullet_balance.py

@@ -22,7 +22,7 @@
 from predicators.settings import CFG
 from predicators.structs import Action, Array, ConceptPredicate, \
     EnvironmentTask, GroundAtom, NSPredicate, Object, Predicate, State, Type
-from predicators.utils import VLMQuery
+from predicators.utils_lite import VLMQuery
 
 
 class PyBulletBalanceEnv(PyBulletEnv):

predicators/envs/pybullet_barrier.py

@@ -14,7 +14,7 @@
 import numpy as np
 import pybullet as p
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs.pybullet_env import PyBulletEnv
 from predicators.pybullet_helpers.geometry import Pose3D, Quaternion
 from predicators.pybullet_helpers.objects import create_object, \

predicators/envs/pybullet_blocks.py

@@ -7,7 +7,7 @@
 import numpy as np
 import pybullet as p
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs.blocks import BlocksEnv
 from predicators.envs.pybullet_env import PyBulletEnv
 from predicators.pybullet_helpers.geometry import Pose3D, Quaternion

predicators/envs/pybullet_boil.py

@@ -8,7 +8,7 @@
 import numpy as np
 import pybullet as p
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs.pybullet_env import PyBulletEnv
 from predicators.pybullet_helpers import retry_pybullet_call
 from predicators.pybullet_helpers.geometry import Pose3D, Quaternion

predicators/envs/pybullet_circuit.py

@@ -16,7 +16,7 @@
 import numpy as np
 import pybullet as p
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs.pybullet_env import PyBulletEnv
 from predicators.pybullet_helpers.geometry import Pose3D, Quaternion
 from predicators.pybullet_helpers.objects import create_object

predicators/envs/pybullet_coffee.py

@@ -37,7 +37,7 @@
 import numpy as np
 import pybullet as p
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs.coffee import CoffeeEnv
 from predicators.envs.pybullet_env import PyBulletEnv
 from predicators.pybullet_helpers.geometry import Pose3D, Quaternion

predicators/envs/pybullet_cover.py

@@ -11,7 +11,7 @@
 import numpy as np
 import pybullet as p
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs.cover import CoverEnv
 from predicators.envs.pybullet_env import PyBulletEnv
 from predicators.pybullet_helpers.geometry import Pose3D, Quaternion

predicators/envs/pybullet_domino/components/domino_component.py

@@ -15,7 +15,7 @@
 import numpy as np
 import pybullet as p
 
-from predicators import utils
+from predicators import utils_lite as utils
 from predicators.envs.pybullet_domino.components.base_component import \
     DominoEnvComponent
 from predicators.pybullet_helpers.geometry import Pose3D, Quaternion