Hydra Configuration

UniRL uses Hydra. Recipes are self-contained YAML files under examples/, organized under diffusion/, ar/, sft/, pe/, unified_model/, and deep_research/, with model subdirectories where needed. Select a recipe with the entrypoint that owns its training domain:

python -m unirl.train_diffusion --config-name=diffusion/sd3/sd3_trainside

Composition

A recipe instantiates each runtime component directly by _target_ (FSDP backend, train stack, rollout engine, reward service, algorithm, data source, …). Config classes are plain @dataclasses defined next to the code that consumes them — there is no ConfigStore and no registration decorator. A recipe wires a component by pointing its _target_ at the class and nesting the component's config: block (also a _target_). Use the generated Config Package README for the instantiation and validation contracts.

Where Knobs Belong

Keep recipe-defining choices in the selected YAML under examples/. Keep cluster-local paths, model mounts, output directories, and WandB identity in launcher environment variables or CLI overrides (recipes interpolate them with ${oc.env:...}). A new typed runtime component should define its config @dataclass next to the implementation; a recipe then references it by _target_ (no registration step).

Override precedence is:

CLI Hydra override > launcher env var > YAML default

Runtime Contracts

--cfg job --resolve stops after Hydra composes the selected YAML and resolves overrides and interpolations such as ${oc.env:...}. It does not instantiate the recipe, check filesystem paths, run dataclass __post_init__ methods, or prove cross-component and batch-geometry compatibility.

Component config dataclass validation runs later, when the owning driver/actor constructs and instantiates that component. The validate_* cross-component helpers in unirl/config/validation.py currently have no live call site, so do not rely on them as a pre-Ray validation phase. Trainer constructors and worker startup contain additional live checks, but reaching those checks requires a real runtime construction path. The available config types and intended contracts are documented in the generated Config Package README.

sync and the tensor transport solve different problems. sync (cfg.sync) sends trainer weights back to dedicated rollout engines, while the tensor transport (unirl/distributed/tensor/) is the data plane for moving bulky rollout outputs between workers.

Use a compose check before launching a large job, but treat it only as a Hydra composition/environment-resolution check:

python -m unirl.train_diffusion \
  --config-name=diffusion/sd3/sd3_trainside \
  --cfg job --resolve