# nvidia-nemo/gym architecture

> Architecture diagram of the GitHub repository nvidia-nemo/gym, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia-nemo/gym
- Repository: https://github.com/nvidia-nemo/gym

## Overview

NeMo Gym is a platform for evaluating and improving models and agents through stateful, verifiable task environments. The main workflow is to launch an evaluation, pair an agent harness and model with task data and an environment, execute rollouts (optionally in sandboxes and at scale), then score and inspect results. Separate capabilities include environment discovery and authoring, training integrations, rollout verification and comparison, observability, and export. The README establishes these product areas; sampled source excerpts are partial, so uncertain internal call wiring is not shown.

Main entry points: [`nemo_gym/orchestration/api.py`](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/orchestration/api.py) (Run orchestration), [`nemo_gym/rollout_collection.py`](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/rollout_collection.py) (Rollout records), [`responses_api_agents`](https://github.com/nvidia-nemo/gym/tree/main/responses_api_agents) (Agent harnesses), [`nemo_gym/cli/main.py`](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/cli/main.py) (Gym CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Run orchestration"]
  node_cli["Gym CLI<br/>[main.py]"]
  node_orchestrator["Run orchestration<br/>[api.py]"]
  node_jobs["Job execution<br/>[jobs.py]"]
  node_datasets["Dataset loading"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Agent harnesses"]
  node_model["Model server<br/>[app.py]"]
  node_sandbox["Sandbox providers"]
end

subgraph group_envs["Environment hub"]
  node_envserver["Environment server"]
  node_resources["Resource servers"]
  node_envcatalog["Environment catalog"]
  node_verifier["Task verifier"]
end

subgraph group_results["Evaluation results"]
  node_rollouts["Rollout records"]
  node_health["Rollout health<br/>[rollout_health.py]"]
  node_reverify["Reward reverification"]
  node_comparison["Run comparison<br/>[runner.py]"]
  node_export["Result exporters<br/>[base.py]"]
end

subgraph group_platform["Platform services"]
  node_telemetry["Telemetry<br/>[setup.py]"]
  node_registry["Agent and model registries<br/>[agent_registry.py]"]
end

node_user(("Evaluator"))
node_externalmodel(("Hosted inference"))
node_training(("Training framework"))

node_user -->|"starts run"| node_cli
node_cli -->|"submits run"| node_orchestrator
node_orchestrator -->|"dispatches jobs"| node_jobs
node_orchestrator -->|"loads tasks"| node_datasets
node_orchestrator -->|"dispatches rollouts"| node_agent
node_agent -->|"requests inference"| node_model
node_model -.->|"forwards inference"| node_externalmodel
node_agent -->|"interacts with"| node_envserver
node_envserver -->|"serves resources"| node_resources
node_resources -->|"scores task"| node_verifier
node_agent -.->|"executes in"| node_sandbox
node_envcatalog -->|"configures tasks"| node_envserver
node_orchestrator -->|"collects results"| node_rollouts
node_rollouts -->|"checks rollouts"| node_health
node_rollouts -->|"recomputes rewards"| node_reverify
node_rollouts -->|"compares runs"| node_comparison
node_rollouts -->|"exports results"| node_export
node_orchestrator -.->|"emits telemetry"| node_telemetry
node_cli -->|"resolves components"| node_registry
node_rollouts -.->|"supplies training data"| node_training

click node_cli "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/cli/main.py"
click node_orchestrator "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/orchestration/api.py"
click node_jobs "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/orchestration/jobs.py"
click node_datasets "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/dataset_orchestrator.py"
click node_agent "https://github.com/nvidia-nemo/gym/tree/main/responses_api_agents"
click node_model "https://github.com/nvidia-nemo/gym/blob/main/responses_api_models/vllm_model/app.py"
click node_sandbox "https://github.com/nvidia-nemo/gym/tree/main/nemo_gym/sandbox/providers"
click node_envserver "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/base_environment_server.py"
click node_resources "https://github.com/nvidia-nemo/gym/tree/main/resources_servers"
click node_envcatalog "https://github.com/nvidia-nemo/gym/tree/main/environments"
click node_verifier "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/environment/_verifier_runner.py"
click node_rollouts "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/rollout_collection.py"
click node_health "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/rollout_health.py"
click node_reverify "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/rollout_reverification.py"
click node_comparison "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/comparison/runner.py"
click node_export "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/exporters/base.py"
click node_telemetry "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/telemetry/setup.py"
click node_registry "https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/agent_registry.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_orchestrator,node_jobs,node_datasets toneBlue
class node_agent,node_model,node_sandbox toneAmber
class node_envserver,node_resources,node_envcatalog,node_verifier toneMint
class node_rollouts,node_health,node_reverify,node_comparison,node_export toneRose
class node_telemetry,node_registry,node_user,node_externalmodel,node_training toneIndigo
```

## Components

### Run orchestration

- [Gym CLI](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/cli/main.py): `nemo_gym/cli/main.py`
- [Run orchestration](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/orchestration/api.py): `nemo_gym/orchestration/api.py`
- [Job execution](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/orchestration/jobs.py): `nemo_gym/orchestration/jobs.py`
- [Dataset loading](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/dataset_orchestrator.py): `nemo_gym/dataset_orchestrator.py`

### Agent runtime

- [Agent harnesses](https://github.com/nvidia-nemo/gym/tree/main/responses_api_agents): `responses_api_agents`
- [Model server](https://github.com/nvidia-nemo/gym/blob/main/responses_api_models/vllm_model/app.py): `responses_api_models/vllm_model/app.py`
- [Sandbox providers](https://github.com/nvidia-nemo/gym/tree/main/nemo_gym/sandbox/providers): `nemo_gym/sandbox/providers`

### Environment hub

- [Environment server](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/base_environment_server.py): `nemo_gym/base_environment_server.py`
- [Resource servers](https://github.com/nvidia-nemo/gym/tree/main/resources_servers): `resources_servers`
- [Environment catalog](https://github.com/nvidia-nemo/gym/tree/main/environments): `environments`
- [Task verifier](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/environment/_verifier_runner.py): `nemo_gym/environment/_verifier_runner.py`

### Evaluation results

- [Rollout records](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/rollout_collection.py): `nemo_gym/rollout_collection.py`
- [Rollout health](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/rollout_health.py): `nemo_gym/rollout_health.py`
- [Reward reverification](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/rollout_reverification.py): `nemo_gym/rollout_reverification.py`
- [Run comparison](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/comparison/runner.py): `nemo_gym/comparison/runner.py`
- [Result exporters](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/exporters/base.py): `nemo_gym/exporters/base.py`

### Platform services

- [Telemetry](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/telemetry/setup.py): `nemo_gym/telemetry/setup.py`
- [Agent and model registries](https://github.com/nvidia-nemo/gym/blob/main/nemo_gym/agent_registry.py): `nemo_gym/agent_registry.py`

### Other components

- **Evaluator**
- **Hosted inference**
- **Training framework**

## Connections

- Evaluator → Gym CLI: starts run
- Gym CLI → Run orchestration: submits run
- Run orchestration → Job execution: dispatches jobs
- Run orchestration → Dataset loading: loads tasks
- Run orchestration → Agent harnesses: dispatches rollouts
- Agent harnesses → Model server: requests inference
- Model server → Hosted inference: forwards inference
- Agent harnesses → Environment server: interacts with
- Environment server → Resource servers: serves resources
- Resource servers → Task verifier: scores task
- Agent harnesses → Sandbox providers: executes in
- Environment catalog → Environment server: configures tasks
- Run orchestration → Rollout records: collects results
- Rollout records → Rollout health: checks rollouts
- Rollout records → Reward reverification: recomputes rewards
- Rollout records → Run comparison: compares runs
- Rollout records → Result exporters: exports results
- Run orchestration → Telemetry: emits telemetry
- Gym CLI → Agent and model registries: resolves components
- Rollout records → Training framework: supplies training data