[ananthsub]

What changed and why

Token capture is a namespace of its own, the way a task format such as nemo_gym.data.tasks.harbor is, so it now has its own lazy public API. Code outside nemo_gym/ imports token capture names from nemo_gym.models.token_capture, not from nemo_gym.models or from a token capture module. Before this change, no package served the rollout finalizer, so the external agent harness guide had to import nemo_gym.models.token_capture.delivery directly. The package layout docs (#5385) ran into that.

• nemo_gym.models.token_capture replaces its eager imports and __all__ with a _PUBLIC_API built with lazy_exports, plus a TYPE_CHECKING block, as in the Harbor package. It serves every name its old __all__ listed, and the protocol and record names that nemo_gym.models served. It also adds finalize_rollout_token_capture, retire_rollout_token_capture, ConformanceError, ConformanceWarning, TerminalAttribution, and resolve_terminal.
  • It also exports RolloutRemovalPayload and RolloutRetiredError. TokenSource and CaptureLedger return the first from retire and delete, and a CaptureLedger raises the second for a retired rollout. Neither the old __all__ nor nemo_gym.models exported them, so a framework implementing those protocols had to import token capture's protocols module.
  • The finalizer in delivery.py imports only token capture modules and nemo_gym.core.episode, which depends on Pydantic alone, so nothing keeps it out of the public API. The package docstring no longer says it needs Gym's server stack.
• No server dependencies. Frameworks implement token capture's protocols, so every name either public API serves imports with only Pydantic and orjson from outside the standard library. Nothing loads Gym's server stack, an HTTP client, or the OpenAI SDK.
  • The external capture handlers (ExternalCaptureHandler, VLLMWorkerCaptureHandler, make_external_capture_handler, validate_framework_context_options) run inside the model server. Their module needs the OpenAI SDK through the chat completions converter. So nemo_gym.models, the model server's public API, serves them instead of token capture's.
• nemo_gym.models.token_capture.staging, the hand-off to training frameworks, keeps a public API of its own, now lazy too. Its docstring already describes it as a namespace separate from token capture's records. It also serves the three staging names that nemo_gym.models served and that its old __all__ did not list.
  • The terminal resolver (resolve_terminal, TerminalAttribution) is defined in token capture, so token capture's API serves it. A lazy API serves only its own package's modules. The old path nemo_gym.token_id_capture.staging, which NeMo RL imports resolve_terminal from, still resolves through a new moved-name entry and warns.
  • The same applies to canonicalize_tool_arguments, which the old nemo_gym.token_id_capture package imported without exporting it.
• nemo_gym.models no longer re-exports token capture's protocol and record names. No release shipped them: v0.7.0 has no nemo_gym.models package, and the moves ship in 0.8.0. So they need no moved-path entries.
• Importers. The vLLM model server, its tests, the Claude Code agent tests, and the external agent harness guide's code samples import from the new public APIs. Code inside nemo_gym/ and its tests imports from the modules that define each name, so the library modules and tests that imported from the token capture packages now import from those modules.

Tracking issue: #5166.

Compatibility

• from nemo_gym.models import <token capture protocol or record name> no longer works. That form never shipped in a release.
• Importing nemo_gym.models.token_capture or its staging package no longer imports their modules eagerly.
• Old nemo_gym.token_id_capture paths keep resolving with a deprecation warning. That includes nemo_gym.token_id_capture.staging.resolve_terminal, which NeMo RL imports, and nemo_gym.token_id_capture.canonicalize_tool_arguments.
• scripts/migrate_imports.py reads public APIs only from top-level packages, so it does not write the token capture or Harbor subpackage form. That predates this change.

Validation

• tests/unit_tests/test_public_api_facades.py now also covers the two new public APIs. It checks that each name is the object its module defines, that importing either package loads none of its modules, and that the TYPE_CHECKING imports match _PUBLIC_API. It also checks that code outside the library imports these names only from a public API, and that every name it imports resolves.
• The token capture dependency check in tests/unit_tests/models/test_token_capture.py loads every name both public APIs serve in a fresh interpreter. It fails if Ray, FastAPI, Starlette, uvicorn, aiohttp, requests, httpx, the OpenAI SDK, or torch was imported, so an external capture handler added back to token capture's API fails it. Before this change the check imported only the package, which now loads none of its modules.
• tests/unit_tests/test_moved_paths.py checks that every recorded old path and NeMo RL's imports still resolve.
• pytest tests/unit_tests, compared with upstream/main in the same environment, to check that the change adds no failures.
• pytest responses_api_models/vllm_model/tests responses_api_agents/claude_code_agent/tests, which run the vLLM model server and the Claude Code agent against the new imports.
• lint-imports, which checks that each package imports only packages below it.
• pre-commit run --files <changed files>.

Rollout evidence

N/A: this changes import paths only, with no change to agent, model server, or verifier behavior.

[copy-pr-bot]

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.