nemo_gym.cli.env
nemo_gym.cli.env
Module Contents
Classes
Functions
Data
_DEFAULT_MODEL_ENDPOINT_READINESS_TIMEOUT_SEC
_DEFAULT_SERVER_SPINUP_TIMEOUT_SEC
_GRACEFUL_SHUTDOWN_TIMEOUT_SEC
API
Bases: BaseNeMoGymCLIConfig
Bases: BaseNeMoGymCLIConfig
Start NeMo Gym servers for agents, models, and resources.
Examples:
Probe every server not yet ready.
With a deadline from monotonic(), each probe is capped at the time left before it.
Servers still unprobed once it passes are reported as timeout without a request.
Start the head server and every configured server, and wait until all of them are ready.
Any failure or interrupt before readiness shuts down everything started so far, then re-raises.
Callers reach their own shutdown() only after this returns.
The spawned servers have no process group or atexit handler, so nothing else would stop them.
Wait for every dry-run process to finish, and fail if any of them did.
A dry run builds each server’s venv and exits, so unlike poll() a finished process is the expected outcome here and only the exit code separates success from failure. The code has to be checked: uv creates the venv before installing into it, so a failed install still leaves an interpreter and an activate script behind. That venv then satisfies skip_venv_if_present on the next run, and the first symptom is an ImportError from a server long after the install that caused it.
Block until every model endpoint named in the config answers, then return.
Reads the bound from model_endpoint_readiness_timeout_seconds, where 0 skips the check
entirely. Raises ConfigError naming the endpoints that never answered and the config key
each came from. It raises rather than exits because RunHelper is imported and driven as a
library, so the caller decides what an unreachable endpoint means; the CLI entrypoints turn
it into an exit.
start() shuts down the servers it already spawned before the error reaches the caller.
Mark the head ready only after every managed server and model endpoint is reachable.
Bases: BaseNeMoGymCLIConfig
Run tests for all server modules in the project.
Examples:
Bases: RunConfig
Test a specific server module by running its pytest suite and optionally validating example data.
Examples:
Absolute server dir resolved against the cwd, then the Gym install root.
Use this for filesystem access (reading data, running the suite); use dir_path (the
relative entrypoint) for display and example commands shown to the user.
The upstream model endpoints named in the resolved config, as (config key, url) pairs.
wait_for_spinup only polls Gym’s own servers, and the Gym-side model server answers as soon
as it starts whether or not anything is behind it, so these are the URLs nothing checks.
base_url is typed Union[str, List[str]] on vllm_model and the local vLLM servers, where the
list form spreads load across replicas. The local ones default to an empty list and are filled
in after Gym launches vLLM, so an empty list means “not yet” rather than “misconfigured” and is
skipped, as is an unset value.
The key travels with the url because the endpoint that fails may be a judge or user model, and
a message naming policy_base_url would then be wrong.
Parse the already-translated local command flags without resolving Gym runtime config.
What to GET to find out whether base_url is being served.
GET /v1/models is part of the OpenAI API, so most endpoints behind a /v1 base URL answer it,
but nothing here depends on that: any HTTP response counts as answering, so an endpoint without
it replies 404 and still passes. URLs that do not end in /v1 are probed at their root.
Render one entry from the unified environment catalog.
Whether a requests connection error was a name that does not resolve.
requests reports this as a ConnectionError like any other, with the resolver failure nested
inside, so the cause chain has to be walked rather than the class inspected.
How long to wait for model endpoints, from config. 0 or a negative value skips the check.
An unset key falls back to the same default the config parser applies. A value that is not a
number is a configuration mistake, so it is reported as one rather than surfacing as a
ValueError traceback from float().
Whether anything answers at base_url, and if not, whether waiting could help.
Answering is the bar, not healthy: a 401 or 404 means something is there, and requiring a 200
would reject endpoints that need auth. A completed TLS handshake counts too, even against a
certificate this process does not trust, which is why SSLError is checked before
ConnectionError it inherits from.
Resolve a relative server dir (e.g. resources_servers/<name>) to an absolute path.
Searches NEMO_GYM_EXTRA_ROOTS, the current working directory (a user’s local server), then the Gym
install root (PARENT_DIR) where built-in servers live in both editable and wheel installs. A
directory counts as a server only if it ships an install marker for one of our two venv setups. This
lets gym env test find and run built-in (and plugin) servers from any cwd, not just a repo checkout.
Deterministically select this shard’s subset of modules.
Round-robin (stride) over a sorted list spreads heavy modules across shards more evenly than contiguous chunks, which balances wall-time when the suite is parallelized across CI runners.
Shell command that sets up a server’s venv and starts its entrypoint with that venv’s own interpreter.
The interpreter is named explicitly instead of relying on the bare python that source bin/activate
puts on PATH: a venv copied or moved after creation still names its original prefix in bin/activate,
so activating it would silently run a different interpreter than uv_venv_dir selected.
How long to wait for Gym servers to become ready, from config. 0 or a negative value waits forever.
An unset or null key falls back to the same default the config parser applies.
Environment interpolation yields a string, so numeric strings are accepted.
Anything else is reported as a ConfigError rather than a TypeError traceback mid-startup.
Install every selected server’s venv the way the suite would, then exit non-zero if any failed.
The container build runs this to seed its uv cache, so scripts/ci/server_tests.sh can create the same
per-server venvs offline. Every server is attempted before failing, so one run reports every gap.
Install one server’s venv exactly as _test_single does, without running its tests.
Wait for every endpoint to answer. Returns the ones that never did.
Unresolvable names are reported once and not waited on. Refused connections are waited on, because an inference server can take minutes to load weights and someone who starts thirty seconds early should not have to start over.
Display the resolved Hydra configuration for debugging purposes.
Examples:
Create a manifest-backed environment or benchmark skeleton.
Initialize a new resources server with template files and directory structure.
Examples:
List or inspect the manifest and legacy environment/benchmark catalog.
List packages installed in a server’s virtual environment.
Pre-warm per-server venvs without starting any servers.
Accepts the same config format as ‘gym env start’. For each server in the config, creates its isolated venv and installs dependencies serially — similar to how RL’s prefetch_venvs.py installs actor venvs at container build time.
No Ray is initialised and no server processes are started. Intended for use in Dockerfile builds so venvs are ready at runtime with no network access needed.
Configuration Parameter:
config_paths (List[str]): Paths to YAML configuration files. Specify via Hydra: +config_paths="[file1.yaml,file2.yaml]"
Examples:
Run local publication checks and confirm a workload is cataloged.
Start NeMo Gym servers for agents, models, and resources.
This command reads configuration from YAML files specified via +config_paths and starts all configured servers.
The configuration files should define server instances with their entrypoints and settings.
Configuration Parameter:
config_paths (List[str]): Paths to YAML configuration files. Specify via Hydra: +config_paths="[file1.yaml,file2.yaml]"
Examples:
Print the selected server’s TaskData schema (see nemo_gym/task_data.py).
Exercise a manifest-backed workload’s verifier fixture without starting services.
Validate a manifest-backed workload or a legacy Gym config without starting services.