WorldFoundry
English中文

Codebase map

Source-level directory-to-responsibility map across the WorldFoundry packages, with key entry files and links to the narrative architecture pages.

Edit this pageGitHubMarkdown

On this page
Repository layoutHow the entries connectWhere to go next

This page is the quick-reference index of the repository: one entry per top-level package, what it owns, and the first file to read. It is deliberately compact. For the why behind these boundaries, read Architecture and the subpages it links to. Use this map to decide where a change belongs before opening a file.

The boundary rule is the same on every entry: a package exposes stable, serializable contracts to its neighbors and keeps private details inside. Cross-package edges that skip the contract layer (for example, a benchmark importing a pipeline, or a pipeline importing an evaluator) are the bugs to look for here.

Repository layout

Package

  • worldfoundry/cli

    User-facing commands: TUI, evaluate, embodied, run, validate, zoo, preflight, reporting. Dispatches into orchestration, never owns model inference or scoring.

    First file cli/main.py:1888 main(); subcommand tree at cli/main.py:1088

  • worldfoundry/cli/tui*.py

    Guided-discovery TUI surfaces (discovery, brand, app).

    First file cli/tui.py, cli/tui_app.py

  • worldfoundry/mcp

    MCP server and tools (discovery, metrics, readiness, context) reused from the same catalog/runtime contracts.

    First file mcp/__init__.py:30 main(); mcp/server.py:38 create_mcp_server; mcp/tools/registration.py:55 register_tools

  • worldfoundry/runtime

    Execution environment preparation: conda profiles, device pool, CUDA tiers, compile cache, in-tree CLI bridges, asset staging.

    First file runtime/conda.py, runtime/env.py, runtime/cuda_tiers.py

  • worldfoundry/data

    Catalogs, runtime profiles, benchmark tasks, and test fixtures. Declares what exists and what is ready; not runtime behavior.

    First file data/models/catalog/, data/benchmarks/catalog/, data/models/runtime/profiles/

  • worldfoundry/core

    Shared inference infrastructure: loading, attention, distributed, VRAM, kernels, memory, configuration, IO, safety. The only home for offload/distributed/kernel/quantization.

    First file Core infrastructure

  • worldfoundry/base_models

    Inference-only model packages: diffusion_model (the single canonical diffusion kernel), llm_mllm_core, perception_core, three_dimensions. No training, datasets, or experiment scripts.

    First file base_models/diffusion_model/__init__.py; Native diffusion

  • worldfoundry/pipelines

    One thin public wrapper per model family: from_pretrained, process/__call__, optional stream.

    First file pipelines/pipeline_utils.py:11 PipelineABC; 88 family dirs under pipelines/

  • worldfoundry/operators

    Input-side partners for runnable pipelines: validation, media loading, camera/action parsing, interaction shaping, perception preprocessing.

    First file operators/base_operator.py:4 BaseOperator

  • worldfoundry/synthesis

    In-tree runtime execution: hosted API wrappers, native runtime bridges, per-family synthesis.py, action surfaces, memory modules.

    First file synthesis/base_synthesis.py:38 BaseSynthesis; Runtime assembly

  • worldfoundry/evaluation

    Public contracts, execution runners, catalog loaders, metrics, reporting, scorecards. The benchmark side of the artifact boundary.

    First file Evaluation core

  • worldfoundry/studio

    Interactive preview shell over the same catalog and runtime contracts. Presentation glue only.

    First file studio/cli.py:78 main(); studio/inference/execution.py, studio/inference/catalog.py; Studio internals

  • worldfoundry/training

    Training and post-training recipes (SFT, distillation, RL). Not on the evaluate/scorecard path.

    First file training/recipes/spec.py

How the entries connect

A run flows down this list, not across it at random. User input enters through cli or mcp; runtime and data prepare the environment and declare what can run; core and base_models provide the shared inference primitives; pipelines plus operators plus synthesis turn a normalized request into a GenerationResult; base_models/three_dimensions runs geometry models and derives geometric artifacts when needed; evaluation consumes artifacts and produces scorecards; studio previews the same artifacts through a UI shell. training sits beside this spine: it produces checkpoints, it does not score them.

The package a file lives in should answer "who owns this kind of change?" before you read the code. If you are unsure which layer owns a fix, start at Architecture and pick the subpage that matches the layer you are changing.

Where to go next