WorldFoundry
EnglishδΈ­ζ–‡

Core configuration

Deferred constructor graphs, structured inference config, recursive instantiation, and freeze behavior.

Edit this pageGitHubMarkdown

On this page
Deferred construction exampleStructured released-model configComplete reference

Core configuration separates describing an object graph from constructing expensive model objects. LazyCall(target)(...) records a target plus named arguments in an editable OmegaConf node; instantiate walks the graph and creates the objects only when the runtime is ready.

This package requires attrs and omegaconf (provided by the video/model runtime environments, not the minimal CLI install).

Deferred construction example

from torch import nn

from worldfoundry.core.configuration import LazyCall, instantiate

Linear = LazyCall(nn.Linear)
layer_config = Linear(in_features=8, out_features=4, bias=False)

# Config composition can still change the graph without a live module.
layer_config.out_features = 6
layer = instantiate(layer_config)

assert isinstance(layer, nn.Linear)
assert layer.in_features == 8
assert layer.out_features == 6

LazyCall accepts keyword arguments only. Defaults from the target signature are recorded before explicit values are applied. Nested lists and mappings are instantiated recursively unless a config sets _recursive_=False; unknown mappings and primitive values pass through unchanged.

Structured released-model config

Config and its nested attrs classes hold the small, shared part of released inference configuration: the deferred model graph, checkpoint source, runtime/CuDNN settings, model-parallel settings, and job identity. Model-specific fields remain in the model's own lazy graph.

make_freezable adds a recursive freeze() operation to attrs classes declared with slots=False. Freezing is a runtime guard against accidental mutation after composition; it does not make referenced PyTorch modules immutable.

Complete reference

The blocks below are the generated signatures for this category. Use the on-page symbol index to jump; source links open the defining implementation behind each lazy export.

9 public symbols

CheckpointConfig

cls
class CheckpointConfig(load_path: str = '',load_from_object_store: ObjectStoreConfig = attrs.field(factory=ObjectStoreConfig),strict_resume: bool = True,dcp_allow_mismatched_size: bool = False,load_ema_to_reg: bool = False)
worldfoundry.core.configuration.CheckpointConfigfrom worldfoundry.core.configuration import CheckpointConfig
source

Overview

Checkpoint source and strictness controls for inference construction. Belongs to Core configuration (LazyConfig / deferred object graphs).

Attributes

load_pathstr
default: ''
load_from_object_storeObjectStoreConfig
default: attrs.field(factory=ObjectStoreConfig)
strict_resumebool
default: True
dcp_allow_mismatched_sizebool
default: False
load_ema_to_regbool
default: False

Config

cls
class Config(model: LazyDict | None,job: JobConfig = attrs.field(factory=JobConfig),trainer: InferenceRuntimeConfig = attrs.field(factory=InferenceRuntimeConfig),model_parallel: _ModelParallelConfig = attrs.field(factory=_ModelParallelConfig),checkpoint: CheckpointConfig = attrs.field(factory=CheckpointConfig))
worldfoundry.core.configuration.Configfrom worldfoundry.core.configuration import Config
source

Overview

Fields used to compose and instantiate a released inference model. Belongs to Core configuration (LazyConfig / deferred object graphs).

Attributes

modelLazyDict | None
jobJobConfig
default: attrs.field(factory=JobConfig)
trainerInferenceRuntimeConfig
default: attrs.field(factory=InferenceRuntimeConfig)
model_parallel_ModelParallelConfig
default: attrs.field(factory=_ModelParallelConfig)
checkpointCheckpointConfig
default: attrs.field(factory=CheckpointConfig)

Methods

methto_dict() -> dict[str, Any]source

Overview

Public method on this type.

Returns: dict[str, Any]

methvalidate() -> Nonesource

Overview

Validate the small set of fields needed during inference.

Returns: None

EMAConfig

cls
class EMAConfig(enabled: bool = False,rate: float = 0.1,iteration_shift: int = 0)
worldfoundry.core.configuration.EMAConfigfrom worldfoundry.core.configuration import EMAConfig
source

