# nvidia-nemo/nemo-helix architecture

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

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

## Overview

NeMo Helix is a modular control plane for evaluating, improving, and hardening production agents. Users enter through the CLI, Python SDK/REST APIs, or NeMo Studio; the CLI supports setup and operations, while platform services and plugins provide agent execution, data generation, evaluation, optimization, and safety capabilities. Shared foundations include authentication, files, jobs, and inference. The README documents the product surfaces and capability breadth; sampled source confirms selected client, controller, and storage behavior, but not most runtime wiring, so unverified links are dashed.

Main entry points: [`plugins/nemo-evals/src/nemo_evals/taskset_runs/plan_storage.py`](https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-evals/src/nemo_evals/taskset_runs/plan_storage.py) (Evaluation workflows), [`packages/nhx_platform/src/nhx/platform/main.py`](https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nhx_platform/src/nhx/platform/main.py) (Platform services), [`packages/nemo_helix_plugin/src/nemo_helix_plugin/inference_gateway/client.py`](https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_plugin/src/nemo_helix_plugin/inference_gateway/client.py) (Inference gateway), [`packages/nemo_helix_plugin/src/nemo_helix_plugin/jobs/client.py`](https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_plugin/src/nemo_helix_plugin/jobs/client.py) (Jobs and orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_cli["NeMo CLI<br/>[app.py]"]
  node_sdk["Python and REST<br/>[client.py]"]
  node_studio["NeMo Studio"]
end

subgraph group_platform["Platform core"]
  node_platform["Platform services<br/>[main.py]"]
  node_plugin_framework["Plugin framework<br/>[controller.py]"]
end

subgraph group_agentops["Agent operations"]
  node_agent_runtime["Agent execution<br/>[controller.py]"]
  node_observability["Traces and insights<br/>[pipeline.py]"]
  node_safety["Safety and guardrails<br/>[engine.py]"]
end

subgraph group_improvement["Agent improvement"]
  node_evaluation["Evaluation workflows<br/>[plan_storage.py]"]
  node_scaled_evals["Scaled evaluations<br/>[controller.py]"]
  node_data_design["Data Designer<br/>[_engine_pass.py]"]
  node_optimization["Optimization<br/>[router.py]"]
  node_customization["Model fine-tuning<br/>[router.py]"]
  node_anonymizer["Data anonymization<br/>[_preview_worker.py]"]
end

subgraph group_foundations["Shared foundations"]
  node_inference["Inference gateway<br/>[client.py]"]
  node_auth["Authentication and policy<br/>[engine.py]"]
  node_files[("Files and artifacts<br/>[log_storage.py]")]
  node_jobs["Jobs and orchestration<br/>[client.py]"]
  node_intake[("Trace ingestion<br/>[storage.py]")]
end

node_user(("Helix user"))

node_user -->|"operates"| node_cli
node_user -->|"integrates through"| node_sdk
node_user -->|"uses"| node_studio
node_cli -.->|"manages services"| node_platform
node_sdk -.->|"calls APIs"| node_platform
node_studio -.->|"accesses capabilities"| node_platform
node_platform -.->|"hosts plugins"| node_plugin_framework
node_plugin_framework -->|"runs controller"| node_agent_runtime
node_agent_runtime -.->|"manages deployments"| node_jobs
node_agent_runtime -.->|"runs agent models"| node_inference
node_intake -.->|"supplies traces"| node_observability
node_observability -.->|"informs evaluations"| node_evaluation
node_evaluation -.->|"schedules runs"| node_jobs
node_evaluation -->|"stores plans"| node_files
node_scaled_evals -->|"reconciles jobs"| node_jobs
node_data_design -.->|"resolves providers"| node_inference
node_data_design -.->|"produces datasets"| node_files
node_optimization -.->|"compares candidates"| node_evaluation
node_customization -.->|"launches tuning"| node_jobs
node_safety -.->|"guards model calls"| node_inference
node_anonymizer -.->|"protects data"| node_files
node_sdk -.->|"carries identity"| node_auth
node_evaluation -.->|"scores candidates"| node_inference

click node_cli "https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_ext/src/nemo_helix_ext/cli/app.py"
click node_sdk "https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_plugin/src/nemo_helix_plugin/client/client.py"
click node_studio "https://github.com/nvidia-nemo/nemo-helix/tree/main/web/packages/studio"
click node_platform "https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nhx_platform/src/nhx/platform/main.py"
click node_plugin_framework "https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_plugin/src/nemo_helix_plugin/controller.py"
click node_agent_runtime "https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-agents/src/nemo_agents_plugin/runner/controller.py"
click node_observability "https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-compass/src/nemo_compass_plugin/analysis/pipeline.py"
click node_evaluation "https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-evals/src/nemo_evals/taskset_runs/plan_storage.py"
click node_scaled_evals "https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/_temporary-scaled-evals/src/nemo_scaled_evals_plugin/controller.py"
click node_data_design "https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-data-designer/src/nemo_data_designer_plugin/sdk/_engine_pass.py"
click node_optimization "https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-optimization/src/nemo_optimization/router.py"
click node_customization "https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-customizer/src/nemo_customizer/router.py"
click node_safety "https://github.com/nvidia-nemo/nemo-helix/blob/main/services/guardrails/src/nhx/guardrails/app/services/rails/engine.py"
click node_inference "https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_plugin/src/nemo_helix_plugin/inference_gateway/client.py"
click node_auth "https://github.com/nvidia-nemo/nemo-helix/blob/main/services/core/auth/src/nhx/core/auth/app/embedded_pdp/engine.py"
click node_files "https://github.com/nvidia-nemo/nemo-helix/blob/main/services/core/files/src/nhx/core/files/app/log_storage.py"
click node_jobs "https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_plugin/src/nemo_helix_plugin/jobs/client.py"
click node_intake "https://github.com/nvidia-nemo/nemo-helix/blob/main/services/intake/src/nhx/intake/spans/storage.py"
click node_anonymizer "https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-anonymizer/src/nemo_anonymizer_plugin/functions/_preview_worker.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_sdk,node_studio,node_user toneBlue
class node_platform,node_plugin_framework toneAmber
class node_agent_runtime,node_observability,node_safety toneMint
class node_evaluation,node_scaled_evals,node_data_design,node_optimization,node_customization,node_anonymizer toneRose
class node_inference,node_auth,node_files,node_jobs,node_intake toneIndigo
```

## Components

### User surfaces

- [NeMo CLI](https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_ext/src/nemo_helix_ext/cli/app.py): `packages/nemo_helix_ext/src/nemo_helix_ext/cli/app.py`
- [Python and REST](https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_plugin/src/nemo_helix_plugin/client/client.py): `packages/nemo_helix_plugin/src/nemo_helix_plugin/client/client.py`
- [NeMo Studio](https://github.com/nvidia-nemo/nemo-helix/tree/main/web/packages/studio): `web/packages/studio`

### Platform core

- [Platform services](https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nhx_platform/src/nhx/platform/main.py): `packages/nhx_platform/src/nhx/platform/main.py`
- [Plugin framework](https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_plugin/src/nemo_helix_plugin/controller.py): `packages/nemo_helix_plugin/src/nemo_helix_plugin/controller.py`

### Agent operations

- [Agent execution](https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-agents/src/nemo_agents_plugin/runner/controller.py): `plugins/nemo-agents/src/nemo_agents_plugin/runner/controller.py`
- [Traces and insights](https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-compass/src/nemo_compass_plugin/analysis/pipeline.py): `plugins/nemo-compass/src/nemo_compass_plugin/analysis/pipeline.py`
- [Safety and guardrails](https://github.com/nvidia-nemo/nemo-helix/blob/main/services/guardrails/src/nhx/guardrails/app/services/rails/engine.py): `services/guardrails/src/nhx/guardrails/app/services/rails/engine.py`

### Agent improvement

- [Evaluation workflows](https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-evals/src/nemo_evals/taskset_runs/plan_storage.py): `plugins/nemo-evals/src/nemo_evals/taskset_runs/plan_storage.py`
- [Scaled evaluations](https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/_temporary-scaled-evals/src/nemo_scaled_evals_plugin/controller.py): `plugins/_temporary-scaled-evals/src/nemo_scaled_evals_plugin/controller.py`
- [Data Designer](https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-data-designer/src/nemo_data_designer_plugin/sdk/_engine_pass.py): `plugins/nemo-data-designer/src/nemo_data_designer_plugin/sdk/_engine_pass.py`
- [Optimization](https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-optimization/src/nemo_optimization/router.py): `plugins/nemo-optimization/src/nemo_optimization/router.py`
- [Model fine-tuning](https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-customizer/src/nemo_customizer/router.py): `plugins/nemo-customizer/src/nemo_customizer/router.py`
- [Data anonymization](https://github.com/nvidia-nemo/nemo-helix/blob/main/plugins/nemo-anonymizer/src/nemo_anonymizer_plugin/functions/_preview_worker.py): `plugins/nemo-anonymizer/src/nemo_anonymizer_plugin/functions/_preview_worker.py`

### Shared foundations

- [Inference gateway](https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_plugin/src/nemo_helix_plugin/inference_gateway/client.py): `packages/nemo_helix_plugin/src/nemo_helix_plugin/inference_gateway/client.py`
- [Authentication and policy](https://github.com/nvidia-nemo/nemo-helix/blob/main/services/core/auth/src/nhx/core/auth/app/embedded_pdp/engine.py): `services/core/auth/src/nhx/core/auth/app/embedded_pdp/engine.py`
- [Files and artifacts](https://github.com/nvidia-nemo/nemo-helix/blob/main/services/core/files/src/nhx/core/files/app/log_storage.py): `services/core/files/src/nhx/core/files/app/log_storage.py`
- [Jobs and orchestration](https://github.com/nvidia-nemo/nemo-helix/blob/main/packages/nemo_helix_plugin/src/nemo_helix_plugin/jobs/client.py): `packages/nemo_helix_plugin/src/nemo_helix_plugin/jobs/client.py`
- [Trace ingestion](https://github.com/nvidia-nemo/nemo-helix/blob/main/services/intake/src/nhx/intake/spans/storage.py): `services/intake/src/nhx/intake/spans/storage.py`

### Other components

- **Helix user**

## Connections

- Helix user → NeMo CLI: operates (evidence: `README.md`)
- Helix user → Python and REST: integrates through (evidence: `README.md`)
- Helix user → NeMo Studio: uses (evidence: `README.md`)
- NeMo CLI → Platform services: manages services
- Python and REST → Platform services: calls APIs
- NeMo Studio → Platform services: accesses capabilities
- Platform services → Plugin framework: hosts plugins
- Plugin framework → Agent execution: runs controller (evidence: `packages/nemo_helix_plugin/src/nemo_helix_plugin/controller.py`)
- Agent execution → Jobs and orchestration: manages deployments
- Agent execution → Inference gateway: runs agent models
- Trace ingestion → Traces and insights: supplies traces
- Traces and insights → Evaluation workflows: informs evaluations
- Evaluation workflows → Jobs and orchestration: schedules runs
- Evaluation workflows → Files and artifacts: stores plans (evidence: `plugins/nemo-evals/src/nemo_evals/taskset_runs/plan_storage.py`)
- Scaled evaluations → Jobs and orchestration: reconciles jobs (evidence: `plugins/_temporary-scaled-evals/src/nemo_scaled_evals_plugin/controller.py`)
- Data Designer → Inference gateway: resolves providers
- Data Designer → Files and artifacts: produces datasets
- Optimization → Evaluation workflows: compares candidates
- Model fine-tuning → Jobs and orchestration: launches tuning
- Safety and guardrails → Inference gateway: guards model calls
- Data anonymization → Files and artifacts: protects data
- Python and REST → Authentication and policy: carries identity
- Evaluation workflows → Inference gateway: scores candidates
