How stable-lab/mage works
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.