feat(cli): inline field docs in generated resources-server config

Annotate the config emitted by ng_init_resources_server with inline comments
explaining each non-obvious field (domain, resources_server, policy_model magic
name, datasets/source), addressing friction #7 (no inline documentation in
generated configs). Also modernize the scaffold to emit the canonical `source:`
dataset block instead of the now-deprecated `gitlab_identifier`, so a freshly
created server starts on the recommended schema.

Addresses M6a (epic #1205).

Signed-off-by: Wojciech Prazuch <wprazuch@nvidia.com>

Author: wprazuch

nemo_gym/cli/env.py

@@ -750,36 +750,48 @@ def init_resources_server():  # pragma: no cover
 
     config_fpath = configs_dirpath / f"{server_type_name}.yaml"
     with open(config_fpath, "w") as f:
-        f.write(f"""{server_type_name}_resources_server:
+        f.write(f"""# Resources server: implements verification and any task-specific tools/state.
+{server_type_name}_resources_server:
   {server_type}:
     {server_type_name}:
+      # Module (relative to this server dir) that defines the FastAPI app.
       entrypoint: app.py
+      # Task category, used by `gym list environments`. See the Domain enum for valid values.
       domain: other
+# Agent server: drives the model and talks to the resources server above.
 {server_type_name}_simple_agent:
   responses_api_agents:
     simple_agent:
       entrypoint: app.py
+      # The resources server this agent uses for tools + verification.
       resources_server:
         type: resources_servers
         name: {server_type_name}_resources_server
+      # The model the agent drives. `policy_model` is a magic name resolved at run time
+      # from your --model-name/--model-url flags (or a model-server config).
       model_server:
         type: responses_api_models
         name: policy_model
+      # One entry per dataset split. `source:` declares where the JSONL is fetched from;
+      # `type` selects the backend (gitlab | huggingface). Omit `source` for a purely local file.
       datasets:
       - name: train
         type: train
         jsonl_fpath: resources_servers/{server_type_name}/data/train.jsonl
         num_repeats: 1
-        gitlab_identifier:
+        source:
+          type: gitlab
           dataset_name: {server_type_name}
           version: 0.0.1
           artifact_fpath: train.jsonl
+        # A license is required for train/validation splits.
         license: Apache 2.0
       - name: validation
         type: validation
         jsonl_fpath: resources_servers/{server_type_name}/data/validation.jsonl
         num_repeats: 1
-        gitlab_identifier:
+        source:
+          type: gitlab
           dataset_name: {server_type_name}
           version: 0.0.1
           artifact_fpath: validation.jsonl

tests/unit_tests/test_cli.py

@@ -15,6 +15,7 @@
 import shutil
 import sys
 import tomllib
+import warnings
 from importlib import import_module
 from io import StringIO
 from pathlib import Path
@@ -35,7 +36,7 @@
     init_resources_server,
 )
 from nemo_gym.cli.general import display_help_legacy
-from nemo_gym.config_types import ResourcesServerInstanceConfig
+from nemo_gym.config_types import DatasetConfig, ResourcesServerInstanceConfig
 
 
 # TODO: Eventually we want to add more tests to ensure that the CLI flows do not break
@@ -138,6 +139,23 @@ def test_init_resources_server_includes_domain(self) -> None:
                 # This should not raise an assertion error about missing domain
                 instance_config = ResourcesServerInstanceConfig.model_validate(full_config_dict)
                 assert instance_config is not None
+
+                # The generated config carries inline field documentation (friction #7).
+                config_text = config_file.read_text()
+                assert "# Task category" in config_text
+                assert "policy_model" in config_text and "magic name" in config_text
+
+                # The scaffold emits the canonical `source:` block, not the deprecated
+                # `gitlab_identifier`, so a fresh server starts on the recommended schema.
+                datasets = config_dict[f"{server_name}_simple_agent"]["responses_api_agents"]["simple_agent"][
+                    "datasets"
+                ]
+                train = next(d for d in datasets if d["name"] == "train")
+                assert "gitlab_identifier" not in train
+                assert train["source"]["type"] == "gitlab"
+                with warnings.catch_warnings():
+                    warnings.simplefilter("error", DeprecationWarning)
+                    DatasetConfig.model_validate(OmegaConf.to_container(train, resolve=True))
         finally:
             # Clean up the test server directory
             if server_path.exists():