Repository navigation
Description
Problem
nemo_gym/ holds 64 top-level modules and 19 packages side by side, so a file's name rarely says which part of the system it belongs to. Several large files mix unrelated code: server_utils.py alone holds the HTTP client, the server client, the server base classes, request handling, Ray setup, and the head server. Imports run in every direction, and 51 of the top-level modules and packages sit in a single import cycle, so a change almost anywhere can affect almost anything else.
That layout also makes review routing coarse. CODEOWNERS can only send most library changes to one broad group, because one flat file often spans several areas.
Plan
Group the library into packages by responsibility, order them so each package depends only on packages below it, and give each package one reviewer group. From the bottom up: config/, utils/, core/, telemetry/, client/, sandbox/, trajectory/, verification/, metrics/, artifacts/, server_runtime/, models/, agents/, data/, rollouts/, orchestration/, eval/, environment/, cli/. This is the order the import-linter contract checks: artifacts/ sits above trajectory/ because its exporters import the ATIF export, and testing/ is dissolved into the packages its helpers test (#5233). Large files are split so each part lands in the package it belongs to. responses_api_agents/, responses_api_models/, resources_servers/, and environment_servers/ do not change.
An import-linter contract in CI checks the order, with today's violations listed as exceptions that may only shrink.
Compatibility
Every current import path keeps working while the moves land and for two minor releases after a module moves.
- An old module path gives the same module object as its new path, so classes, registries, and patches through the old path keep working.
- Each use of an old path warns once, naming the new path, the release that moved it, the release that removes it, and the running version.
- A unit test fails once the package version reaches a removal release while the old path still exists.
- Config keys, CLI commands, server configs, output files, and the request and response formats between servers do not change.
scripts/migrate_imports.pyrewrites old paths in open branches and downstream projects. A PR to NeMo RL will switch it to the new paths.
The one break: a patch of a name that a split file no longer looks up itself stops taking effect, such as monkeypatch.setattr(nemo_gym.server_utils, "request", fake) once ServerClient and request live in client/. Each split PR lists those names.
History: every move is a git mv. The repository squash-merges, so a whole-module move shows as a rename, but a split file starts its own history at its new path. git blame -C -C <new file> follows the moved lines back to the old file.
Each package PR also gives its package a lazy public API in __init__.py; server code imports from nemo_gym.<package>, and code inside nemo_gym/ imports submodules directly. Each PR is a single commit.
Stack
- feat(compat): keep old import paths working across the package reorganization #5167 Keep old import paths working across the reorganization
- ci: check package layering with import-linter #5168 Check package layering with import-linter
- refactor: remove path and name couplings before the reorganization #5169 Remove path and name couplings before the reorganization
- refactor(config): move config modules into nemo_gym/config #5189 Move config modules into
nemo_gym/config/ - refactor(utils): move general helpers into nemo_gym/utils #5195 Move general helpers into
nemo_gym/utils/ - refactor(core): move shared definitions into nemo_gym/core #5203 Move shared definitions into
nemo_gym/core/ - refactor(client): move the HTTP and server clients into nemo_gym/client #5206 Move the HTTP and server clients into
nemo_gym/client/ - refactor(trajectory): move the trajectory modules into nemo_gym/trajectory #5209 Move the trajectory data model into
nemo_gym/trajectory/ - refactor(verification): move the verification modules into nemo_gym/verification #5210 Move the verification helpers into
nemo_gym/verification/ - refactor(metrics): move the metrics modules into nemo_gym/metrics #5211 Move the rollout metrics into
nemo_gym/metrics/ - refactor(artifacts): move run artifacts and exporters into nemo_gym/artifacts #5212 Move run artifacts and exporters into
nemo_gym/artifacts/ - refactor(server_runtime): move the server runtime modules into nemo_gym/server_runtime #5214 Move the server runtime modules into
nemo_gym/server_runtime/ - refactor(server_runtime): split server_utils into the server runtime package #5215 Split
server_utilsinto the server runtime package - refactor(models): move the model clients, converters and token capture into nemo_gym/models #5224 Move the model clients, converters, and token capture into
nemo_gym/models/ - refactor(models): split model call capture out of the model server base and move the OpenAI client into client/ #5225 Split model call capture out of the model server base and move the OpenAI client into
nemo_gym/client/ - refactor(agents): move the agent server modules into nemo_gym/agents #5228 Move the agent server modules into
nemo_gym/agents/ - refactor(data): move the task data modules into nemo_gym/data #5229 Move the task data modules into
nemo_gym/data/ - refactor(data): split the Harbor run commands out of the task CLI module #5230 Split the Harbor run commands out of the task CLI module
- refactor(rollouts): move rollout collection and health into nemo_gym/rollouts #5231 Move rollout collection and health into
nemo_gym/rollouts/ - refactor(rollouts): split rollout performance and trajectory building out of the collector #5232 Split rollout performance and trajectory building out of the collector
- refactor: move the session conformance helpers next to what they test #5233 Move the session conformance helpers next to what they test
- refactor(orchestration): move server setup and the sidecar into nemo_gym/orchestration #5234 Move server setup and the sidecar into
nemo_gym/orchestration/ - refactor(orchestration): split the server supervisor out of cli/env.py #5235 Split the server supervisor out of
cli/env.py - refactor(eval): move the evaluation modules into nemo_gym/eval #5244 Move the evaluation modules into
nemo_gym/eval/ - refactor(environment): move the registries into nemo_gym/environment #5298 Move the registries into
nemo_gym/environment/ - refactor(cli): replace the cli_setup_command shim with a moved-path entry #5300 Replace the
cli_setup_commandshim with a moved-path entry - docs: describe the repository layout and the nemo_gym packages #5385 Document the package layout
- Route CODEOWNERS to the per-package reviewer groups
- Switch NeMo RL to the new paths
- Remove the old paths after the deprecation window
Follow-ups
- refactor(models): give token capture its own lazy public API #5525 Give token capture its own public API
- chore: remove a stray patch backup from nemo_gym/core #5527 Remove a stray patch backup from
nemo_gym/core - fix(core): warn once for renamed names served by lazy_exports #5530 Warn once for renamed names served by
lazy_exports - refactor(core): move the failure modules from #5072 into their packages #5536 Move the failure modules from feat(eval): report causal failures across service boundaries #5072 into
core/andutils/ - refactor(core): split the episode modules into types, context and failure records #5564 Split the
coreepisode modules into types, context and failure records - refactor(server_runtime): rename RunHelper to ServerSupervisor #5526 Rename
RunHelpertoServerSupervisor - refactor(models): rename ResponsesConverter to ChatCompletionsConverter #5528 Rename
ResponsesConvertertoChatCompletionsConverter - refactor(models): retire VLLMConverter aliases #5531 Retire the
VLLMConverteraliases - refactor(models): rename token ID capture to token capture #5533 Rename token ID capture to token capture
- refactor(server_runtime): rename the head server to the registry server #5553 Rename the head server to the registry server
- refactor(verification): move nemo_gym.verifiers into verification/ #5561 Move
nemo_gym/verifiers/intoverification/
Activity
refactor(core): split the episode modules into types, context and fai…
test: mirror nemo_gym packages in the unit test tree
test: mirror nemo_gym packages in the unit test tree
test: mirror nemo_gym packages in the unit test tree
test: mirror nemo_gym packages in the unit test tree
test: mirror nemo_gym packages in the unit test tree
test: mirror nemo_gym packages in the unit test tree
test: mirror nemo_gym packages in the unit test tree (#5589)