Core configuration

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

Last updated: Oct 7, 2026

On this page

Deferred construction example Structured released-model config Complete 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

class

`CheckpointConfig`

Source

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.configurationfrom worldfoundry.core.configuration import CheckpointConfig

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

Attributes

load_pathstrdefault ''

load_from_object_storeObjectStoreConfigdefault attrs.field(factory=ObjectStoreConfig)

strict_resumebooldefault True

dcp_allow_mismatched_sizebooldefault False

load_ema_to_regbooldefault False

class

`Config`

Source

class Config(model: LazyDict | None,job: JobConfig = attrs.field(factory=JobConfig),trainer: InferenceRuntimeConfig = attrs.field(factory=InferenceRuntimeConfig),model_parallel: Any = attrs.field(factory=_default_model_parallel),checkpoint: CheckpointConfig = attrs.field(factory=CheckpointConfig))

worldfoundry.core.configurationfrom worldfoundry.core.configuration import Config

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

Attributes

modelLazyDict | None

jobJobConfigdefault attrs.field(factory=JobConfig)

trainerInferenceRuntimeConfigdefault attrs.field(factory=InferenceRuntimeConfig)

model_parallelAnydefault attrs.field(factory=_default_model_parallel)

checkpointCheckpointConfigdefault attrs.field(factory=CheckpointConfig)

Methods

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

Deep-copy this config tree into a plain dict (attrs `asdict`).

Returns

dict[str, Any]

methvalidate() -> NoneSource

Validate the small set of fields needed during inference.

Returns

None

class

`EMAConfig`

Source

class EMAConfig(enabled: bool = False,rate: float = 0.1,iteration_shift: int = 0)

worldfoundry.core.configurationfrom worldfoundry.core.configuration import EMAConfig

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

Attributes

enabledbooldefault False

ratefloatdefault 0.1

iteration_shiftintdefault 0

function

`instantiate`

Source

def instantiate(cfg,*args,**kwargs)

worldfoundry.core.configurationfrom worldfoundry.core.configuration import instantiate

Overview

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

Source docstring

Materialize a LazyCall / Hydra-style config into a live object.

Faster than `hydra.utils.instantiate(..., _convert_=all) for the common case of a mapping with _target_ (see facebookresearch/hydra #1200). Callers may pass extra *args / **kwargs`; keyword overrides win over stored config keys.

Parameters

cfg

A `_target_` mapping, OmegaConf container, list, or any already-materialized value.

args

Extra positional arguments forwarded to the target.

kwargs

Extra keyword arguments that override stored fields.

Returns

The constructed object, a list/ListConfig of constructed objects, a structured dataclass/attrs instance, or *cfg* unchanged when it is not a constructor description.

class

`LazyCall`

Source

class LazyCall(target)

worldfoundry.core.configurationfrom worldfoundry.core.configuration import LazyCall

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

Return an editable config instead of invoking the target.

Parameters

kwargs

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

Returns

OmegaConf `DictConfig containing _target_` and the eventual constructor arguments.

Notes

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

class

`LazyConfig`

Source

class LazyConfig()

worldfoundry.core.configurationfrom worldfoundry.core.configuration import LazyConfig

Overview

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

Source docstring

Load local Python/YAML lazy configs and save resolved inference configs.

Trust boundary: `.py configs are executed (detectron2 LazyConfig design) -- only load Python configs you would run as code. YAML configs are parsed with yaml.safe_load and cannot instantiate arbitrary Python objects; save_yaml only ever emits plain YAML, so framework round-trips are unaffected. Configs needing Python objects belong in .py` files.

Methods

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

Overview

Load a config relative to the *caller's* file, not the process cwd.

Source docstring

Load a config relative to the *caller's* file, not the process cwd.

`inspect.stack()[1] is the caller. <string> (exec` without a filename) cannot resolve a sibling path and is rejected.

Parameters

filenamestr

keysstr | tuple[str, ...] | Nonedefault None

smethload(filename: str,keys: str | tuple[str, ...] | None = None)Source

Overview

Load a trusted `.py config via exec, or YAML via safe_load`.

Source docstring

Load a trusted `.py config via exec, or YAML via safe_load`.

A `.py result drops names starting with _ and keeps only dict / OmegaConf values so helper functions defined in the file do not become config keys. keys` selects a subset after load.

Parameters

filenamestr

keysstr | tuple[str, ...] | Nonedefault None

Raises

SyntaxError: The Python config does not parse.
ValueError: Suffix is not `.py / .yaml / .yml`.

smethsave_yaml(config: Any,filename: str | Path) -> strSource

Overview

Write a resolved, key-sorted YAML snapshot that cannot `exec`.

Source docstring

Write a resolved, key-sorted YAML snapshot that cannot `exec`.

A failed `deepcopy is ignored so an un-copyable live object still serializes through :func:_plain_config` rather than aborting the save.

Parameters

configAny

filenamestr | Path

Returns

str

class

`LazyDict`

Source

class LazyDict(*args,**kwargs)

worldfoundry.core.configurationfrom worldfoundry.core.configuration import LazyDict

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

function

`make_freezable`

Source

def make_freezable(cls: T) -> T

worldfoundry.core.configurationfrom worldfoundry.core.configuration import make_freezable

Overview

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

Source docstring

Add a recursive runtime `freeze` operation to an attrs class.

Freezing is *shallow* with respect to containers: it blocks attribute assignment on the instance (and recursively freezes nested attrs values that expose `freeze`), but the contents of list/dict fields remain mutable. Decorating the same class twice is a no-op.

Parameters

clsT

Returns

class

`ObjectStoreConfig`

Source

class ObjectStoreConfig(enabled: bool = False,credentials: str = '',bucket: str = '')

worldfoundry.core.configurationfrom worldfoundry.core.configuration import ObjectStoreConfig

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

Attributes

enabledbooldefault False

credentialsstrdefault ''

bucketstrdefault ''