World Genesis v0.3.0 — PyTorch JEPA backend, dashboard knob, test/doc fixes

Author: Gerrit Tombrink

.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -e ".[dev]"
+
+      # The committed data/ files let the world build without network access;
+      # the optional torch backend is not installed here, so its test module
+      # skips via pytest.importorskip — exercising the graceful-degradation path.
+      - name: Run test suite
+        run: pytest -q

.gitignore

@@ -0,0 +1,45 @@
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# ---- Virtual environments ----
+.venv/
+venv/
+env/
+ENV/
+
+# ---- Test / type / lint caches ----
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+
+# ---- Simulation run output ----
+# CSV/JSON written by sim_logger.py at runtime — not source.
+logs/
+
+# ---- Editors / OS ----
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+
+# ---- Secrets ----
+.env
+.env.*
+*.pem
+
+# NOTE: data/ (Natural Earth + precomputed .npy/.npz) IS committed on purpose
+# so the app runs after a clone. See docs/data_attributions.md. To regenerate
+# instead, delete data/ and run the generate_*.py scripts.

CHANGELOG.md

@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-25
+
+Adds the PyTorch JEPA backend that earlier releases listed as a v0.3
+candidate. The backend is opt-in; the default NumPy path and all prior
+behaviour are unchanged. This release also closes documentation/test gaps
+found in an upload-readiness audit.
+
+### Added — PyTorch JEPA backend
+
+- **`world_model_torch.py`** — a PyTorch re-implementation of the JEPA
+  world model (encoder, AdaLN predictor, SIGReg, CEM planner) using autograd
+  instead of the hand-written NumPy backprop. At its default settings it
+  reproduces `world_model.py` exactly: weights copied across backends via
+  `load_numpy_params` / `export_numpy_params` produce encode/predict outputs
+  matching to < 1e-4 (verified in `test_world_model_torch.py`). CPU by
+  default with optional CUDA (`device="auto"`); `torch.set_num_threads(1)`
+  by default to stay friendly to the eventlet server loop.
+- **Paper-aligned toggles (opt-in, off by default):** `sigreg_mode=
+  "epps_pulley"` implements the LeWorldModel (Maes et al. 2026,
+  arXiv:2603.19312) characteristic-function SIGReg with the paper's
+  λ = 0.1 and a large projection count, plus `predictor_dropout`. The
+  default `moments` SIGReg (M = 15, λ = 0.01) is unchanged.
+- **`SharedWorldModel(backend="numpy"|"torch", ...)`** dispatch; the torch
+  import is lazy so PyTorch remains an optional dependency
+  (`pip install -e ".[torch]"`).
+- **Dashboard JEPA tab** — select backend (NumPy / PyTorch), settings preset
+  (Repo default / Paper), and device at runtime via `set_jepa_backend`
+  (`app.py`) / `World.set_jepa_backend` (`world.py`). The swap preserves the
+  experience buffer and repoints all agents; the sim loop is paused during
+  the swap and resumed. Falls back gracefully with a clear message when
+  PyTorch is not installed.
+
+### Added — tests
+
+- **`test_world_model_gradcheck.py`** — central finite-difference gradient
+  checks for every analytic backward pass (linear, GELU, RMSNorm, AdaLN,
+  SIGReg). Measured relative error < 1e-8. This is the test prior READMEs
+  referred to but did not ship.
+- **`test_world_model.py`** — JEPA learning/inference behaviour: prediction
+  loss reduction, learned action conditioning (zero-init AdaLN identity →
+  action-sensitive after training), anti-collapse, linear probe R², CEM
+  planner output validity.
+- **`test_world_model_torch.py`** — torch backend parity, weight cross-check,
+  Epps–Pulley toggle, and device handling (skips when torch is absent).
+
+### Fixed — documentation & packaging
+
+- README test table referenced two test files that did not exist
+  (`test_world_model.py`, `test_world_model_gradcheck.py`); both now ship.
+- `world_model.py` docstring pointed at a non-existent `test_layers_gradcheck.py`.
+- Project version was out of sync (`pyproject.toml` 0.1.0 vs CITATION/CHANGELOG
+  0.2.1); all now read 0.3.0.
+- `docs/validation.md` described the PyTorch port as future work; it is now
+  documented as implemented.
+- Added `.gitignore` and a GitHub Actions test workflow
+  (`.github/workflows/test.yml`, Python 3.11/3.12/3.13).
+- `test_macro.py` unit tests now `assert` instead of `return`-ing a bool
+  (removes pytest `PytestReturnNotNoneWarning`).
+
 ## [0.2.1] - 2026-05-06
 
 A same-day follow-up review pass on v0.2.0 surfaced five additional bugs

