worldforge

WorldForge

observe
  → policy proposes candidate actions
  → predict rolls futures  /  score ranks them as a cost oracle
  → LatentMPCController selects the lowest-cost chunk   (CEM, receding horizon)
  → execute, evaluate, replan

The world model stays a pure oracle. The controller stays a pure optimizer. Each adapter advertises only the capabilities it actually implements.

Quickstart

uv add worldforge-ai
# or: pip install worldforge-ai

from worldforge import Action, LatentMPCController, PlannerConfig, WorldForge

forge = WorldForge()

# Action-conditioned forward dynamics on a JSON world-state dict.
prediction = forge.predict(
    {"scene": {"objects": {}}},
    Action.move_to(0.3, 0.8, 0.0),
    provider="mock",
)

# Latent MPC: sample horizons, score them, keep elites, return the lowest-cost chunk.
plan = LatentMPCController(
    forge=forge,
    score_provider="mock",
    config=PlannerConfig(
        horizon=1,
        num_samples=64,
        num_iterations=5,
        num_elites=8,
        action_parameter_bounds={"x": (-1.0, 1.0), "y": (-1.0, 1.0), "z": (-1.0, 1.0)},
        seed=0,
    ),
).plan_step(
    observation_info={"point": [0.0, 0.8, 0.0]},
    goal_info={"target": [0.3, 0.8, 0.0]},
)

print(prediction.physics_score, plan.best_score, plan.actions[0])

The mock provider needs no credentials, GPU, checkpoint, or robot. Success is a physics score plus a receding-horizon plan that selected the lowest-cost action.

uv run worldforge doctor --registered-only
uv run python examples/latent_mpc_planning.py
uv run worldforge predict kitchen --provider mock --x 0.3 --y 0.8 --z 0.0 --steps 2
uv run worldforge eval --suite planning --provider mock --format json
uv run worldforge benchmark --provider mock --operation predict --operation embed

Optional extras: uv add "worldforge-ai[harness]" (Textual robotics report), uv add "worldforge-ai[rerun]" (event/artifact recording), uv add "worldforge-ai[tensorboard]" (LeWorldModel checkpoint inspection).

Python 3.13 only. From source: uv add "worldforge-ai @ git+https://github.com/AbdelStark/worldforge". For a checkout: git clone https://github.com/AbdelStark/worldforge.git && cd worldforge && uv sync --group dev.

uv run worldforge examples
uv run worldforge provider list
uv run worldforge provider info mock
uv run worldforge provider contract mock --format json
uv run worldforge negotiate --list
uv run worldforge benchmark --provider mock --operation embed --input-file examples/benchmark-inputs.json
uv run worldforge benchmark --provider mock --operation predict --budget-file examples/benchmark-budget.json

Robotics Showcase

The front-door robotics demo composes a Hugging Face LeRobot policy with a LeWorldModel checkpoint. LeRobot proposes PushT action candidates, WorldForge bridges them into LeWorldModel-native tensors, LeWorldModel scores them, and WorldForge selects the lowest-cost chunk for local mock replay.

This is simulation/replay planning: real policy inference, real score-model inference, typed composition, candidate ranking, and visual replay. Hardware control, safety, robot controllers, and task-specific preprocessing stay host-owned.

For measured decision evidence without a live robot, the Go2 Air ControlBench trace replay reranks public DecisionTrace fixtures and reports native-odometry regret. It does not import DimOS, Unitree SDKs, or connect hardware:

uv run python examples/go2-controlbench-decisiontrace/run.py

Pipeline: real policy, real score checkpoint, WorldForge planner, local mock replay.

Decision: candidate ranking, robot-arm illustration, and fixed tabletop replay.

scripts/robotics-showcase
uv run python scripts/demo_showcases.py run all --workspace-dir .worldforge/demo-showcases

The first command launches a staged Textual report, writes /tmp/worldforge-robotics-showcase/real-run.json, and records /tmp/worldforge-robotics-showcase/real-run.rrd. Press o in the TUI to open Rerun. --no-tui prints the terminal report; --json-only is for automation; --health-only is a non-mutating preflight. Pin auto-built LeWorldModel assets with --lewm-revision <40-char-commit-sha>.

The second command is checkout-safe: no credentials or optional model runtimes.

Walkthrough: Robotics Replay Showcase · Technical deep dive · Rerun · Demo showcases

