WorldFoundry
English中文

Quickstart

Configure the environment, prepare assets, use the TUI or CLI, then run inference and evaluation.

Edit this pageGitHubMarkdown

On this page
WorkflowPrerequisites1. Environment2. Assets3. TUI4. CLI5. Inference6. EvaluationWhere details live

This guide walks through the shortest complete path from a clone to a reviewable WorldFoundry run:

Most runs follow the same shape even when the model or benchmark changes: make the Python environment importable, discover stable IDs, prepare only the required checkpoints and benchmark assets, generate artifacts, inspect them, and only then score them.

Tip

You do not need a GPU or model weights to browse catalogs and inspect readiness. Complete environment and discovery checks, read the reported blockers, and stop before asset download if you are only evaluating coverage.

Workflow

Create the conda environment and source WorldFoundry paths.

Prepare only the model checkpoints, benchmark data, and metric assets needed for the run.

Use the TUI when you want an interactive command builder, or use the CLI commands below when scripting.

Run inference first. Run benchmark scoring only after generated artifacts match the benchmark layout.

Prerequisites

  • OS: Linux recommended for GPU inference and most benchmark runners
  • Install track: use python -m pip install -e ".[tui]" for lightweight CPU catalog/CLI/TUI work; use bash scripts/setup/bootstrap_worldfoundry.sh for the CUDA conda runtime. That bootstrap is the official first-clone script; it already calls scripts/setup/unified_install.sh to create the unified GPU env, so you do not start from unified_install.sh unless you are only refreshing that env. Optional extras do not select a CUDA PyTorch wheel index.
  • Python: 3.10+; the GPU path manages it through the WorldFoundry unified conda environment
  • Optional: CUDA-capable GPU, Hugging Face token for gated checkpoints

Note

Catalog browsing and readiness inspection work without weights. The expensive path begins only when you choose a concrete model run and download assets.

1. Environment

The commands below describe the GPU runtime path. The official first-clone command is bash scripts/setup/bootstrap_worldfoundry.sh. It creates the default WorldFoundry runtime and writes a local shell file with the paths used by the CLI, Studio, and evaluation runners. Always source that file before running commands in a new shell.

Start from the repository root. Model demo videos are served from GitHub CDN; docs development does not need git lfs pull.

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/OpenEnvision/WorldFoundry.git
cd WorldFoundry

bash scripts/setup/bootstrap_worldfoundry.sh
source tmp/worldfoundry_unified_env.sh
conda activate "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}"

Next

Detailed environment mapping by model and benchmark lives in Environment. Use that page when a model needs an extra conda profile or a benchmark evaluator depends on a metric package outside the unified runtime.

2. Assets

WorldFoundry keeps executable code in-tree. Checkpoints, datasets, metric weights, reference files, and generated outputs are staged locally, usually through Hugging Face.

Important

Model assets and benchmark assets are separate. A model checkpoint lets you generate candidate artifacts; benchmark assets define what to generate, how outputs should be named, and which files or metric weights are needed to compute scores.

bash scripts/inference/prepare_model_infer.sh <model-id> --verify-env-only
bash scripts/inference/prepare_model_infer.sh <model-id> --download
worldfoundry-eval zoo model-download --model-id <model-id> --check-local --json

Use HF_TOKEN only for gated assets whose terms you have accepted:

export HF_TOKEN=<your-huggingface-token>

Full cache and path conventions are in Local assets.

3. TUI

Use the TUI when you do not want to remember IDs and flags. It reads the same manifests as the CLI, shows the available choices, and can print the final command before anything expensive runs.

python -m pip install -e ".[tui]"
worldfoundry-eval tui

Generate a command without entering the interactive session:

worldfoundry-eval tui \
  --model-id <model-id> \
  --benchmark-id <benchmark-id> \
  --print-command

Note

The TUI does not bypass missing checkpoint, dataset, license, or environment requirements. If it prints a command for a benchmark whose assets are not staged yet, run the benchmark asset preparation step first.

4. CLI

Use the CLI for scripts, batch jobs, and reproducible notes. Start with the discovery commands instead of guessing IDs:

worldfoundry-eval zoo models --json
worldfoundry-eval zoo benchmarks --json
worldfoundry-eval zoo model-download --model-id <model-id> --check-local --json

The canonical first inference command for reproducible and documented runs is worldfoundry-eval run <id> --pipeline.task-profile …. Copy <id> and the task profile from the model page; worldfoundry-eval run <id> --help lists the typed flags.

worldfoundry-eval run <model-id> \
  --pipeline.task-profile <task-profile> \
  --output-dir tmp/worldfoundry_infer/<model-id>

Which command. Everyday reproducible runs and the commands on model pages use worldfoundry-eval run. Use python -m worldfoundry.studio.workspace_job infer only for Workspace visual smoke. See CLI entrypoints.

Workspace visual smoke (the same job path the Studio UI submits):

python -m worldfoundry.studio.workspace_job infer \
  --model-id <model-id> \
  --prompt "a cinematic scene, high quality" \
  --output-dir tmp/worldfoundry_infer/<model-id> \
  --device cuda

The full command map is in CLI. Run-status labels are in Run status.

5. Inference

Inference produces artifacts. It does not produce benchmark evidence by itself.

Important

A generated video can look correct in Studio and still fail a benchmark run if filenames, prompt coverage, split, or metadata do not match what the benchmark runner expects.

The practical loop is: generate a small batch, inspect the outputs, confirm the directory layout, and then scale to the full prompt set required by the target benchmark.

For repeated visual review, start the workspace:

bash scripts/workspace/run_workspace.sh

Open http://127.0.0.1:7870/ and inspect outputs before scoring:

find tmp/worldfoundry_infer/<model-id> -maxdepth 2 -type f | head

More details: Run inference and Studio.

6. Evaluation

A benchmark run needs three concrete inputs. If any one is missing, the runner should stop with a blocked scorecard rather than silently producing a leaderboard-looking number.

  • Benchmark assets — Prompt/task metadata, reference files, official result files, judge credentials, simulator assets, or metric checkpoints.
  • Candidate artifacts — Videos, frames, rollouts, traces, or official-shaped result dumps produced by the model.
  • Runner mode — official-validation imports existing official-shaped results; official-run computes scores from generated artifacts.

If the official benchmark already produced a result file, import it:

worldfoundry-eval zoo benchmark-run \
  --benchmark-id <benchmark-id> \
  --mode official-validation \
  --official-results-path /path/to/official/results-or-report \
  --generated-artifact-dir /path/to/generated/artifacts \
  --output-dir tmp/<benchmark-id>/official-validation \
  --json

Tip

Open scorecard.json first. Public leaderboard claims require complete assets, complete generated artifacts, and benchmark-specific eligibility flags.

Where details live

Environment

Conda profiles and setup scripts by model and benchmark family.

Local assets

Checkpoint sources, Hugging Face cache paths, and readiness checks.

TUI

Interactive model and benchmark picker that prints runnable commands.

CLI

Full command reference for discovery, inference, scoring, and reporting.

Run status

Reader labels for Verified, Runner parity pending, Static load only, and Planned.

Benchmark Hub

Benchmark-specific data layouts, metric assets, and run commands.