chore: harden workflow, linting, and fallback build paths

Author: biru-codeastromer

CHANGELOG.md

@@ -5,4 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on Keep a Changelog and this project follows Semantic Versioning.
 
 ## [Unreleased]
-- Initial scaffold in progress.
+- Pending release metadata and follow-up benchmark extensions.
+
+## [0.1.0] - 2026-02-21
+### Added
+- Monorepo scaffold with Python packages for `core`, `agents`, `planners`, `worldmodels`, and `server`.
+- Three procedural long-horizon environments: MemoryMaze, SwitchQuest, and CraftLite.
+- Stable episode trace schema, deterministic evaluation harness, CLI runner, and continual track metrics.
+- Planner implementations: MCTS, MPC-CEM, and trajectory sampling baselines.
+- World model baselines: deterministic latent, stochastic latent, and ensemble uncertainty wrapper.
+- Agent baselines: random, oracle, planner-oracle, imagination MPC, search MCTS skeleton, and PPO placeholder.
+- FastAPI server with runs CRUD, artifact uploads, leaderboard queries, tasks listing, and trace/metrics downloads.
+- Next.js dashboard with pages for home/tasks/leaderboard/run viewer.
+- Expo mobile viewer for task, leaderboard, and run summary browsing.
+- Docker compose stack, demo upload script, CI workflow, and pre-commit tooling.
+- Paper artifacts: imported draft PDF, LaTeX manuscript recreation, BibTeX references, and build workflow.

Makefile

@@ -1,24 +1,39 @@
-PYTHON ?= python3
-PIP ?= pip3
+VENV ?= .venv
+PYTHON ?= $(VENV)/bin/python
+PIP ?= $(VENV)/bin/pip
 
 .PHONY: setup test lint demo paper
 
 setup:
+	python3 -m venv $(VENV)
+	$(PIP) install --upgrade pip
 	$(PIP) install -r requirements-dev.txt
 	$(PIP) install -e core -e planners -e worldmodels -e agents -e server
 	cd web && npm install
 	cd mobile && npm install
 
 test:
-	pytest
+	$(PYTHON) -m pytest
 
 lint:
-	ruff check .
-	ruff format --check .
+	$(PYTHON) -m ruff check .
+	$(PYTHON) -m ruff format --check .
 
 demo:
-	docker compose up -d --build
+	@if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then \
+		docker compose up -d --build; \
+	else \
+		echo "Docker daemon unavailable; starting local API fallback on :8000"; \
+		mkdir -p .tmp; \
+		$(PYTHON) -m uvicorn worldmodel_server.main:app --host 127.0.0.1 --port 8000 > .tmp/demo-server.log 2>&1 & \
+		echo $$! > .tmp/demo-server.pid; \
+		sleep 2; \
+	fi
 	$(PYTHON) scripts/demo_run.py
+	@if [ -f .tmp/demo-server.pid ]; then \
+		kill `cat .tmp/demo-server.pid` || true; \
+		rm -f .tmp/demo-server.pid; \
+	fi
 
 paper:
 	$(MAKE) -C paper paper

README.md

@@ -1,28 +1,52 @@
 # worldmodel-gym
 
-WorldModel Gym is a long-horizon planning benchmark for imagination-based agents.
+WorldModel Gym is a reproducible long-horizon planning benchmark + evaluation platform for imagination-based agents.
 
-## 30-second demo
+## Quickstart (30 seconds)
 
 ```bash
 make setup
 make demo
 ```
 
-Then open:
+`make demo` will:
+- start the API + web stack with Docker when available
+- fall back to local API execution when Docker daemon is unavailable
+- run one benchmark evaluation
+- upload artifacts and populate leaderboard data
 
