Skip to content

Reorganize nemo_gym into layered packages with per-package reviewer groups #5166

Open

Description

@ananthsub

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.py rewrites 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

Follow-ups

Metadata

Metadata

Assignees

Labels

Rolloutarea:coreShared APIs, servers, telemetry, health, and registriestrackingTracks a coordinated body of work across multiple issues or pull requests.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions