# stable-lab/mage architecture

> Architecture diagram of the GitHub repository stable-lab/mage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stable-lab/mage
- Repository: https://github.com/stable-lab/mage

## Overview

##### Project Type & Purpose
- MAGE is an open-source multi-agent engine aimed at automated RTL code generation using large language models (LLMs).
- The README and file structure reveal that the main objective is to generate and simulate RTL code with a multi-agent interplay that leverages different LLM providers (e.g., Anthropic’s Claude, OpenAI’s GPT models).

##### Analyzing the File Structure for Architectural Cues
- The top-level directories:
- “src/mage”: Contains the core logic including agent management, configuration generation, prompting, token counting, and various utility functions.
- “src/sim”: Holds files related to simulation including SystemVerilog files and Makefiles. This indicates a clear separation between the code generation (MAGE engine) and simulation/verification components.
- “tests”: Contains unit and integration tests for various components (e.g., agents, RTL generators).
- “fig”: Holds PDF and image files that likely detail design overviews and evaluation results, suggesting available visual artifacts that represent parts of the architecture.
- Other files (e.g., action.yml, pyproject.toml, development guide) show integrations with CI/CD and packaging, but the central focus remains on multi-agent-driven code generation and simulation of RTL designs.

##### Key Components
a. Multi-Agent Engine (Core in src/mage):
- The “agent.py” likely defines the central role of agents.
- Subcomponents such as “prompts.py”, “rtl_generator.py”, “rtl_editor.py”, “sim_judge.py”, and “sim_reviewer.py” indicate distinct responsibilities like code generation, simulation evaluation, and review.
- Utility modules (e.g., “token_counter.py”, “log_utils.py”) handle ancillary tasks crucial for smooth operation.
b. Convergence/Code Coverage Tools:
- The “src/mage/converage” directory contains C++ and Python integration (e.g., LLMGuidance.cpp/h, LLMGuidance4CodeCov*.cpp/h, and RunGPT.py) suggesting special modules to guide or analyze code generation coverage.
c. Simulation/Verification Environment:
- The “src/sim” directory includes simulation files (e.g., “top.sv”, “sim_golden.vvp”) and Makefiles which are instrumental in verifying the generated RTL code.
d. External Dependencies and APIs:
- The README details how to configure API keys for different LLM providers, showing external interactions.
- Additionally, the integration with third-party tools (e.g., Icarus Verilog, Verilator, and Pyverilog) is key to the simulation and evaluation process.
e. Benchmarking & Testing:
- The “tests” directory and references in the README to benchmarks (via submodules like “verilog-eval”) indicate that the system can be evaluated against preset RTL designs.

##### Relationships and Interactions
- Agents coordinate via message passing or function calls (illustrate interactions between “agent.py” and “rtl_generator.py”).
- Post-generation, the RTL output flows into the simulation environment (“src/sim”), where simulation tools and test benches (like “sim_judge.py” and “sim_reviewer.py”) analyze performance.
- Configuration and API communication flows:
- API keys/configuration (via key.cfg and environment variables) form the connection between the engine and external LLM APIs.
- Interactions with benchmarking tools:

##### Architectural Patterns and Design Principles
- Multi-agent Architecture: Emphasize how distinct agents handle individual tasks (code generation, simulation evaluation, and logging).
- Separation of Concerns: Clear split between the components generating code and those verifying or simulating the generated RTL.
- Modularity: The structure shows separation into different directories (mage, sim, tests) that promote independent development and testing.
- Integration of External Tools: The use of verilog simulators and varied LLM APIs signifies a design that integrates heterogeneous components seamlessly.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Dependencies & API
    EX["API & Config"]:::external

    %% Multi-Agent Engine Subgraph
    subgraph "Multi-Agent Engine"
        A1["agent.py"]:::mage
        A2["prompts.py"]:::mage
        A3["rtl_generator.py"]:::mage
        A4["rtl_editor.py"]:::mage
        A5["sim_judge.py"]:::mage
        A6["sim_reviewer.py"]:::mage
        A7["token_counter.py"]:::mage
        A8["utils.py"]:::mage
    end

    %% Convergence/Code Coverage Tools Subgraph
    subgraph "Convergence/Code Coverage Tools"
        C1["LLMGuidance.cpp"]:::convergence
        C2["LLMGuidance.h"]:::convergence
        C3["LLMGuidance4CodeCov.cpp"]:::convergence
        C4["LLMGuidance4CodeCov.h"]:::convergence
        C5["RunGPT.py"]:::convergence
    end

    %% Simulation/Verification Environment Subgraph
    subgraph "Simulation/Verification Environment"
        S1["top.sv"]:::sim
        S2["sim_golden.vvp"]:::sim
        S3["Makefile"]:::sim
    end

    %% Benchmarking & Testing Subgraph
    subgraph "Benchmarking & Testing"
        T1["tests"]:::testing
        T2["verilog-eval"]:::testing
    end

    %% Relationships and Data Flow
    EX -->|"config"| A1
    EX -->|"config"| A7
    A3 -->|"generates RTL"| S1
    A3 -->|"coverage check"| C1
    S1 -->|"feedback"| A5
    S1 -->|"feedback"| A6
    S2 -->|"simulation results"| T1
    S2 -->|"benchmark data"| T2

    %% Click Events for Multi-Agent Engine Files
    click A1 "https://github.com/stable-lab/mage/blob/main/src/mage/agent.py"
    click A2 "https://github.com/stable-lab/mage/blob/main/src/mage/prompts.py"
    click A3 "https://github.com/stable-lab/mage/blob/main/src/mage/rtl_generator.py"
    click A4 "https://github.com/stable-lab/mage/blob/main/src/mage/rtl_editor.py"
    click A5 "https://github.com/stable-lab/mage/blob/main/src/mage/sim_judge.py"
    click A6 "https://github.com/stable-lab/mage/blob/main/src/mage/sim_reviewer.py"
    click A7 "https://github.com/stable-lab/mage/blob/main/src/mage/token_counter.py"
    click A8 "https://github.com/stable-lab/mage/blob/main/src/mage/utils.py"

    %% Click Events for Convergence/Code Coverage Tools
    click C1 "https://github.com/stable-lab/mage/blob/main/src/mage/converage/LLMGuidance.cpp"
    click C2 "https://github.com/stable-lab/mage/blob/main/src/mage/converage/LLMGuidance.h"
    click C3 "https://github.com/stable-lab/mage/blob/main/src/mage/converage/LLMGuidance4CodeCov.cpp"
    click C4 "https://github.com/stable-lab/mage/blob/main/src/mage/converage/LLMGuidance4CodeCov.h"
    click C5 "https://github.com/stable-lab/mage/blob/main/src/mage/converage/RunGPT.py"

    %% Click Events for Simulation/Verification Environment
    click S1 "https://github.com/stable-lab/mage/blob/main/src/sim/top.sv"
    click S2 "https://github.com/stable-lab/mage/blob/main/src/sim/sim_golden.vvp"
    click S3 "https://github.com/stable-lab/mage/tree/main/src/sim/Makefile"

    %% Click Event for External Dependencies
    click EX "https://github.com/stable-lab/mage/blob/main/README.md"

    %% Click Events for Benchmarking & Testing
    click T1 "https://github.com/stable-lab/mage/tree/main/tests"
    click T2 "https://github.com/stable-lab/mage/tree/main/verilog-eval"

    %% Styles
    classDef mage fill:#a1c4fd,stroke:#1f78c1,stroke-width:2px;
    classDef convergence fill:#f3e9d2,stroke:#d9843b,stroke-width:2px;
    classDef sim fill:#c9f7f5,stroke:#33a6a6,stroke-width:2px;
    classDef external fill:#f9d6d5,stroke:#d9534f,stroke-width:2px;
    classDef testing fill:#d4e4f7,stroke:#2e64a4,stroke-width:2px;
```