CITATION.cff

@@ -13,8 +13,8 @@ authors:
     given-names: Gerrit
     name-suffix: Dr.
     affiliation: GeoLambda GmbH
-version: 0.2.1
-date-released: "2026-05-06"
+version: 0.3.0
+date-released: "2026-05-25"
 license: AGPL-3.0-or-later
 repository-code: "https://github.com/GeoLambdaAI/world-genesis"
 url: "https://www.geolambda.ai"

README.md

@@ -199,7 +199,7 @@ Each agent perceives the world through a **Joint Embedding Predictive Architectu
 | Predictor | MLP with **Adaptive Layer Normalization** (AdaLN) — action conditions each layer's scale and shift; zero-init scale/shift weights (DiT-style) | Maes et al. 2026, Section 3.2; Peebles & Xie 2022 |
 | SIGReg (v0.2) | Differentiable moments-matching variant: skewness² + kurtosis² + variance penalty along random unit-norm projections, in the spirit of Cramer-Wold gaussianity testing | Adapted from Maes et al. 2026, Section 4 |
 | CEM Planner | Cross-Entropy Method: sample action sequences, rollout in latent space, select elites, refine | LeCun 2022, Section 3.4 |
-| Training | L = L\_pred + λ · SIGReg(Z), **analytic backpropagation** (hand-implemented in NumPy, gradient-checked against finite differences to <1e-10), Adam optimizer with gradient clipping at 5.0 | LeCun 2022 |
+| Training | L = L\_pred + λ · SIGReg(Z), **analytic backpropagation** (hand-implemented in NumPy, gradient-checked against central finite differences to <1e-8 in `test_world_model_gradcheck.py`), Adam optimizer with gradient clipping at 5.0. An optional PyTorch backend (`world_model_torch.py`) uses autograd. | LeCun 2022 |
 
 **Loss function:**
 
@@ -209,6 +209,20 @@ L = ||z_hat_{t+1} - z_{t+1}||^2 + lambda * SIGReg(Z)
 
 where `z_hat_{t+1} = Predictor(Encoder(x_t), a_t)` and `z_{t+1} = Encoder(x_{t+1})`.
 
