Factory Functions

The main entry points for creating and managing world models.

For docstring-derived details, see Factory API (Autogenerated).

create_world_model

Create a world model from a preset, alias, or saved path.

from worldflux import create_world_model

model = create_world_model(
    model="dreamerv3:size12m",
    obs_shape=(3, 64, 64),
    action_dim=4,
    device="cpu",
)

If you request a non-native backend via backend=..., create_world_model() returns an OfficialBackendHandle instead of instantiating a local PyTorch model. Pass that handle to Trainer(...).submit() or execution/parity flows.

Parameters

Parameter	Type	Default	Description
model	str	required	Model preset, alias, or path to a saved model
obs_shape	tuple[int, ...]	None	Optional observation-shape override for the selected preset/config
action_dim	int	None	Optional action-dimension override (defaults to config value, typically 6)
device	str	"cpu"	Device to place model on
api_version	str	"v3"	API compatibility mode
**kwargs			Config overrides for the selected model family

Model Specifiers

Presets (type:size)

model = create_world_model("dreamerv3:size12m", ...)
model = create_world_model("tdmpc2:5m", ...)

CI Presets (*:ci)

model = create_world_model("dreamer:ci", ...)
model = create_world_model("tdmpc2:ci", ...)

Aliases

# DreamerV3 aliases
model = create_world_model("dreamer", ...)        # dreamerv3:size12m
model = create_world_model("dreamer-ci", ...)     # dreamer:ci
model = create_world_model("dreamer-small", ...)  # dreamerv3:size12m
model = create_world_model("dreamer-medium", ...) # dreamerv3:size50m
model = create_world_model("dreamer-large", ...)  # dreamerv3:size200m

# TD-MPC2 aliases
model = create_world_model("tdmpc", ...)         # tdmpc2:5m
model = create_world_model("tdmpc2-ci", ...)     # tdmpc2:ci
model = create_world_model("tdmpc-small", ...)   # tdmpc2:5m
model = create_world_model("tdmpc-medium", ...)  # tdmpc2:48m
model = create_world_model("tdmpc-large", ...)   # tdmpc2:317m

The list above shows common aliases. For the current full alias map in your runtime:

from worldflux import MODEL_ALIASES
print(MODEL_ALIASES)

In the current implementation, dreamer family aliases resolve to DreamerV3 presets.

Load from Path

model = create_world_model("./my_saved_model")
model = create_world_model("/path/to/checkpoint")

Config Overrides

model = create_world_model(
    "tdmpc2:19m",
    obs_shape=(39,),
    action_dim=6,
    hidden_dim=768,      # Valid TDMPC2Config field
    num_q_networks=7,    # Valid TDMPC2Config field
)

Use config-field names that exist on the selected config class.

Returns

• backend="native_torch": a local model implementing the WorldModel protocol
• backend!="native_torch": an OfficialBackendHandle for delegated execution

Delegated Backend Example

from worldflux import create_world_model
from worldflux.training import Trainer, TrainingConfig

handle = create_world_model(
    "dreamerv3:official_xl",
    backend="worldflux_dreamerv3_jax_subprocess",
    device="cuda",
)

trainer = Trainer(
    handle,
    TrainingConfig(
        backend="worldflux_dreamerv3_jax_subprocess",
        backend_profile="official_xl",
        device="cuda",
    ),
)
job = trainer.submit()

---

list_models

List available model presets.

from worldflux import list_models

# Supported MVP presets only
models = list_models()

# Supported MVP presets with descriptions
models = list_models(verbose=True)

# Include advanced proof-oriented presets explicitly
models = list_models(verbose=True, surface="public")

# Include experimental / internal families explicitly
models = list_models(verbose=True, surface="all")

Parameters

Parameter	Type	Default	Description
verbose	bool	False	Return detailed metadata instead of only names
maturity	str | None	None	Optional maturity filter (reference, experimental, skeleton)
surface	str	"supported"	Public surface filter. One of "supported", "public", or "all"

Returns

• verbose=False: list[str] of model names
• verbose=True: dict[str, dict] with catalog metadata

---

Reference Presets

DreamerV3

Preset	Approx Params	deter_dim	stoch_discrete	stoch_classes
dreamer:ci	~0.1M	64	4	4
dreamerv3:size12m	~12M	2048	16	16
dreamerv3:size25m	~25M	4096	32	16
dreamerv3:size50m	~50M	4096	32	32
dreamerv3:size100m	~100M	8192	32	32
dreamerv3:size200m	~200M	8192	32	32
dreamerv3:official_xl	~200-300M	8192	32	64

TD-MPC2

Preset	Approx Params	latent_dim	hidden_dim	num_q_networks
tdmpc2:ci	~0.1M	32	32	2
tdmpc2:5m	~5M	256	256	5
tdmpc2:proof_5m	~5M	256	256	5
tdmpc2:5m_legacy	~5M	256	256	5
tdmpc2:19m	~19M	512	512	5
tdmpc2:48m	~48M	512	1024	5
tdmpc2:317m	~317M	1024	2048	5

Parity Roles

• dreamer:ci, tdmpc2:ci: CI / quick validation / scaffold presets. Do not use them for proof-grade parity.
• dreamerv3:official_xl: Dreamer proof-canonical preset.
• tdmpc2:proof_5m: TD-MPC2 proof-canonical preset.
• tdmpc2:5m: TD-MPC2 compatibility preset.
• tdmpc2:5m_legacy: TD-MPC2 legacy compatibility preset.
• The remaining reference-family presets are for experimentation and capacity tuning.

For advanced proof-oriented presets, use:

worldflux models list --surface public --verbose

For the complete catalog (including experimental/skeleton families), use:

worldflux models list --surface all --verbose