README.md

metadata

title: AgentIC
emoji: 🤖
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
app_port: 7860

AgentIC

AgentIC is an autonomous RTL-to-GDSII pipeline. Give it a natural-language chip specification — it generates RTL, writes testbenches, runs simulation, formal verification, coverage, and regression, and optionally drives physical implementation through GDSII hardening. Every stage is AI-assisted, EDA-tool-verified, and gated behind a Human-in-the-Loop approval checkpoint.

How It Runs

AgentIC is deployed as a Docker container on HuggingFace Spaces. The backend is a FastAPI server (server/api.py) running on port 7860. The frontend is a React app (web/) that connects to it via HTTP and Server-Sent Events.

Browser (React frontend)
    │  HTTP + SSE (real-time streaming)
    ▼
FastAPI  — uvicorn server.api:app :7860   ← HuggingFace Space
    │
    ├── CrewAI agents  →  LLM (NVIDIA API)   ← remote call
    └── EDA tools (iverilog, verilator, yosys, sby)  ← installed in Docker

Build Stages

Stage	What happens
SPEC	LLM structures the natural-language description into a hardware spec
RTL_GEN	Designer agent generates synthesizable Verilog
RTL_FIX	Syntax errors are caught and repaired in a repair loop
VERIFICATION	Testbench agent writes a testbench; iverilog/verilator runs simulation
FORMAL_VERIFY	yosys + sby runs bounded model checking on the RTL
COVERAGE_CHECK	Verilator coverage analysis; fails if below threshold
REGRESSION	Multi-seed regression run across corner cases
SDC_GEN	Timing constraints file generated
FLOORPLAN	(requires skip_openlane: false) OpenLane floorplanning
HARDENING	(requires skip_openlane: false) GDSII hardening
SIGNOFF	(requires skip_openlane: false) DRC/LVS sign-off
SUCCESS	All gates passed; artifacts available

Human-in-the-Loop (HITL)

Before physical implementation begins (FLOORPLAN), the build pauses and sends an approval_required event over the SSE stream. The Human-in-the-Loop Build page in the frontend shows the RTL summary, verification results, and formal proof status. You approve or reject before hardening starts.

• Approve → build continues into FLOORPLAN → HARDENING → SIGNOFF
• Reject → build stops with a full failure record

To run RTL-only (no physical stages, no HITL pause), set skip_openlane: true in the build request. This is the default on HuggingFace since OpenLane requires a full PDK installation.

EDA Tools

All EDA tools run inside the Docker container:

Tool	Installed via	Used for
iverilog	apt	Verilog compilation + simulation
verilator	apt	Coverage analysis
yosys	apt	Synthesis + formal prep
sby (SymbiYosys)	built from source	Formal verification

API Endpoints

Method	Path	Description
POST	/build	Start a build job
GET	/build/stream/{job_id}	Real-time SSE event stream
GET	/build/status/{job_id}	Job status
GET	/build/result/{job_id}	Final artifacts
GET	/approval/status	Check if waiting for HITL
POST	/approve	Approve pending stage
POST	/reject	Reject pending stage
GET	/designs	List completed designs
GET	/metrics/{design_name}	Physical metrics for a design

Interactive docs: https://huggingface.co/spaces/vxkyyy/AgentIC → /docs

Deployment

AgentIC is deployed to HuggingFace Spaces via Docker. Every push to main on GitHub automatically deploys via GitHub Actions.

See docs/DEPLOY_HUGGINGFACE.md for the full deployment guide, CI/CD explanation, and HITL operational details.

Local Development

# Build and run the backend locally
docker build -t agentic:local .
docker compose up

# API available at http://localhost:7860
# Docs at http://localhost:7860/docs

# Run the frontend (separate process)
cd web
npm install
npm run dev
# Frontend at http://localhost:5173

Environment Variables

Copy .env.example to .env and fill in your keys:

cp .env.example .env
# Edit .env — set NVIDIA_API_KEY at minimum

Variable	Required	Description
NVIDIA_API_KEY	Yes	Cloud LLM API key
NVIDIA_MODEL	No	Default: meta/llama-3.3-70b-instruct
NVIDIA_BASE_URL	No	Default: https://integrate.api.nvidia.com/v1
GROQ_API_KEY	No	Optional fallback LLM
LLM_MODEL	No	Local Ollama model override
LLM_BASE_URL	No	Local LLM endpoint

What AgentIC Actually Does

