Module config 

fdl.yml manifest loading, validation, and resolved-command types. fdl.yaml configuration loading and discovery.

Walks up from CWD to find the project manifest, parses YAML/JSON, and loads sub-command configs from registered command directories.

The implementation is split across topic files; this mod.rs re-exports the public surface so external callers can continue using crate::config::Type paths unchanged.

Structs

ArgSpec

A positional argument.

ClusterConfig

Cluster topology, parsed from the cluster: block at the project root. Two role-separated sub-blocks:

ClusterController

Controller-side cluster config. Holds the rendezvous bind point and pre-flight build context. The controller is the orchestrator host fdl-cli runs on; it is NOT a NCCL rank itself.

ClusterWorker

One worker (a physical host running one or more NCCL ranks).

CommandConfig

Sub-command fdl.yaml (e.g., ddp-bench/fdl.yaml).

CommandSpec

A command at any nesting level. Three mutually-exclusive kinds are recognised at resolve time:

DdpConfig

DDP configuration. Maps 1:1 to flodl DdpConfig / DdpRunConfig.

OptionSpec

A flag option, --name / -x.

OutputConfig

Output settings.

ProjectConfig

Root fdl.yaml at project root.

ResolvedConfig

Fully resolved configuration ready for arg translation.

Schema

The schema declared inline in a sub-command’s fdl.yaml. Maps 1:1 to what <entry> --fdl-schema will later emit as JSON. deny_unknown_fields also applies to the --fdl-schema probe JSON: a schema emitted by a NEWER flodl-cli-macros than this fdl knows fails to parse rather than silently dropping the unknown field, and the probe layer falls back to the inline yml schema (or none) — help always renders (see schema_cache).

SpeedHint

SshConfig

SSH endpoint configuration for a remote worker host.

TrainingConfig

Training scalars.

Enums

CommandKind

What kind of command is this, resolved from a CommandSpec.

LocalDevices

CUDA device indices on a host. Either explicit (a list of indices) or the "all" shorthand (auto-detect at startup on that host).

Constants

DEFAULT_CONTROLLER_PORT

Default port for the controller’s rendezvous bind. Overridable via cluster.controller.port: in fdl.cluster.yml.

DEFAULT_DATA_PATH

Convention default for ClusterWorker::data_path / ClusterController::data_path when the entry does not declare one. Maps to the cross-node mount that holds training data + checkpoints + per-rank logs.

Functions

cluster_dispatch_enabled

Whether the leaf command’s effective cluster: value resolves to true AND a cluster: topology is declared at the project root.

config_layer_sources

Source path list for a base config + env overlay, in merge order. Used by fdl config show to annotate which layer a value came from.

defaults_only

Resolved config from root defaults only (no job).

find_config

Walk up from start looking for fdl.yaml.

find_config_in

Locate the project config inside dir only — no walk-up, no example-copy prompt. For resolvers that already hold the project root and must not block on interactive prompts.

load_command

Load a command config from a sub-directory.

load_command_with_env

Load a sub-command config with an optional environment overlay.

load_merged_value

Load the raw merged serde_yaml_ng::Value for a config + optional env overlay. Exposed so callers like fdl config show can inspect the resolved view before it is deserialized into a strongly-typed struct.

load_project

Load a project config from a specific path.

load_project_with_env

Load a project config with an optional environment overlay.

merge_preset

Merge the enclosing CommandConfig defaults with a named preset’s overrides. Preset values win. Used when dispatching an inline preset command (neither run nor path).

resolve_cluster_dispatch

Resolve whether a leaf command should fan out across the cluster, given the chain of super::schema::CommandSpec::cluster directives along its command path, ordered root → leaf.

resolve_config_layers

Resolve every layer contributing to a config, in merge order, with inherit-from: chains expanded. Paired with the base file + optional env overlay, the result is [chain(base)..., chain(env_overlay)...] de-duplicated by canonical path (kept-first).

schema_to_args_spec

Convert a Schema into an ArgsSpec suitable for strict-mode tail validation. Positional required flags are intentionally dropped: the binary itself will enforce them after parsing, and treating them as required here would turn “missing positional” into a double-errored mess.

validate_preset_for_exec

Validate a single preset that’s about to be invoked. Combines the always-on choices: check and, if schema.strict, the unknown-key rejection — scoped to just this preset, not the whole commands: map. Called from the exec path so typos in a sibling preset don’t block --help for a correct one.

validate_preset_values

Always-on: validate preset YAML options: values against declared choices: in the schema. An option YAML value whose key matches a declared option with a choices: list must be one of those choices. Keys not declared in the schema are ignored here — those are the concern of validate_presets_strict (opt-in).

validate_presets_strict

At load time, reject preset options: keys that are not declared in the enclosing schema. Runs only when schema.strict == true, and only against entries resolved to CommandKind::Preset — run: and path: kinds don’t share the parent schema.

validate_schema

Check a schema for collisions and structural issues.

validate_tail

Validate the user’s extra argv tail against a schema. Always called before run::exec_command — the parser’s lenient-unknowns mode is keyed off schema.strict so choice validation on declared flags fires regardless, while unknown-flag rejection stays opt-in.