build(deps): make Ray an optional dependency by ananthsub · Pull Request #4350 · NVIDIA-NeMo/Gym

ananthsub · 2026-10-09T20:54:43Z

Closes #4316.

What changed

ray[default] and its jinja2 pin move out of nemo-gym's core dependencies and live only in the ray extra (also part of all). A plain pip install nemo-gym no longer installs Ray.

Packaging: pyproject.toml and uv.lock. The lockfile change is metadata only; Ray and jinja2 stay locked through the extra, and no package versions move.
CI:
- scripts/ci/core_unit_tests.sh, plus the unit-test and full-test-suite syncs, add --extra ray, so Ray code paths stay tested and stay in the coverage gate.
- The wheel smoke test still installs the plain wheel, which now also covers the path without Ray.
- Server-test setup stays without the extra, because each Ray server's own venv requests it.
Docker: the image builds add --extra ray. The ray_dist.jar removal for the CVE is unchanged.
Tests: two tests skip when Ray isn't installed:
- tests/unit_tests/test_ray_serve_gateway.py, because the gateway imports Ray Serve at module level;
- the Super 3.5 launcher's prebuilt-environment check, because its generated dependency check imports Ray, which the evaluation image provides.
Docs: the installation and development-setup pages explain when to add the ray extra, and the FAQ no longer says Ray is a core dependency.

Why

This is the last step of #3669. Earlier changes made Gym run without Ray (#4300), had Ray servers request the extra (#4301), and made servers run without Ray unless they declare ray_enabled = True (#4307). The only remaining reason every install got Ray was nemo-gym's own core dependency.

Validation

Package metadata: uv build --wheel gives Requires-Dist: ray[default]>=2.58.0; extra == "ray" and Requires-Dist: jinja2>=3.1; extra == "ray", with no unconditional Ray requirement.
Without the extra: uv sync --locked --extra dev gives an environment where neither ray nor jinja2 is importable, and gym --version reports "ray": "not installed".
Full tests/unit_tests/ run, -m "not sandbox" as in the core CI job. I built the core CI job's environment (dev, telemetry, mlflow, wandb) twice:
- With --extra ray, everything passes.
- Without it, only the Ray-specific tests above skip. One timing-sensitive OpenSandbox cleanup test failed once under parallel load, and passed three times out of three on its own.
fern check passes.
pre-commit run scoped to the changed files.

Rollout evidence

N/A. This changes which packages a default install includes. It doesn't change prompts, model requests, trajectories, verification or rewards. #4300 smoke-tested gym env start with Ray uninstalled.

Compatibility