-- Web UI: <http://localhost:3000>
-- API docs: <http://localhost:8000/docs>
+Open:
+- [http://localhost:3000](http://localhost:3000) (web dashboard)
+- [http://localhost:8000/docs](http://localhost:8000/docs) (FastAPI docs)
 
-## Run one evaluation
+## Run a single evaluation
 
 ```bash
-python -m worldmodel_gym.eval.run --agent random --env memory_maze --track test --seeds 101,102 --max-episodes 2
+.venv/bin/python -m worldmodel_gym.eval.run \
+  --agent random \
+  --env memory_maze \
+  --track test \
+  --seeds 211,223 \
+  --max-episodes 2
 ```
 
-Artifacts are written to `runs/<run_id>/`.
+Artifacts are written to `runs/<run_id>/`:
+- `metrics.json`
+- `trace.jsonl`
+- `config.yaml`
 
-## Developer targets
+## Monorepo layout
+
+- `core/`: environments, traces, eval harness
+- `planners/`: MCTS, MPC-CEM, trajectory sampling
+- `worldmodels/`: deterministic/stochastic/ensemble latent models
+- `agents/`: baseline agents and registry
+- `server/`: FastAPI leaderboard + run artifact service
+- `web/`: Next.js dashboard
+- `mobile/`: Expo viewer
+- `paper/`: draft PDF + LaTeX sources
+
+## Dev targets
 
 ```bash
 make lint

agents/pyproject.toml

@@ -9,7 +9,6 @@ requires-python = ">=3.11"
 dependencies = [
   "numpy>=1.26.4",
   "torch>=2.3.1",
-  "stable-baselines3>=2.5.0",
 ]
 
 [tool.setuptools.packages.find]

agents/worldmodel_agents/imagination_mpc.py

@@ -3,17 +3,19 @@
 import copy
 
 import numpy as np
+from worldmodel_models.registry import create_world_model
+from worldmodel_planners.mpc_cem import MPCCEMPlanner
 
 from worldmodel_agents.base import AgentConfig, BaseAgent
-from worldmodel_planners.mpc_cem import MPCCEMPlanner
-from worldmodel_models.registry import create_world_model
 
 
 class ImaginationMPCAgent(BaseAgent):
     def __init__(self, config: AgentConfig | None = None):
         super().__init__(config=config)
         self.world_model = create_world_model("ensemble")
-        self.planner = MPCCEMPlanner(action_space_n=self.config.action_space_n, horizon=10, population=64, iterations=3)
+        self.planner = MPCCEMPlanner(
+            action_space_n=self.config.action_space_n, horizon=10, population=64, iterations=3
+        )
         self.latent = self.world_model.init_state(batch_size=1)
         self.buffer: list[dict] = []
         self.rng = np.random.default_rng(0)

agents/worldmodel_agents/oracle_agent.py

@@ -2,9 +2,10 @@
 
 import copy
 
-from worldmodel_agents.base import AgentConfig, BaseAgent
 from worldmodel_planners.mcts import MCTSPlanner
 
+from worldmodel_agents.base import AgentConfig, BaseAgent
+
 
 def _move_toward(agent_pos: list[int], target_pos: list[int]) -> int:
     ar, ac = agent_pos
@@ -64,7 +65,9 @@ def act(self, obs, info: dict) -> int:
 class PlannerOnlyOracleAgent(BaseAgent):
     def __init__(self, config: AgentConfig | None = None):
         super().__init__(config=config)
-        self.planner = MCTSPlanner(action_space_n=self.config.action_space_n, num_simulations=48, max_depth=18)
+        self.planner = MCTSPlanner(
+            action_space_n=self.config.action_space_n, num_simulations=48, max_depth=18
+        )
 
     def act(self, obs, info: dict) -> int:
         del obs

agents/worldmodel_agents/search_mcts.py

@@ -3,19 +3,21 @@
 import copy
 
 import numpy as np
-
-from worldmodel_agents.base import AgentConfig, BaseAgent
 from worldmodel_models.registry import create_world_model
 from worldmodel_planners.mcts import MCTSPlanner
 
+from worldmodel_agents.base import AgentConfig, BaseAgent
+
 
 class SearchMCTSAgent(BaseAgent):
     """Minimal MuZero-style skeleton: learned model + MCTS planning."""
 
     def __init__(self, config: AgentConfig | None = None):
         super().__init__(config=config)
         self.world_model = create_world_model("deterministic")
-        self.planner = MCTSPlanner(action_space_n=self.config.action_space_n, num_simulations=56, max_depth=14)
+        self.planner = MCTSPlanner(
+            action_space_n=self.config.action_space_n, num_simulations=56, max_depth=14
+        )
         self.latent = self.world_model.init_state(batch_size=1)
         self.buffer: list[dict] = []
         self.rng = np.random.default_rng(0)
@@ -32,7 +34,9 @@ def act(self, obs, info: dict) -> int:
         self.latent = self.world_model.observe(self.latent, obs)
 
         def transition_fn(state, action):
-            next_state, _pred_obs, pred_reward, pred_done, _aux = self.world_model.predict(state, int(action))
+            next_state, _pred_obs, pred_reward, pred_done, _aux = self.world_model.predict(
+                state, int(action)
+            )
             return next_state, float(pred_reward), bool(pred_done)
 
         result = self.planner.plan(

core/worldmodel_gym/envs/base.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
 import copy
+from dataclasses import dataclass
 from typing import Any
 
 import gymnasium as gym
@@ -46,7 +46,9 @@ def __init__(self, config: BaseEnvConfig):
         self.action_space = spaces.Discrete(8)
         self._rng = np.random.default_rng(0)
 
-        symbolic_space = spaces.Box(low=0.0, high=1.0, shape=(16, self.grid_size, self.grid_size), dtype=np.float32)
+        symbolic_space = spaces.Box(
+            low=0.0, high=1.0, shape=(16, self.grid_size, self.grid_size), dtype=np.float32
+        )
         rgb_space = spaces.Box(low=0, high=255, shape=(64, 64, 3), dtype=np.uint8)
 
         if self.config.obs_mode == "rgb":

core/worldmodel_gym/envs/memory_maze.py

@@ -71,7 +71,12 @@ def _step_state(self, action: int) -> tuple[float, bool, list[str]]:
             self.has_key = True
             events.append("found_key")
 
-        if action == 5 and self.has_key and self._adjacent(self.agent_pos, self.door_pos) and not self.door_open:
+        if (
+            action == 5
+            and self.has_key
+            and self._adjacent(self.agent_pos, self.door_pos)
+            and not self.door_open
+        ):
             self.door_open = True
             events.append("opened_door")
 

core/worldmodel_gym/eval/continual.py

@@ -9,12 +9,18 @@ class ContinualSchedule:
     shift_strength: float = 0.05
 
 
-def apply_shift_kwargs(base_kwargs: dict, env_id: str, shift_idx: int, shift_strength: float) -> dict:
+def apply_shift_kwargs(
+    base_kwargs: dict, env_id: str, shift_idx: int, shift_strength: float
+) -> dict:
     kwargs = dict(base_kwargs)
     if env_id == "memory_maze":
-        kwargs["wall_density"] = min(0.35, kwargs.get("wall_density", 0.16) + shift_idx * shift_strength)
+        kwargs["wall_density"] = min(
+            0.35, kwargs.get("wall_density", 0.16) + shift_idx * shift_strength
+        )
     elif env_id == "switch_quest":
-        kwargs["wall_density"] = min(0.25, kwargs.get("wall_density", 0.1) + shift_idx * shift_strength)
+        kwargs["wall_density"] = min(
+            0.25, kwargs.get("wall_density", 0.1) + shift_idx * shift_strength
+        )
     elif env_id == "craft_lite":
         kwargs["rock_count"] = int(kwargs.get("rock_count", 5) + shift_idx)
     return kwargs