+**Backends (NumPy default, PyTorch optional).** The reference implementation in
+`world_model.py` is pure NumPy with hand-written, gradient-checked backprop. An
+opt-in PyTorch backend (`world_model_torch.py`) implements the identical
+architecture with autograd and optional CUDA. At its default settings it
+reproduces the NumPy model — weights copied across backends match encode/predict
+outputs to < 1e-4 — so it is a true drop-in, not a different model. It also adds
+*opt-in* paper-aligned toggles: an Epps–Pulley characteristic-function SIGReg
+(Maes et al. 2026) with λ = 0.1, and predictor dropout. Install with
+`pip install -e ".[torch]"`; select at runtime in code
+(`SharedWorldModel(backend="torch")`) or from the dashboard's **JEPA** tab
+(NumPy / PyTorch × Repo-default / Paper × device). Switching preserves the
+shared experience buffer; if PyTorch is not installed the option degrades
+gracefully and the NumPy backend keeps running.
+
 **Agent decision loop** (Kahneman's Dual Process Theory):
 - **System 1, symbolic** (every tick): Maslow-style needs hierarchy weights
   eleven goal candidates by trait-modulated priorities (eat, heal, work, trade,
@@ -407,9 +421,10 @@ altitude, and disease environment have higher survival and reproduction rates.
 | Module | Lines | Purpose |
 |--------|-------|---------|
 | `agents.py` | 1,208 | Autonomous agents: JEPA cognition, physics, traits, skills, memory, social actions |
-| `world.py` | 1,079 | World engine: tick loop, resources, businesses, settlements, scenario dispatch, era-aware UI summaries |
-| `world_model.py` | 701 | JEPA implementation: encoder, predictor (AdaLN), SIGReg, CEM planner, deterministic batch sampling |
-| `shared_world_model.py` | 229 | Single shared JEPA for all agents with batch encode/plan |
+| `world.py` | 1,189 | World engine: tick loop, resources, businesses, settlements, scenario dispatch, era-aware UI summaries, runtime JEPA backend swap |
+| `world_model.py` | 701 | JEPA implementation (NumPy, hand-written backprop): encoder, predictor (AdaLN), SIGReg, CEM planner, deterministic batch sampling |
+| `world_model_torch.py` | 534 | Optional PyTorch JEPA backend (autograd): same architecture, CUDA-ready, Epps–Pulley SIGReg toggle, NumPy weight bridge |
+| `shared_world_model.py` | 263 | Single shared JEPA for all agents with batch encode/plan; selects NumPy or PyTorch backend |
 | `macro.py` | 512 | 14-state ODE: climate, resources, pollution, socioeconomics |
 | `geopolitics.py` | 705 | Emergent nations, alliances, trade (gravity model), conflict (IFs) |
 | `bridge.py` | 456 | Bidirectional coupling: agents <-> macro <-> geopolitics; per-cell regen baselines |
@@ -443,9 +458,10 @@ altitude, and disease environment have higher survival and reproduction rates.
 | Test | Validates | Count |
 |------|-----------|-------|
 | `test_macro.py` | BAU 2025–2100 vs. IPCC AR6 SSP2-4.5/SSP3-7.0 envelope; carbon-cycle vs. Mauna Loa decadal mean; ECS-consistency unit test | 9 + 2 |
-| `test_world_model.py` | JEPA training: prediction-loss reduction, action-conditioning, anti-collapse, linear probe R², CEM planner output validity | 5 |
-| `test_world_model_gradcheck.py` | Backward implementations (linear, GELU, RMSNorm, AdaLN, SIGReg) verified against finite-difference gradients to <1e-10 | 5 |
+| `test_world_model.py` | JEPA training: prediction-loss reduction, learned action-conditioning, anti-collapse, linear probe R², CEM planner output validity | 5 |
+| `test_world_model_gradcheck.py` | Backward implementations (linear, GELU, RMSNorm, AdaLN, SIGReg) verified against central finite differences (measured relative error <1e-8) | 5 |
 | `test_shared_world_model.py` | Single vs. batch equivalence (max diff 1e-15), per-agent vs. plan_batch identity, edge cases | 6 |
+| `test_world_model_torch.py` | PyTorch backend (opt-in): single/batch parity, NumPy↔Torch weight cross-check (<1e-4), Epps–Pulley toggle, device handling (skips if torch absent) | 9 (+1 CUDA-gated) |
 | `test_agents_lifecycle.py` | Era-aware lifecycle thresholds across 4 eras, modern drift bounds, paleolithic 1-tick floor | 7 |
 | `test_geopolitics.py` | Haversine correctness, conflict monotonicity, 5-nation BAU prevalence calibration, summit-cadence independence | 5 |
 | `test_world.py` | Haversine threshold semantics, snapshot iteration safety | 4 |
@@ -517,7 +533,8 @@ that affected scientific correctness without breaking the runtime:
    10⁻⁴, so the prediction loss decreased only on the bias terms and the
    AdaLN action-conditioning weights were never updated at all. v0.2
    replaces this with hand-written analytic backpropagation in pure NumPy,
-   verified against finite-difference gradients to <1e-10 relative error.
+   verified against central finite differences to <1e-8 relative error
+   (`test_world_model_gradcheck.py`).
    On a synthetic toy problem with hidden physical parameters, prediction
    loss now decreases 103× and a linear probe recovers the hidden physics
    with R² = 0.98.

app.py

@@ -205,6 +205,15 @@ def get_god_log():
     return jsonify(world.god_mode.get_intervention_log())
 
 
+@app.route("/api/jepa/status")
+def get_jepa_status():
+    if world is None:
+        from world import _torch_available
+        return jsonify({"backend": "numpy", "preset": "default",
+                        "torch_available": _torch_available()})
+    return jsonify(world.get_jepa_status())
+
+
 @app.route("/api/dialogues")
 def get_dialogues():
     if world is None:
@@ -295,6 +304,37 @@ def on_test_llm():
         socketio.emit("llm_test_result", result)
 
 
+# ---- JEPA World-Model Backend ----
+@socketio.on("set_jepa_backend")
+def on_set_jepa_backend(data):
+    """Swap the shared JEPA backend/preset at runtime.
+
+    Rebuilding the model and repointing every agent must not interleave with
+    a tick, so the sim loop is paused for the swap (cooperative eventlet
+    scheduling means this is the same safety pattern used by on_reset) and
+    resumed afterwards only if it was running and the swap succeeded.
+    """
+    global sim_running, sim_thread
+    if not world:
+        return
+    backend = data.get("backend", "numpy")
+    preset = data.get("preset", "default")
+    device = data.get("device", "auto")
+
+    was_running = sim_running
+    if was_running:
+        sim_running = False
+        time.sleep(0.12)  # let the current tick finish before swapping
+
+    result = world.set_jepa_backend(backend=backend, preset=preset, device=device)
+
+    if was_running:
+        sim_running = True
+        sim_thread = eventlet.spawn(simulation_loop)
+
+    socketio.emit("jepa_status", result)
+
+
 # ---- God Mode ----
 @socketio.on("set_god_mode")
 def on_set_god_mode(data):

docs/validation.md

@@ -106,11 +106,15 @@ Full per-year trace is reproducible via `python test_macro.py | tee logs/validat
    (`latent_dim = 24` in `SharedWorldModel` defaults; `hidden_dim = 48`),
    versus millions of parameters in the published papers. v0.2.0 replaced
    v0.1's directional finite-difference gradient estimator with hand-written
-   analytic back-propagation in pure NumPy, gradient-checked against finite
-   differences to <1e-10; v0.2.1 made the training-batch sampling
-   deterministic via a per-instance `RandomState`, removing global-RNG
-   coupling. A PyTorch port for larger latent dimensions remains a v0.3
-   candidate.
+   analytic back-propagation in pure NumPy, gradient-checked against central
+   finite differences to <1e-8 relative error
+   ([`test_world_model_gradcheck.py`](../test_world_model_gradcheck.py));
+   v0.2.1 made the training-batch sampling deterministic via a per-instance
+   `RandomState`, removing global-RNG coupling. v0.3.0 adds an opt-in PyTorch
+   backend ([`world_model_torch.py`](../world_model_torch.py)) with autograd
+   and optional CUDA for scaling `latent_dim` up; it reproduces the NumPy
+   model at default settings (cross-backend encode/predict agree to <1e-4)
+   and exposes the paper's Epps–Pulley SIGReg as an opt-in toggle.
 7. **Conceptual references vs. quantitative ones.** Diamond (1997),
    Dawkins (2009), Stringer (2012), and Marshak (2019) are cited at the
    *structural* level — the simulator implements the continental-axis

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "world-genesis"
-version = "0.1.0"
+version = "0.3.0"
 description = "A physics-based, AI-driven simulation of human civilization on Planet Earth — JEPA agents, macro ODE, emergent geopolitics, real Earth geography."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -62,6 +62,9 @@ viz = [
     "matplotlib>=3.8",
     "pandas>=2.2",
 ]
+torch = [
+    "torch>=2.2",
+]
 
 [project.urls]
 Homepage = "https://www.geolambda.ai"
@@ -89,6 +92,7 @@ py-modules = [
     "sim_logger",
     "world",
     "world_model",
+    "world_model_torch",
 ]
 
 [tool.pytest.ini_options]

requirements.txt

@@ -1,6 +1,7 @@
 # Python 3.11+ required — see pyproject.toml ([project] requires-python).
-# Optional extras: pip install -e ".[viz]"  (matplotlib + pandas for scripts/figures.py)
-#                  pip install -e ".[dev]"  (pytest + pytest-cov + ruff + mypy)
+# Optional extras: pip install -e ".[viz]"    (matplotlib + pandas for scripts/figures.py)
+#                  pip install -e ".[dev]"    (pytest + pytest-cov + ruff + mypy)
+#                  pip install -e ".[torch]"  (PyTorch JEPA backend; CPU or CUDA)
 
 numpy>=1.24.0
 flask>=3.0.0