# nvlabs/ace-rtl architecture

> Architecture diagram of the GitHub repository nvlabs/ace-rtl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvlabs/ace-rtl
- Repository: https://github.com/nvlabs/ace-rtl

## Overview

ACE-RTL is an agentic RTL generation, verification, and iterative-repair system. The principal workflow starts with a user-selected task, runs generation and verification, uses tool feedback to guide reflection and coordination, and returns artifacts and results. Its runtime also includes a native CVDP evaluator and shared LLM backend. The graph preserves the README’s Generator/Reflector/Coordinator workflow and major benchmark integrations; edges are limited to README statements and SOURCE INDEX references, so unsampled implementation details are not inferred.

Main entry points: [`skills/ace-rtl/scripts/ace_cvdp_native/cli.py`](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/cli.py) (Native runner), [`skills/ace-rtl/scripts/ace_rtl_agent/agent.py`](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/agent.py) (Agent runtime), [`skills/ace-rtl/scripts/ace_rtl_agent/llm_centric_debugger.py`](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/llm_centric_debugger.py) (LLM debugger), [`skills/ace-rtl/scripts/ace_rtl_agent/comprehensive_error_analyzer.py`](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/comprehensive_error_analyzer.py) (Error analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Agent orchestration"]
  node_main["Agent CLI<br/>[main.py]"]
  node_agent["Agent runtime<br/>[agent.py]"]
  node_loop["Iteration loop<br/>[agent_loop.py]"]
  node_report["Run reporting<br/>[agent_reporting.py]"]
  node_fresh["Role coordinator"]
end

subgraph group_rtl["RTL reasoning"]
  node_generator["RTL generator<br/>[rtl_generator.py]"]
  node_focused["Focused debugger"]
  node_llm_debug["LLM debugger"]
  node_deep_error["Error analysis"]
  node_failure["Failure extraction"]
  node_rules["RTL rule advice"]
  node_testbench["Testbench analysis"]
end

subgraph group_models["LLM services"]
  node_llm_client["LLM client<br/>[llm_client.py]"]
  node_ace_client["ACE model adapter"]
  node_backend["LLM backend<br/>[llm_backend.py]"]
end

subgraph group_bench["Benchmark evaluation"]
  node_cvdp["CVDP integration"]
  node_verilogeval["VerilogEval integration"]
  node_chipbench["ChipBench integration"]
  node_native_cli["Native runner<br/>[cli.py]"]
  node_native_config["Task configuration<br/>[config.py]"]
  node_native_process["Run processes<br/>[processes.py]"]
  node_native_harness["CVDP harness<br/>[harness.py]"]
  node_native_diag["Result diagnostics<br/>[diagnostics.py]"]
  node_native_sv["SystemVerilog helpers<br/>[sv.py]"]
end

node_user(("Task user"))
node_nvidia["NVIDIA API"]

node_user -->|"submits task"| node_main
node_main -->|"starts runtime"| node_agent
node_agent -->|"delegates iteration"| node_loop
node_agent -->|"delegates reporting"| node_report
node_agent -->|"uses generation"| node_generator
node_agent -->|"uses evaluation"| node_cvdp
node_agent -->|"uses evaluation"| node_verilogeval
node_agent -->|"uses integration"| node_chipbench
node_loop -.->|"coordinates roles"| node_fresh
node_loop -.->|"reflects on failures"| node_focused
node_llm_debug -->|"uses debugging"| node_focused
node_llm_debug -->|"analyzes tests"| node_testbench
node_llm_debug -->|"requests analysis"| node_llm_client
node_llm_debug -->|"requests model call"| node_ace_client
node_deep_error -->|"extracts failure"| node_failure
node_deep_error -->|"requests analysis"| node_llm_client
node_deep_error -->|"consults rules"| node_rules
node_llm_client -->|"calls backend"| node_backend
node_ace_client -->|"calls backend"| node_backend
node_backend -->|"sends requests"| node_nvidia
node_native_cli -->|"loads configuration"| node_native_config
node_native_cli -->|"uses process helpers"| node_native_process
node_native_cli -->|"runs evaluation"| node_native_harness
node_native_cli -->|"uses RTL helpers"| node_native_sv
node_native_cli -->|"summarizes results"| node_native_diag
node_native_harness -->|"reads settings"| node_native_config
node_native_harness -->|"uses process helpers"| node_native_process
node_native_cli -->|"invokes agent roles"| node_fresh
node_native_cli -->|"evaluates benchmark"| node_cvdp

click node_main "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/main.py"
click node_agent "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/agent.py"
click node_loop "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/agent_loop.py"
click node_report "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/agent_reporting.py"
click node_fresh "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/fresh_start_coordinator.py"
click node_generator "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/rtl_generator.py"
click node_focused "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/focused_debugger.py"
click node_llm_debug "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/llm_centric_debugger.py"
click node_deep_error "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/comprehensive_error_analyzer.py"
click node_failure "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/primary_failure_extractor.py"
click node_rules "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/rtl_rule_advisor.py"
click node_testbench "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/testbench_analyzer.py"
click node_llm_client "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/utils/llm_client.py"
click node_ace_client "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/utils/ace_model_client.py"
click node_backend "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/llm_backend.py"
click node_cvdp "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/utils/cvdp_environment.py"
click node_verilogeval "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/utils/verilogeval_integration.py"
click node_chipbench "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/utils/chipbench_integration.py"
click node_native_cli "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/cli.py"
click node_native_config "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/config.py"
click node_native_process "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/processes.py"
click node_native_harness "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/harness.py"
click node_native_diag "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/diagnostics.py"
click node_native_sv "https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/sv.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_main,node_agent,node_loop,node_report,node_fresh toneBlue
class node_generator,node_focused,node_llm_debug,node_deep_error,node_failure,node_rules,node_testbench toneAmber
class node_llm_client,node_ace_client,node_backend,node_nvidia toneMint
class node_cvdp,node_verilogeval,node_chipbench,node_native_cli,node_native_config,node_native_process,node_native_harness,node_native_diag,node_native_sv,node_user toneRose
```

## Components

### Agent orchestration

- [Agent CLI](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/main.py): `skills/ace-rtl/scripts/ace_rtl_agent/main.py`
- [Agent runtime](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/agent.py): `skills/ace-rtl/scripts/ace_rtl_agent/agent.py`
- [Iteration loop](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/agent_loop.py): `skills/ace-rtl/scripts/ace_rtl_agent/agent_loop.py`
- [Run reporting](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/agent_reporting.py): `skills/ace-rtl/scripts/ace_rtl_agent/agent_reporting.py`
- [Role coordinator](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/fresh_start_coordinator.py): `skills/ace-rtl/scripts/ace_rtl_agent/fresh_start_coordinator.py`

### RTL reasoning

- [RTL generator](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/rtl_generator.py): `skills/ace-rtl/scripts/ace_rtl_agent/rtl_generator.py`
- [Focused debugger](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/focused_debugger.py): `skills/ace-rtl/scripts/ace_rtl_agent/focused_debugger.py`
- [LLM debugger](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/llm_centric_debugger.py): `skills/ace-rtl/scripts/ace_rtl_agent/llm_centric_debugger.py`
- [Error analysis](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/comprehensive_error_analyzer.py): `skills/ace-rtl/scripts/ace_rtl_agent/comprehensive_error_analyzer.py`
- [Failure extraction](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/primary_failure_extractor.py): `skills/ace-rtl/scripts/ace_rtl_agent/primary_failure_extractor.py`
- [RTL rule advice](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/rtl_rule_advisor.py): `skills/ace-rtl/scripts/ace_rtl_agent/rtl_rule_advisor.py`
- [Testbench analysis](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/testbench_analyzer.py): `skills/ace-rtl/scripts/ace_rtl_agent/testbench_analyzer.py`

### LLM services

- [LLM client](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/utils/llm_client.py): `skills/ace-rtl/scripts/ace_rtl_agent/utils/llm_client.py`
- [ACE model adapter](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/utils/ace_model_client.py): `skills/ace-rtl/scripts/ace_rtl_agent/utils/ace_model_client.py`
- [LLM backend](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/llm_backend.py): `skills/ace-rtl/scripts/ace_rtl_agent/llm_backend.py`

### Benchmark evaluation

- [CVDP integration](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/utils/cvdp_environment.py): `skills/ace-rtl/scripts/ace_rtl_agent/utils/cvdp_environment.py`
- [VerilogEval integration](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/utils/verilogeval_integration.py): `skills/ace-rtl/scripts/ace_rtl_agent/utils/verilogeval_integration.py`
- [ChipBench integration](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_rtl_agent/utils/chipbench_integration.py): `skills/ace-rtl/scripts/ace_rtl_agent/utils/chipbench_integration.py`
- [Native runner](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/cli.py): `skills/ace-rtl/scripts/ace_cvdp_native/cli.py`
- [Task configuration](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/config.py): `skills/ace-rtl/scripts/ace_cvdp_native/config.py`
- [Run processes](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/processes.py): `skills/ace-rtl/scripts/ace_cvdp_native/processes.py`
- [CVDP harness](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/harness.py): `skills/ace-rtl/scripts/ace_cvdp_native/harness.py`
- [Result diagnostics](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/diagnostics.py): `skills/ace-rtl/scripts/ace_cvdp_native/diagnostics.py`
- [SystemVerilog helpers](https://github.com/nvlabs/ace-rtl/blob/main/skills/ace-rtl/scripts/ace_cvdp_native/sv.py): `skills/ace-rtl/scripts/ace_cvdp_native/sv.py`

### Other components

- **Task user**
- **NVIDIA API**

## Connections

- Task user → Agent CLI: submits task
- Agent CLI → Agent runtime: starts runtime (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/main.py`)
- Agent runtime → Iteration loop: delegates iteration (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/agent.py`)
- Agent runtime → Run reporting: delegates reporting (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/agent.py`)
- Agent runtime → RTL generator: uses generation (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/agent.py`)
- Agent runtime → CVDP integration: uses evaluation (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/agent.py`)
- Agent runtime → VerilogEval integration: uses evaluation (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/agent.py`)
- Agent runtime → ChipBench integration: uses integration (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/agent.py`)
- Iteration loop → Role coordinator: coordinates roles
- Iteration loop → Focused debugger: reflects on failures
- LLM debugger → Focused debugger: uses debugging (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/llm_centric_debugger.py`)
- LLM debugger → Testbench analysis: analyzes tests (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/llm_centric_debugger.py`)
- LLM debugger → LLM client: requests analysis (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/llm_centric_debugger.py`)
- LLM debugger → ACE model adapter: requests model call (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/llm_centric_debugger.py`)
- Error analysis → Failure extraction: extracts failure (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/comprehensive_error_analyzer.py`)
- Error analysis → LLM client: requests analysis (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/comprehensive_error_analyzer.py`)
- Error analysis → RTL rule advice: consults rules (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/comprehensive_error_analyzer.py`)
- LLM client → LLM backend: calls backend (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/utils/llm_client.py`)
- ACE model adapter → LLM backend: calls backend (evidence: `skills/ace-rtl/scripts/ace_rtl_agent/utils/ace_model_client.py`)
- LLM backend → NVIDIA API: sends requests
- Native runner → Task configuration: loads configuration (evidence: `skills/ace-rtl/scripts/ace_cvdp_native/cli.py`)
- Native runner → Run processes: uses process helpers (evidence: `skills/ace-rtl/scripts/ace_cvdp_native/cli.py`)
- Native runner → CVDP harness: runs evaluation (evidence: `skills/ace-rtl/scripts/ace_cvdp_native/cli.py`)
- Native runner → SystemVerilog helpers: uses RTL helpers (evidence: `skills/ace-rtl/scripts/ace_cvdp_native/cli.py`)
- Native runner → Result diagnostics: summarizes results (evidence: `skills/ace-rtl/scripts/ace_cvdp_native/cli.py`)
- CVDP harness → Task configuration: reads settings (evidence: `skills/ace-rtl/scripts/ace_cvdp_native/harness.py`)
- CVDP harness → Run processes: uses process helpers (evidence: `skills/ace-rtl/scripts/ace_cvdp_native/harness.py`)
- Native runner → Role coordinator: invokes agent roles
- Native runner → CVDP integration: evaluates benchmark
