cp: fix(cli): report cleanly unresolved config interpolations; fix the env resolve docs example (2310) into r0.5.0

fern/versions/latest/pages/reference/cli-commands.mdx

@@ -401,6 +401,8 @@ gym env init --resources-server my_server
 
 Resolve the configs, flags, and overrides into a final merged config and print it. Useful for debugging configuration. Secrets are hidden.
 
+Unlike `gym env validate`, `resolve` substitutes no dummy model, so a model config's `policy_*` values must be supplied for its interpolations to resolve.
+
 | Option | Description |
 | --- | --- |
 | `--config PATH` | Config file to load. Repeatable. |
@@ -411,7 +413,10 @@ Resolve the configs, flags, and overrides into a final merged config and print i
 gym env resolve \
     --config resources_servers/example_single_tool_call/configs/example_single_tool_call.yaml \
     --config responses_api_models/openai_model/configs/openai_model.yaml \
-    ++responses_create_params.temperature=0.6
+    ++responses_create_params.temperature=0.6 \
+    ++policy_base_url=https://api.openai.com/v1 \
+    ++policy_api_key=sk-example \
+    ++policy_model_name=gpt-4o-mini
 ```
 
 ### `gym env validate`

nemo_gym/config_types.py

@@ -163,6 +163,10 @@ class ConfigMissingValuesError(ConfigError, ValueError):
     """One or more required config values are still unset (OmegaConf '???') after merging."""
 
 
+class ConfigInterpolationError(ConfigError, ValueError):
+    """An `${...}` interpolation references a key that is not present in the merged config."""
+
+
 class ServerRefNotFoundError(ConfigError, ValueError):
     """A server cross-reference points to an instance that is not defined in the merged config."""
 

nemo_gym/global_config.py

@@ -13,6 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 import logging
+import re
 import sys
 from argparse import ArgumentParser
 from collections import defaultdict
@@ -31,6 +32,7 @@
 import wandb
 import wandb.util
 from omegaconf import MISSING, DictConfig, ListConfig, OmegaConf, open_dict
+from omegaconf.errors import InterpolationResolutionError
 from openai import __version__ as openai_version
 from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError
 from ray import __version__ as ray_version
@@ -40,6 +42,7 @@
 from nemo_gym.config_types import (
     AlmostServerError,
     ConfigError,
+    ConfigInterpolationError,
     ConfigMissingValuesError,
     ConfigPathNotFoundError,
     InheritPathNotFoundError,
@@ -828,7 +831,24 @@ def set_global_config_dict(
     global_config_dict_parser_cls: Type[GlobalConfigDictParser] = GlobalConfigDictParser,
 ) -> None:
     global _GLOBAL_CONFIG_DICT
-    global_config_dict = global_config_dict_parser_cls().parse(global_config_dict_parser_config)
+    try:
+        global_config_dict = global_config_dict_parser_cls().parse(global_config_dict_parser_config)
+    except InterpolationResolutionError as e:
+        # Same class of user error as an unset '???' (see raise_on_missing_values), so report it the same
+        # way instead of letting omegaconf's traceback reach the top level. Covers both a missing `${key}`
+        # (InterpolationKeyError) and a failing resolver such as `${oc.env:VAR}`, which carries its own
+        # message and so is passed through as-is.
+        match = re.search(r"Interpolation key '([^']+)' not found", str(e))
+        if not match:
+            raise ConfigInterpolationError(str(e)) from e
+        key = match.group(1)
+        raise ConfigInterpolationError(
+            f"""Config value '{e.full_key}' references '{key}', which is not set after merging.
+
+Provide it via a CLI override, in env.yaml, or in a config you pass via config_paths.
+For example, on the command line:
+  ++{key}=<value>"""
+        ) from e
 
     _GLOBAL_CONFIG_DICT = global_config_dict