This is a breaking packaging change and needs a release note (#4317):

Ray-backed servers after a plain install: anyone running a server that declares ray_enabled = True (such as local_vllm_model, genrm_model or the SWE agents) needs pip install "nemo-gym[ray]", or uv sync --extra ray, where gym runs. Without it, gym env start stops before launching anything and says so.
Built-in Ray servers' own venvs: they keep getting Ray through their manifests, pinned to the version where gym runs.
NeMo RL: brings its own Ray, so nothing changes there.
External servers that use Ray: should request nemo-gym[ray] in their manifests.

copy-pr-bot · 2026-10-09T20:54:47Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

github-actions · 2026-10-10T00:55:53Z

🌿 Preview your docs: https://nvidia-preview-pr-4350-7c54b11affa0.docs.buildwithfern.com/nemo/gym

copy-pr-bot · 2026-10-12T13:49:57Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

ananthsub · 2026-10-12T14:08:28Z

/ok to test 9d5360e

ananthsub · 2026-10-13T23:36:23Z

/ok to test 4b25988

…dules (NVIDIA-NeMo#4581) ## What changed `responses_api_agents/stirrup_agent/__init__.py` now loads the agent module (`app.py`) only when one of the agent classes (`StirrupAgentWrapper`, `StirrupAgentWrapperConfig`, `StirrupRunRequest`) is accessed. Before, it imported `app.py` eagerly, so importing any stirrup_agent helper module loaded the whole agent. `TaskStrategy` is still imported directly, since it's lightweight. ## Why gdpval doesn't use Ray, but it imports two stirrup_agent helper modules: - `file_reader`, in `app.py`, to read deliverables during `verify`; - `task_distribution`, in `multistage_elo.py`. Because the package `__init__.py` imported the agent, and the agent imports Ray at module level, those imports needed Ray. Every server venv used to have Ray, so this went unnoticed. With NVIDIA-NeMo#4350, which makes Ray an optional dependency, gdpval's venv no longer has Ray. gdpval's tests then fail with `No module named 'ray'`, and so would `verify` for any task with a deliverables directory. This unblocks NVIDIA-NeMo#4350. Nothing in the repository imports the agent classes through the package; callers import submodules directly. Accessing `responses_api_agents.stirrup_agent.StirrupAgentWrapper` still works. ## Validation All of the following ran on NVIDIA-NeMo#4350's head with this change applied: - **gdpval's tests, without Ray:** in a venv built from `resources_servers/gdpval/requirements.txt`, the `pytest tests` run passes. With the previous `__init__.py` in the same venv, the gdpval failures from NVIDIA-NeMo#4350's CI reproduce. - **stirrup_agent's tests, with Ray:** in a venv built from `responses_api_agents/stirrup_agent/requirements.txt` and its `overrides.txt`, the `pytest tests` run passes. - **Imports in an environment without Ray:** - `responses_api_agents.stirrup_agent.file_reader` and `responses_api_agents.stirrup_agent.task_distribution` import cleanly, where they previously failed; - with Ray installed, `from responses_api_agents.stirrup_agent import StirrupAgentWrapper, StirrupRunRequest, TaskStrategy` still works. - `pre-commit run` on the changed file. ## Rollout evidence N/A. This only changes when the agent module is imported. The agent's behavior, prompts, trajectories, verification and rewards are unchanged. ## Compatibility None. Package-level access to the agent classes behaves as before. The agent module now loads on first access instead of at package import. Signed-off-by: Ananth Subramaniam <ansubramania@nvidia.com>

Move `ray[default]` and its `jinja2` pin out of nemo-gym's core dependencies into the `ray` extra, so a plain `pip install nemo-gym` no longer installs Ray. Gym already runs without Ray, and the servers that declare `ray_enabled = True` request the extra in their own manifests. - CI: the core unit-test, unit-test and full-test-suite syncs add `--extra ray`, so Ray code paths stay tested. The wheel smoke test and server-test setup stay without it. - Docker: the image builds add `--extra ray`. - Tests: the Ray Serve gateway test and the Super 3.5 launcher's prebuilt-environment check skip when Ray isn't installed. - Docs: installation, development setup and FAQ describe the extra. Closes #4316. Signed-off-by: Ananth Subramaniam <ansubramania@nvidia.com>

ananthsub · 2026-10-14T14:54:15Z

/ok to test 7c54b11

github-actions · 2026-10-14T15:15:38Z

🔄 Merge queue validation started! You can track the progress here: https://github.com/NVIDIA-NeMo/Gym/actions/runs/38587741688

… deliverables dir The GDPVal run recipe could not work as written on main: - The benchmark config defaults persist_deliverables_dir to the relative output/gdpval/deliverables, which the Stirrup agent rejects at startup. - With an absolute PERSIST_DELIVERABLES_DIR, every task fails with "GDPval requires the Apptainer sandbox" because GDPVAL_CONTAINER_PATH is unset; the run then stops with "None of the N dispatched rollouts produced a result" and no aggregate metrics. - Since Ray became an optional extra (#4350), a `uv sync --extra dev` install stops before the run because the Stirrup agent needs Ray. Add a "Prerequisites for every run" section to the benchmark README and the config's run recipe. Correct the Stirrup README, which still called Apptainer optional, said the agent falls back to a local sandbox, and installed Gym without Ray, and fix the aggregate-metrics filename (<stem>_aggregate_metrics.json) in both READMEs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: qiaochuz <qiaochuz@nvidia.com>

ananthsub marked this pull request as ready for review October 10, 2026 00:53

ananthsub requested a review from a team as a code owner October 10, 2026 00:53

nemo-automation-bot Bot requested review from a team and anwithk October 10, 2026 00:53

copy-pr-bot Bot temporarily deployed to public October 10, 2026 00:53 Inactive

copy-pr-bot Bot temporarily deployed to public October 10, 2026 00:56 Inactive

hemildesai approved these changes Oct 10, 2026

View reviewed changes

github-actions Bot added the sla:review-overdue Review response is over the one-business-day SLA label Oct 12, 2026

github-actions Bot mentioned this pull request Oct 12, 2026

[Tracker] Pull request handoff SLA #3402

Open

ananthsub force-pushed the ananthsub/ray-optional-dependency branch from cfb3737 to 9d5360e Compare October 12, 2026 13:49

copy-pr-bot Bot temporarily deployed to public October 12, 2026 14:09 Inactive

nemo-automation-bot Bot requested a review from a team October 12, 2026 14:09

copy-pr-bot Bot temporarily deployed to public October 12, 2026 14:11 Inactive

ananthsub force-pushed the ananthsub/ray-optional-dependency branch from 9d5360e to 4b25988 Compare October 13, 2026 23:36

copy-pr-bot Bot temporarily deployed to public October 13, 2026 23:37 Inactive

copy-pr-bot Bot temporarily deployed to public October 13, 2026 23:39 Inactive

chtruong814 approved these changes Oct 13, 2026

View reviewed changes

copy-pr-bot Bot temporarily deployed to public October 13, 2026 23:39 Inactive

ananthsub enabled auto-merge October 13, 2026 23:39

This was referenced Oct 13, 2026

Release notes and migration guide for optional Ray #4317

Open

fix(stirrup_agent): don't load the agent when importing its helper modules #4581

Merged

ananthsub force-pushed the ananthsub/ray-optional-dependency branch from 4b25988 to 7c54b11 Compare October 14, 2026 14:54

copy-pr-bot Bot temporarily deployed to public October 14, 2026 14:58 Inactive

copy-pr-bot Bot temporarily deployed to public October 14, 2026 15:00 Inactive

copy-pr-bot Bot temporarily deployed to public October 14, 2026 15:01 Inactive

ananthsub added this pull request to the merge queue Oct 14, 2026

Merged via the queue into main with commit 40d7484 Oct 14, 2026
49 of 54 checks passed

ananthsub deleted the ananthsub/ray-optional-dependency branch October 14, 2026 15:34

qiaochuz-nv mentioned this pull request Oct 15, 2026

docs(gdpval): document the Ray extra, Apptainer sandbox, and absolute deliverables dir #4655

Closed

Navigation Menu

Repository navigation

build(deps): make Ray an optional dependency - #4350

build(deps): make Ray an optional dependency#4350
ananthsub merged 1 commit into
mainfrom
ananthsub/ray-optional-dependency

ananthsub commented Oct 9, 2026

Uh oh!

copy-pr-bot Bot commented Oct 9, 2026

Uh oh!

github-actions Bot commented Oct 10, 2026 •

edited

Loading

Uh oh!

copy-pr-bot Bot commented Oct 12, 2026

Uh oh!

ananthsub commented Oct 12, 2026

Uh oh!

ananthsub commented Oct 13, 2026

Uh oh!

ananthsub commented Oct 14, 2026

Uh oh!

github-actions Bot commented Oct 14, 2026

Uh oh!

Uh oh!

This branch was previously deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

ananthsub commented Oct 9, 2026

What changed

Why

Validation

Rollout evidence

Compatibility

Uh oh!

copy-pr-bot Bot commented Oct 9, 2026

Uh oh!

github-actions Bot commented Oct 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

copy-pr-bot Bot commented Oct 12, 2026

Uh oh!

ananthsub commented Oct 12, 2026

Uh oh!

ananthsub commented Oct 13, 2026

Uh oh!

ananthsub commented Oct 14, 2026

Uh oh!

github-actions Bot commented Oct 14, 2026

Uh oh!

Uh oh!

This branch was previously deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions Bot commented Oct 10, 2026 •

edited

Loading