AIR CLI Integration: -h for yaml configuration

acceptance/experimental/air/config-help/output.txt

@@ -0,0 +1,110 @@
+
+=== command help
+>>> [CLI] experimental air run --help
+Submit a training workload to Databricks serverless GPU compute.
+
+The workload is described by a YAML config file (see --file).
+
+To look up a config field, pass its path to -h:
+
+  databricks experimental air run -h config
+  databricks experimental air run -h config.compute
+  databricks experimental air run -h config.compute.accelerator_type
+
+The path must be a separate argument: cobra reserves -h as a boolean, so
+-h=config.compute and -hconfig.compute are not accepted.
+
+Usage:
+  databricks experimental air run [flags]
+
+Flags:
+      --dry-run                  Validate the config without submitting
+  -f, --file string              Path to the workload YAML config
+  -h, --help                     help for run
+      --idempotency-key string   Return the existing run if this key was already used
+      --override stringArray     Override a YAML field, e.g. compute.num_accelerators=8 (repeatable)
+      --watch                    Stream logs until the run completes
+
+Global Flags:
+      --debug            enable debug logging
+  -o, --output type      output type: text or json (default text)
+  -p, --profile string   ~/.databrickscfg profile
+  -t, --target string    bundle target to use (if applicable)
+
+=== schema overview
+>>> [CLI] experimental air run -h config
+config
+  The run YAML schema. Pass a field path for details, e.g. config.compute.accelerator_type.
+
+  Fields:
+    experiment_name              (required) Name of the experiment.
+    compute                      (required) Which accelerators to run on and how many.
+    environment                  Python dependencies, or a custom Docker image, for the run's runtime.
+    command                      (required) Shell command that starts the workload.
+    env_variables                Plain environment variables, as NAME: value.
+    secrets                      Environment variables sourced from secrets, as NAME: scope/key.
+    code_source                  Local code to upload and make available to the run.
+    max_retries                  How many times to retry a failed run.
+    timeout_minutes              Wall-clock limit for the run in minutes.
+    idempotency_token            Reuse token: a repeat submission with the same token returns the existing run instead of starting another.
+    parameters                   Free-form values passed through to the workload.
+    mlflow_run_name              Name for the MLflow run.
+    mlflow_experiment_directory  Workspace directory holding the MLflow experiment.
+    permissions                  Who may view or manage the run, as a list of principal plus level grants.
+    usage_policy_name            Usage policy to bill the run to, by name.
+    usage_policy_id              Usage policy to bill the run to, by id.
+
+Use "-h config.<field>" for details on a field.
+
+=== nested object lists its fields
+>>> [CLI] experimental air run -h config.compute
+config.compute
+  Which accelerators to run on and how many.
+
+  Fields:
+    num_accelerators  Total number of GPUs to allocate.
+    accelerator_type  Which accelerator to run on, e.g. GPU_1xA10.
+
+Use "-h config.compute.<field>" for details on a field.
+
+=== leaf field
+>>> [CLI] experimental air run -h config.compute.accelerator_type
+config.compute.accelerator_type
+  Which accelerator to run on, e.g. GPU_1xA10. See https://docs.databricks.com/aws/en/machine-learning/ai-runtime/cli/yaml-config#reference for the current list of supported GPU types. Matched case-sensitively.
+
+  Type:     string
+  Required: no
+
+=== conditionally required leaf
+>>> [CLI] experimental air run -h config.environment.docker_image.url
+config.environment.docker_image.url
+  Fully qualified image URL, e.g. myregistry.io/team/train:v3.
+
+  Type:     string
+  Required: when environment.docker_image is set
+
+=== union field reports both accepted shapes
+>>> [CLI] experimental air run -h config.code_source.snapshot.git.remote
+config.code_source.snapshot.git.remote
+  No longer supported: the snapshot archives your local copy. Only false is accepted; use commit to pin a revision.
+
+  Type:     bool or string
+  Required: no
+
+=== the config. prefix is optional
+>>> [CLI] experimental air run -h compute.num_accelerators
+config.compute.num_accelerators
+  Total number of GPUs to allocate. Must be a positive multiple of the accelerator type's per-node GPU count. See https://docs.databricks.com/aws/en/machine-learning/ai-runtime/cli/yaml-config#reference for supported GPU types.
+
+  Type:     int
+  Required: no
+
+=== unknown field suggests the near match
+>>> [CLI] experimental air run -h config.compute.acclerator_type
+Error: unknown config field "config.compute.acclerator_type"; did you mean "accelerator_type"?
+
+fields under "config.compute" are: accelerator_type, num_accelerators
+
+=== free-form map keys are not schema fields
+>>> [CLI] experimental air run -h config.parameters.learning_rate
+Error: "config.parameters" holds user-defined keys, so "learning_rate" is not part of the schema; see "config.parameters" instead