At a high level, AgentIC performs four jobs:

1. Turn an ambiguous prose specification into a structured hardware task.
2. Generate candidate RTL, testbenches, properties, and constraints.
3. Push those artifacts through quality gates with controlled repair loops.
4. Stop only when the design either passes the configured flow or fails with a concrete diagnosis.

The system is not a simple code generator. It is a build-and-check pipeline that keeps testing what it generates.

System Model

AgentIC is organized around three layers:

1. Orchestration Layer

The orchestrator owns stage transitions, retry budgets, artifact routing, and failure handling. It is the source of truth for:

• which stage runs next
• what inputs each stage is allowed to consume
• what counts as pass, fail, skip, or tool error
• how many retries are allowed
• when the build must halt instead of spinning

Core implementation: orchestrator.py

2. Tool Layer

EDA tool wrappers execute Verilator, Icarus Verilog, Yosys, and SymbiYosys. Intermediate work is staged in temporary directories; human-relevant artifacts remain in the design tree.

Core implementation: vlsi_tools.py

3. Agent Layer

Specialist AI components assist specific tasks such as RTL generation, testbench creation, failure analysis, and formal-property generation. These components do not bypass the tool checks; their output must still pass the relevant stage gates.

End-to-End Pipeline

The full build pipeline is:

Specification
  -> RTL_GEN
  -> RTL_FIX
  -> VERIFICATION
  -> FORMAL_VERIFY
  -> COVERAGE_CHECK
  -> REGRESSION
  -> HARDENING
  -> CONVERGENCE
  -> SIGNOFF

Each stage is gated. A stage can only advance if its required checks pass. There is no silent forwarding of a broken artifact.

Stage Intent

Stage	Purpose	Typical Outputs
SPECIFICATION	Normalize the user prompt into a design contract	structured prompt context
RTL_GEN	Generate initial RTL and supporting files	<name>.v, supporting metadata
RTL_FIX	Enforce syntax, lint, and semantic rigor; repair failures	corrected RTL, diagnostics
VERIFICATION	Build TB, run simulation, analyze functional failures	<name>_tb.v, sim logs, VCD
FORMAL_VERIFY	Generate SVA, preflight it, run formal checks	<name>_sva.sv, formal summaries
COVERAGE_CHECK	Improve or validate coverage after functional success	coverage metrics, coverage JSON
REGRESSION	Run directed corner-case validation	regression results
HARDENING	Invoke OpenLane flow if enabled	layout flow outputs
CONVERGENCE	Recover from physical-flow failures	updated configs or constraints
SIGNOFF	Run DRC/LVS/STA/power/equivalence style checks	signoff reports

Reliability Model

AgentIC is designed around one rule: every stage must provide enough evidence to justify the next stage.

Fail-Closed By Default

If syntax, lint, simulation, formal checks, or physical checks fail, the build does not continue unless a replacement artifact passes the relevant gate.

Deterministic Before Generative

Repair is layered:

1. deterministic cleanup or mechanical fix
2. targeted analysis
3. constrained regeneration
4. strategy pivot or fail-closed halt

This ordering matters. The system tries to preserve design intent and minimize uncontrolled rewrites.

Budgeted Loops

Each repair path is budgeted. The system tracks repeated failures and retry exhaustion to avoid infinite churn.

Core Reasoning Components

AgentIC uses multiple specialized components rather than one undifferentiated "agent".

These components are used for tasks such as:

• RTL generation
• testbench generation
• SVA generation
• constraint generation
• documentation

These outputs are still stage-gated. AgentIC does not assume that generated code is valid just because an AI model produced it.

How Reliability Is Managed

Reliability work in AgentIC focuses on three practical areas:

• clear stage boundaries
• explicit artifact passing between stages
• replayable testing from benchmark failures

The goal is to make failures diagnosable and repeatable, not to hide them behind optimistic retries.

Toolchain

AgentIC is built around open-source digital design tools:

• Verilator
• Icarus Verilog (iverilog, vvp)
• Yosys
• SymbiYosys (sby)
• OpenLane for physical implementation

Formal and physical-flow stages are optional depending on the selected build mode and installed environment.

Repository Structure

Top-level layout:

AgentIC/
├── src/agentic/          # orchestrator, tool wrappers, agents, CLI
├── tests/                # unit and reliability tests
├── benchmark/            # benchmark runner and reports
├── docs/                 # supporting documentation
├── web/                  # frontend
├── server/               # backend/service layer
├── scripts/              # helper and CI scripts
├── artifacts/            # generated runtime artifacts
└── metircs/              # benchmark and design metrics