scripts/robotics-showcase --no-tui
uv run --extra rerun worldforge-demo-rerun
uvx --from "rerun-sdk>=0.24,<0.32" rerun /tmp/worldforge-robotics-showcase/real-run.rrd

Capability Model

A capability is an operation an adapter actually supports, not the upstream model’s branding. Unknown names raise. Unsupported calls raise. Empty results are not a substitute for “not implemented.”

Register a full BaseProvider, or a narrow Cost, Policy, Predictor, or Embedder protocol implementation. The protocol path is one name, optional profile metadata, and the one method behind the advertised capability.

LeWorldModel is a score provider, not a video generator. Cosmos-Policy, GR00T, and LeRobot are policy providers, not predictive world models. The planning backbone composes those narrow surfaces.

Provider Surfaces

jepa is a score-only adapter for host-owned facebookresearch/jepa-wms torch-hub runtimes. genie remains a capability-closed reservation. Candidates stay outside package exports and auto-registration until they have a validated runtime path, typed parser coverage, request limits, and docs.

Architecture

┌──────────────────────────────────────────────────────────┐
│  Host application / CLI                                  │
└────────────────────────────┬─────────────────────────────┘
                             │
                             ▼
┌──────────────────────────────────────────────────────────┐
│  WorldForge                                              │
│  catalog · capability dispatch · diagnostics · eval      │
│                                                          │
│     LatentMPCController   (CEM / receding horizon)       │
└──────────────┬─────────────────────────────┬─────────────┘
               │ score / predict / policy    │
               ▼                             ▼
┌───────────────────────────┐    ┌─────────────────────────┐
│  Provider adapter         │    │  Typed results          │
│  contract · validation    │───▶│  scores, plans, payloads│
│  events                   │    └─────────────────────────┘
└──────────────┬────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────┐
│  Upstream runtime (host-owned)                           │
│  mock · LeWorldModel · LeRobot · GR00T · Cosmos-Policy   │
└──────────────────────────────────────────────────────────┘

There is no symbolic World runtime and no built-in world store. Planning runs over plain JSON world-state dicts. Durable persistence, robot execution, and optional ML runtimes are host-owned.

Project Status

WorldForge is pre-1.0 beta (0.5.0). Public APIs can still change when the contract needs to tighten; breaking changes are recorded in the changelog.

The claim-to-evidence map links README-level capability and runtime claims to tests, commands, artifacts, and non-claims.

Development

uv sync --group dev
uv lock --check
uv run ruff check src tests examples scripts
uv run ruff format --check src tests examples scripts
uv run python scripts/generate_provider_docs.py --check
uv run python scripts/check_docs_commands.py
uv run python scripts/check_docs_snippets.py
uv run python scripts/check_wrapper_portability.py
uv run python scripts/check_optional_import_boundaries.py
uv run python scripts/check_core_performance.py
uv run mkdocs build --strict
uv run pytest
uv run --extra harness pytest --cov=src/worldforge --cov-report=term-missing --cov-fail-under=90
bash scripts/test_package.sh
uv build --out-dir dist --clear --no-build-logs

Before a tag, run the locked dependency audit and generate release evidence, notes, and the quality dashboard. Raw details are sanitized so host-local paths, signed URLs, and secret-shaped keys stay out of attachable output. Expanded gate and triage: operator playbooks. If local setup fails first, run uv run python scripts/contributor_doctor.py --format markdown.

uv run python scripts/scaffold_provider.py "Acme WM" \
  --taxonomy "JEPA latent predictive world model" \
  --implementation-status scaffold \
  --planned-capability score

Contributor guide: CONTRIBUTING.md. Agent context: AGENTS.md.

Citing WorldForge

@software{worldforge,
  title   = {WorldForge: An integration layer for physical-AI world models},
  author  = {AbdelStark and {WorldForge contributors}},
  year    = {2026},
  url     = {https://github.com/AbdelStark/worldforge},
  version = {0.5.0}
}

Contributing

Issues, discussions, and pull requests are welcome. Read CONTRIBUTING.md and open an issue for non-trivial changes before sending a patch. Provider work starts at the provider authoring guide and playbooks. External adopters can share integration stories through the adoption case-study template.

License

WorldForge is released under the MIT License.

Resources

Contributors

Abdel 💻 🤔 📆

0xLucqs 💻

Thomas Marchand 💻

Omar U. Espejel 💻

Adrien Lacombe 💻

Made with love by Abdel and the WorldForge community.