acceptance/experimental/air/config-help/script

@@ -0,0 +1,31 @@
+# Pin the rendered config field help. Any change to a `help:` struct tag on the
+# run YAML schema shows up as a diff here.
+
+# Plain -h must keep documenting the command itself, and advertise the config
+# path syntax so the feature is discoverable.
+title "command help"
+trace $CLI experimental air run --help
+
+title "schema overview"
+trace $CLI experimental air run -h config
+
+title "nested object lists its fields"
+trace $CLI experimental air run -h config.compute
+
+title "leaf field"
+trace $CLI experimental air run -h config.compute.accelerator_type
+
+title "conditionally required leaf"
+trace $CLI experimental air run -h config.environment.docker_image.url
+
+title "union field reports both accepted shapes"
+trace $CLI experimental air run -h config.code_source.snapshot.git.remote
+
+title "the config. prefix is optional"
+trace $CLI experimental air run -h compute.num_accelerators
+
+title "unknown field suggests the near match"
+trace $CLI experimental air run -h config.compute.acclerator_type
+
+title "free-form map keys are not schema fields"
+trace $CLI experimental air run -h config.parameters.learning_rate

experimental/air/cmd/compute.go

@@ -54,8 +54,8 @@ func gpusPerNode(g gpuType) (int, error) {
 // computeConfig is the `compute` block of the run YAML: which accelerators to
 // use and how many.
 type computeConfig struct {
-	NumAccelerators int    `yaml:"num_accelerators"`
-	AcceleratorType string `yaml:"accelerator_type"`
+	NumAccelerators int    `yaml:"num_accelerators" help:"Total number of GPUs to allocate. Must be a positive multiple of the accelerator type's per-node GPU count. See https://docs.databricks.com/aws/en/machine-learning/ai-runtime/cli/yaml-config#reference for supported GPU types."`
+	AcceleratorType string `yaml:"accelerator_type" help:"Which accelerator to run on, e.g. GPU_1xA10. See https://docs.databricks.com/aws/en/machine-learning/ai-runtime/cli/yaml-config#reference for the current list of supported GPU types. Matched case-sensitively."`
 }
 
 // validate checks the compute block against the backend's constraints.

experimental/air/cmd/run.go

@@ -36,9 +36,36 @@ func newRunCommand() *cobra.Command {
 		Short: "Submit a training workload from a YAML config",
 		Long: `Submit a training workload to Databricks serverless GPU compute.
 
-The workload is described by a YAML config file (see --file).`,
+The workload is described by a YAML config file (see --file).
+
+To look up a config field, pass its path to -h:
+
+  databricks experimental air run -h config
+  databricks experimental air run -h config.compute
+  databricks experimental air run -h config.compute.accelerator_type
+
+The path must be a separate argument: cobra reserves -h as a boolean, so
+-h=config.compute and -hconfig.compute are not accepted.`,
 	}
 
+	// cobra passes -h's positional args to the help func before Args/required-flag
+	// validation, so a config path documents a field without needing -f.
+	cmd.SetHelpFunc(func(c *cobra.Command, args []string) {
+		fields := c.Flags().Args()
+		if len(fields) == 0 {
+			// Parent() is nil for a detached command (unit tests).
+			if parent := c.Parent(); parent != nil {
+				parent.HelpFunc()(c, args)
+				return
+			}
+			_ = c.Usage()
+			return
+		}
+		if err := writeConfigFieldHelp(c.OutOrStdout(), fields[0]); err != nil {
+			c.PrintErrln("Error:", err)
+		}
+	})
+
 	cmd.Flags().StringVarP(&file, "file", "f", "", "Path to the workload YAML config")
 	cmd.Flags().BoolVar(&watch, "watch", false, "Stream logs until the run completes")
 	cmd.Flags().StringArrayVar(&overrides, "override", nil, "Override a YAML field, e.g. compute.num_accelerators=8 (repeatable)")