Overview

Exponential moving-average settings used while loading inference models. Belongs to Core configuration (LazyConfig / deferred object graphs).

Attributes

enabledbool
default: False
ratefloat
default: 0.1
iteration_shiftint
default: 0

instantiate

func
def instantiate(cfg,*args,**kwargs)
worldfoundry.core.configuration.instantiatefrom worldfoundry.core.configuration import instantiate
source

Overview

Materialize a LazyConfig / LazyCall object graph into concrete Python objects.

Parameters

cfg
a dict-like object with "_target_" that defines the caller, and other keys that define the arguments
args
Optional positional parameters pass-through.
kwargs
Optional named parameters pass-through.

LazyCall

cls
class LazyCall(target)
worldfoundry.core.configuration.LazyCallfrom worldfoundry.core.configuration import LazyCall
source

Overview

Deferred constructor call used in LazyConfig graphs so objects are built only at instantiate time.

Source docstring

Wrap a callable so that when it's called, the call will not be executed, but returns a dict that describes the call.

LazyCall object has to be called with only keyword arguments. Positional arguments are not yet supported.

Example:: from worldfoundry.core.configuration import LazyCall, instantiate

layer_cfg = LazyCall(nn.Conv2d)(in_channels=32, out_channels=32) layer_cfg.out_channels = 64 # can edit it afterwards layer = instantiate(layer_cfg)

Parameters

target
Callable to instantiate later, its importable string name, or an existing target mapping.

Methods

meth__call__(**kwargs)source

Overview

Return an editable config instead of invoking the target.

Parameters

kwargs
Named constructor arguments. Target defaults are copied first, then explicit values override them.

Notes

Positional arguments are intentionally unsupported at this stage; they can be supplied later to `instantiate` when necessary.

LazyConfig

cls
class LazyConfig()
worldfoundry.core.configuration.LazyConfigfrom worldfoundry.core.configuration import LazyConfig
source

Overview

Load local Python/YAML lazy configs and save resolved inference configs. Belongs to Core configuration (LazyConfig / deferred object graphs).

Methods

smethload_rel(filename: str, keys: str | tuple[str, ] | None = None)source

Overview

Public staticmethod on this type.

Parameters

filenamestr
keysstr | tuple[str, ...] | None
default: None
smethload(filename: str, keys: str | tuple[str, ] | None = None)source

Overview

Public staticmethod on this type.

Parameters

filenamestr
keysstr | tuple[str, ...] | None
default: None
smethsave_yaml(config: Any, filename: str | Path) -> strsource

Overview

Public staticmethod on this type.

Parameters

configAny
filenamestr | Path

Returns: str

LazyDict

cls
class LazyDict(args, **kwargs)
worldfoundry.core.configuration.LazyDictfrom worldfoundry.core.configuration import LazyDict
source

Overview

Marker subclass for editable, lazily instantiated object graphs. Belongs to Core configuration (LazyConfig / deferred object graphs).

Source docstring

Marker subclass for editable, lazily instantiated object graphs.

It behaves like OmegaConf `DictConfig but lets WorldFoundry distinguish a deferred constructor tree from an ordinary runtime mapping. Construct it through LazyCall` in normal code.

Parameters

args
kwargs

make_freezable

func
def make_freezable(cls: T) -> T
worldfoundry.core.configuration.make_freezablefrom worldfoundry.core.configuration import make_freezable
source

Overview

Add a recursive runtime `freeze operation to an attrs class. Belongs to Core configuration (LazyConfig / deferred object graphs). Annotated return type: T`.

Parameters

clsT

Returns: T

ObjectStoreConfig

cls
class ObjectStoreConfig(enabled: bool = False,credentials: str = '',bucket: str = '')
worldfoundry.core.configuration.ObjectStoreConfigfrom worldfoundry.core.configuration import ObjectStoreConfig
source

Overview

Object-store location used to read inference checkpoints. Belongs to Core configuration (LazyConfig / deferred object graphs).

Attributes

enabledbool
default: False
credentialsstr
default: ''
bucketstr
default: ''