nvidia-nemo-rl-config-conventions

name	nvidia-nemo-rl-config-conventions
description	Configuration conventions for NeMo-RL. YAML is the single source of truth for defaults. Covers TypedDict usage, exemplar YAML updates, and forbidden default patterns.
license	Apache-2.0 AND CC-BY-4.0
metadata	{"when_to_use":"Adding or modifying config fields; reviewing config changes; 'where do I set defaults', 'TypedDict pattern', 'exemplar YAML', 'forbidden default patterns', during code review of config files.","author":"NVIDIA"}

Configuration Conventions

Core Rule

YAML is the single source of truth for defaults. Do not set non-None defaults in code for configuration values. The loaded YAML (and any user overrides) must supply required values.

Access Config Directly

For required attributes, write code like policy_cfg["precision"] and assume it is present. Do not introduce hidden defaults deep in the code.

Express Optionality via TypedDict

Use typing.NotRequired to mark optional attributes. Optional attributes may be absent/None; code may check for their presence.

Where Defaults Live

• Exemplar configs under examples/configs/*.yaml include documented defaults.
• Recipe YAMLs under examples/configs/recipes/**/*.yaml are runnable snapshots and may omit documentation.

Documenting New Config Keys

When adding a new config key to a TypedDict subclass, document:

• The key's purpose
• Valid values/types
• Recommended default (if applicable)

Reflect the default in the exemplar YAMLs under examples/configs/*.yaml.

Recipe YAMLs Must Set defaults

Recipe YAMLs under examples/configs/recipes/**/*.yaml must set defaults: <exemplar>.yaml to inherit from one of the exemplar configs in examples/configs/*.yaml. This keeps recipes minimal — they only override what differs from the exemplar.

If a recipe YAML does not have a defaults key, run:

uv run ./tools/config_cli.py minimize <recipe.yaml>

This will minimize the config and assign the appropriate defaults key.

Accessing NotRequired Fields

When accessing a NotRequired field, use an in check or .get(key) / .get(key, None). Never provide a non-None default — that hides behavior and defeats the purpose of making the field optional.

Do:

# .get() with None (not a hidden default)
stop_properly_penalty_coef = cfg.get("stop_properly_penalty_coef", None)

# Truthiness check for optional booleans
if master_config.grpo.get("skip_reference_policy_logprobs_calculation"):
    ...

# Nested NotRequired: check presence at each level explicitly
if "megatron_cfg" in policy_config and policy_config["megatron_cfg"]["enabled"]:
    ...

Don't:

# Hidden boolean default — should come from YAML
disable_ppo_ratio = cfg.get("disable_ppo_ratio", False)

# Hidden non-trivial default — caller has no idea True is the fallback
normalize_rewards = grpo_config.get("normalize_rewards", True)

# Chained .get() with hidden defaults at each level
megatron_enable = config.get("megatron_cfg", {}).get("enabled", False)

If a NotRequired field is absent, the code should handle that explicitly — not paper over it with a magic default.

Forbidden Patterns

Don't:

# Hidden default in code
precision = policy_cfg.get("precision", "bfloat16")

# Function parameter defaulting a config value
def build_policy(policy_cfg, precision: str = "bfloat16"):
    ...

Do:

# Required attribute: expect it from YAML or user override
precision: str = policy_cfg["precision"]

# Optional attribute: check for presence
if "milestones" in scheduler_cfg:
    configure_milestones(scheduler_cfg["milestones"])

See also: @docs/design-docs/design-and-philosophy.md (TypedDict and Configuration Defaults section).