nemo_gym.cli.env
nemo_gym.cli.env
Module Contents
Classes
Functions
Data
RAY_ENABLE_AUTO_CONNECT_ENV_VAR_NAME
_DEFAULT_MODEL_ENDPOINT_READINESS_TIMEOUT_SEC
_DEFAULT_SERVER_SPINUP_TIMEOUT_SEC
_ENDPOINT_STARTING_STATUS_CODES
_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: RuntimeError
Gym servers did not become ready within server_spinup_timeout_seconds.
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.
Bases: NamedTuple
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.
Yield each server instance in the config that has an entrypoint to launch.
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 other than a gateway status 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. The exception is 502, 503 and 504, which a proxy or load
balancer returns while the server behind it is still starting; those are waited on like a
refused connection. 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.
The probe connects directly, ignoring HTTP_PROXY and the like, because model requests go
through Gym’s aiohttp client, which ignores them too. Through a proxy, an endpoint the proxy
cannot reach would come back as 502 or 504 and be waited on until the timeout.
Names of the configured servers that declare ray_enabled = True, so this run must start or join Ray.
A declaration that can’t be read from the entrypoint’s source, such as one inherited from another module,
doesn’t count. Such a server fails at startup with an error asking it to declare ray_enabled = True itself.
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.
The middle line records when venv setup finished.
The server uses it to separate venv setup from interpreter start and import time in its startup stages (see nemo_gym.telemetry.startup).
It reads the clock with the venv’s own interpreter because date +%s%N does not work on macOS.
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.
How a startup that raised error ended, as the startup telemetry reports it.
Wait for every endpoint to answer. Returns the ones that never did.
Unresolvable names are reported once and not waited on. Refused connections and gateway statuses 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.