refactor(cli): address review on gym env validate (docs, coverage, real tests)

@cmunley1 review:
- Examples now lead with `gym env validate --environment <env>` / `--benchmark <benchmark>`; reword
  so the model config is clearly optional (NO_MODEL injects a dummy policy_model).
- Remove the `# pragma: no cover` from validate() — it is unit-tested.
- Strengthen TestValidate to run REAL validation (valid config -> ok; unknown cross-ref -> clean
  exit 1) instead of mocking the parser; keep one fast decorator-path unit test.

The real test surfaced that ServerRefNotFoundError (a cross-ref error) was a plain ValueError, so it
escaped exit_cleanly_on_config_error and dumped a traceback. Fold it into the ConfigError family so
cross-reference errors are reported cleanly by validate (and gym env start).

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

Author: wprazuch

nemo_gym/cli/env.py

@@ -865,22 +865,26 @@ def dump_config():  # pragma: no cover
 
 
 @exit_cleanly_on_config_error
-def validate():  # pragma: no cover
+def validate():
     """Validate a config without starting Ray or any server subprocess.
 
     Runs the full config parse — config_paths resolution (missing/malformed), server cross-reference
     validation, mandatory `???` values, and schema — then exits 0 (valid) or, via
     `exit_cleanly_on_config_error`, 1 with a clean traceback-free message. No Ray, no servers, so it
     returns in well under a second instead of after Ray bootstrap.
 
-    Model *values* aren't required: like `gym list`/`env compose`, a dummy `policy_model` is injected
-    so model interpolations (e.g. `${policy_base_url}`) resolve — validation is about config
-    well-formedness; the real model is supplied by the `--model*` flags at run time.
+    No model config is required: a dummy `policy_model` is injected (the `NO_MODEL` parser config, as
+    in `gym list` / `env compose`) so model interpolations (e.g. `${policy_base_url}`) resolve —
+    validation is about config well-formedness, not the model. Pass a model config / `--model-type`
+    as well if you want it validated too.
 
     Examples:
 
     ```bash
-    gym env validate --config resources_servers/<env>/configs/<env>.yaml --config responses_api_models/<model>/configs/<model>.yaml
+    gym env validate --environment <env>
+    gym env validate --benchmark <benchmark>
+    # or by explicit config path(s):
+    gym env validate --config resources_servers/<env>/configs/<env>.yaml
     ```
     """
     global_config_dict = get_global_config_dict(

nemo_gym/config_types.py

@@ -137,10 +137,6 @@ def is_server_ref(config_dict: DictConfig) -> Optional[ServerRef]:
         return None
 
 
-class ServerRefNotFoundError(ValueError):
-    """A server cross-reference points to an instance that is not defined in the merged config."""
-
-
 class ConfigError(Exception):
     """Base for user-facing configuration errors.
 
@@ -167,6 +163,10 @@ class ConfigMissingValuesError(ConfigError, ValueError):
     """One or more required config values are still unset (OmegaConf '???') after merging."""
 
 
+class ServerRefNotFoundError(ConfigError, ValueError):
+    """A server cross-reference points to an instance that is not defined in the merged config."""
+
+
 ########################################
 # Dataset configs for handling and upload/download
 ########################################

tests/unit_tests/test_cli.py

@@ -14,6 +14,7 @@
 # limitations under the License.
 import json
 import shutil
+import sys
 import tomllib
 from importlib import import_module
 from pathlib import Path
@@ -292,15 +293,42 @@ def test_config_error_base_catches_subclasses(self) -> None:
 
 
 class TestValidate:
-    def test_valid_config_prints_ok(self, monkeypatch: MonkeyPatch, capsys) -> None:
-        monkeypatch.setattr(nemo_gym.cli.env, "get_global_config_dict", lambda **k: OmegaConf.create({}))
-
+    def _validate_config(self, monkeypatch: MonkeyPatch, tmp_path: Path, config_yaml: str) -> None:
+        """Run the real `validate()` against a config file (no mocking of the parse path)."""
+        config_file = tmp_path / "config.yaml"
+        config_file.write_text(config_yaml)
+        # chdir to a clean dir so a repo-local env.yaml isn't picked up; clear the parse cache.
+        monkeypatch.chdir(tmp_path)
+        monkeypatch.setattr(sys, "argv", ["gym", f"+config_paths=[{config_file}]"])
+        monkeypatch.setattr(nemo_gym.global_config, "_GLOBAL_CONFIG_DICT", None)
         validate()
 
+    def test_valid_config_passes(self, monkeypatch: MonkeyPatch, tmp_path, capsys) -> None:
+        # A well-formed config (real parse, real checks) -> "valid".
+        self._validate_config(
+            monkeypatch,
+            tmp_path,
+            "my_server:\n  resources_servers:\n    my_server:\n      entrypoint: app.py\n      domain: other\n",
+        )
         assert "valid" in capsys.readouterr().out.lower()
 
-    def test_config_error_exits_nonzero(self, monkeypatch: MonkeyPatch) -> None:
-        # A ConfigError raised during the parse is turned into a clean exit(1), no traceback.
+    def test_unknown_cross_reference_exits_nonzero(self, monkeypatch: MonkeyPatch, tmp_path) -> None:
+        # An agent referencing a resources server that isn't defined -> ServerRefNotFoundError ->
+        # clean exit(1) (real cross-reference validation, not a mock).
+        bad = (
+            "my_agent:\n"
+            "  responses_api_agents:\n"
+            "    a:\n"
+            "      entrypoint: app.py\n"
+            "      resources_server:\n        type: resources_servers\n        name: does_not_exist\n"
+            "      model_server:\n        type: responses_api_models\n        name: policy_model\n"
+        )
+        with raises(SystemExit) as exc_info:
+            self._validate_config(monkeypatch, tmp_path, bad)
+        assert exc_info.value.code == 1
+
+    def test_config_error_becomes_clean_exit(self, monkeypatch: MonkeyPatch) -> None:
+        # Fast unit check of the decorator path: any ConfigError -> exit(1), no traceback.
         def _raise(**kwargs):
             raise NoServerInstancesError("nothing configured to run")