docs/USER_GUIDE.md

AgentIC User Guide

This guide provides detailed instructions on how to switch between LLM backends and use the various commands available in AgentIC.

1. Switching LLM Backends

AgentIC operates with a Strict Two-Model Policy:

• Primary: NVIDIA Qwen Cloud (High Performance)
• Fallback: VeriReason Local (Privacy/Offline)

To Use NVIDIA Cloud (Recommended)

Ensure your NVIDIA_API_KEY is set in the .env file or your environment.

.env file:

NVIDIA_API_KEY="nvapi-..." 

The system will automatically prioritize this if the key is valid.

To Use VeriReason (Local/Offline)

To force the system to use the local VeriReason model, simply unset or remove the NVIDIA_API_KEY.

Option A: Temporarily (Command Line)

# Run with empty key to force fallback
NVIDIA_API_KEY="" python main.py build --name my_chip --desc "..."

Option B: Permanently (.env) Comment out the key in your .env file:

# NVIDIA_API_KEY="nvapi-..."

When no NVIDIA key is found, AgentIC safely falls back to the local VeriReason model configured at http://localhost:11434.

---

2. Command Reference

All commands are run via python main.py [COMMAND] [OPTIONS].

build

Automates the entire chip design pipeline: RTL → Verification → Hardening.

python main.py build --name [NAME] --desc "[DESCRIPTION]" [OPTIONS]

Options:

• --name, -n: Name of the module/project (Required).
• --desc, -d: Natural language description of functionality (Required).
• --skip-openlane: specificy this flag to stop after verification (skips GDSII hardening).
• --full-signoff: Enable rigorous verification (Formal + Coverage + Regression).
• --max-retries: Max attempts to auto-fix errors (Default: 5).
• --show-thinking: Show LLM reasoning process in console.

Example:

python main.py build -n spi_master -d "SPI Master with configurable CPOL" --full-signoff

simulate

Runs simulation on an existing design, with AI-powered auto-fixing for testbench or RTL errors.

python main.py simulate --name [NAME]

Options:

• --max-retries: Max auto-fix attempts (Default: 5).
• --show-thinking: Show detailed AI analysis of simulation logs.

harden

Runs the OpenLane flow to turn verified RTL into a GDSII layout file.

python main.py harden --name [NAME]

Features:

• Auto-generates config.tcl compliant with OpenLane 2.0.
• Runs in background or foreground.
• Performs final signoff checks (STA/Power) upon completion.

verify

Runs the standalone verification suite (Lint + Simulation + Formal).

python main.py verify [NAME]

---

3. Configuration Notes

• PDK Root: Default ~/.ciel. Change via PDK_ROOT env var.
• OpenLane Root: Default ~/OpenLane. Change via OPENLANE_ROOT env var.
• Local Model: Defaults to VeriReason-Qwen2.5-3b. Update LLM_MODEL in .env if you have a custom fine-tune.