Key files:

• README.md
• main.py
• cli.py
• orchestrator.py
• vlsi_tools.py
• USER_GUIDE.md

Installation

Prerequisites

Minimum verification flow:

Python 3.10+
Verilator 5.x
Icarus Verilog
Yosys / SymbiYosys via oss-cad-suite

Optional physical flow:

OpenLane
Docker
Installed PDK (for example sky130 or gf180)

Setup

git clone https://github.com/Vickyrrrrrr/AgentIC.git
cd AgentIC
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Environment

Typical .env values:

NVIDIA_API_KEY="your-key-here"
LLM_BASE_URL="http://localhost:11434"
OPENLANE_ROOT="/path/to/OpenLane"
PDK_ROOT="/path/to/pdk"

See USER_GUIDE.md for model backend selection details.

CLI Usage

All commands are invoked through main.py.

Build

Fast RTL and verification flow:

python3 main.py build \
  --name my_design \
  --desc "32-bit APB timer with interrupt" \
  --skip-openlane

Full flow with signoff-oriented stages:

python3 main.py build \
  --name my_design \
  --desc "32-bit APB timer with interrupt" \
  --full-signoff \
  --pdk-profile sky130

Skip coverage while still continuing from formal to regression:

python3 main.py build \
  --name my_design \
  --desc "UART transmitter with programmable baud divisor" \
  --skip-openlane \
  --skip-coverage

Important build flags:

--skip-openlane
--skip-coverage
--full-signoff
--strict-gates / --no-strict-gates
--min-coverage
--max-retries
--max-pivots
--pdk-profile {sky130,gf180}
--hierarchical {auto,off,on}
--congestion-threshold

Other Commands

python3 main.py simulate --name <design>
python3 main.py harden --name <design>
python3 main.py verify <design>

Generated Artifacts

A typical design directory contains:

designs/<name>/
├── src/
│   ├── <name>.v
│   ├── <name>_tb.v
│   ├── <name>_sva.sv
│   ├── *_formal_result.json
│   ├── *_coverage_result.json
│   └── *.vcd
├── formal/
├── config.tcl
├── macro_placement.tcl
└── ip_manifest.json

Design-local src/ is intended to keep permanent, human-useful artifacts. Tool intermediates such as Verilator build trees, compiled simulators, .sby working directories, coverage work products, and Yosys scratch outputs are staged in temporary directories and cleaned automatically.

Benchmarking

The repository includes a benchmark runner for multi-design evaluation:

python3 benchmark/run_benchmark.py --design counter8 --attempts 1 --skip-openlane

Generated summaries live under benchmark/results.

Benchmarking matters here because repeated failures usually point to pipeline issues, validation gaps, or repair-routing problems. Those failures are used to improve the system over time.

Web Interface

AgentIC includes a frontend and backend for interactive execution and live streaming of pipeline events. The UI is useful when you want:

• stage-by-stage visibility
• human approval gates
• real-time log streaming
• artifact inspection during a build

Frontend and service code:

• web
• server

Scope And Limits

AgentIC is aimed at autonomous digital design exploration, verification-heavy iteration, and open-source PDK implementation flows. It is not yet a replacement for a certified commercial signoff stack or a production ASIC team with foundry-qualified internal methodology.

Practical implications:

• benchmark pass rate still matters more than demo quality
• hierarchical repair is harder than single-module repair and is treated explicitly
• formal and coverage stages are valuable, but must be routed correctly to be useful
• "industry-grade" here means constrained, diagnosable, replayable, and fail-closed

Design Principles

The project is built around a small number of non-negotiable rules:

• fail closed
• prefer deterministic fixes before LLM fixes
• preserve design intent with minimum-diff repair
• validate every generated artifact before downstream use
• treat routing bugs as seriously as model bugs
• turn observed benchmark failures into regression tests

IP Note

This README describes capabilities and workflow at a high level. It does not document the internal prompt architecture, private heuristics, decision policies, or proprietary reasoning logic used inside the system.

License

Proprietary and Confidential.

Copyright © 2026 Vicky Nishad. All rights reserved.

This repository, including its architecture, algorithms, prompts, agent logic, repair heuristics, and associated intellectual property, may not be reproduced, distributed, reverse-engineered, or used in derivative works without explicit written permission.