VeriAssist AI

AI-Powered Specification Intelligence & RTL Analysis for UVM/SystemVerilog Design Verification

VeriAssist AI is a multi-agent AI system for UVM/SystemVerilog design verification engineers. It ingests hardware IP specifications (PDFs, DOCX, Markdown), parses RTL source files, and provides a reasoning-backed chat interface so engineers can query protocol behaviour, signal semantics, transfer flows, and verification requirements from their own documentation and designs — not from an LLM's generic pre-training.

The core intelligence is built on a 4-phase reasoning engine that decomposes every question, retrieves evidence across multiple angles, detects knowledge gaps, and synthesises a chain-of-thought answer with exact citations back to the source documents.

What's Built Today

Component	Status	Description
Ingestion Agent	✅ Working	Parses PDF, DOCX, MD specs into a searchable knowledge base
Hybrid RAG	✅ Working	ChromaDB + BM25 retrieval, FastEmbed ONNX embeddings
3D Scoping	✅ Working	`@subsystem:protocol:doc_type` targeting during chat
Reasoning Engine	✅ Working	4-phase CoT pipeline (decompose → retrieve → gap-fill → synthesise)
RTL Analysis	✅ Working	pyslang-based IEEE 1800-2017 parser, FSM detection, protocol inference
Chat Agent	✅ Working	Dual-mode: Spec/Protocol queries + Design RTL analysis
Chat TUI	✅ Working	Textual-based interactive chat with mode switching, RTL loading
Ingestion TUI	✅ Working	Textual-based graphical document ingestion GUI
Dynamic Tokens	✅ Working	Auto-detects truncated responses, retries with extended budget, condenses
Session Logging	✅ Working	All queries and responses logged to `.veriassist/chat_session.log`
CLI	✅ Working	`va ingest`, `va chat`, `va analyze-rtl`, `va stats`, `va ui`
UVM Generation	🔜 Planned	Driver, monitor, scoreboard generation
Debug Agent	🔜 Planned	Waveform/assertion/race-condition sub-agents
EDA Integration	🔜 Planned	VCS, Xcelium, Questa adapters

Installation

Prerequisites

Python 3.11+
Git
Anthropic API key (primary LLM backend) — get one here

Quick Setup (recommended)

One script creates the venv, installs all dependencies, creates a .env template, and runs the tests:

# Linux / macOS
chmod +x setup.sh
./setup.sh

# Windows (PowerShell)
.\setup.ps1

Then edit .env and paste your Anthropic API key.

Manual Install

git clone https://github.com/YOUR_USERNAME/veriassist-ai.git
cd veriassist-ai

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -e ".[ui,rtl,dev]"   # core + TUI + RTL parser + dev tools

va --version

Configure Your Anthropic API Key

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY = "sk-ant-api03-..."

# Linux / macOS
export ANTHROPIC_API_KEY="sk-ant-api03-..."

Or add it to a .env file in the project root (ANTHROPIC_API_KEY=sk-ant-...).

Never commit your API key — .env is already in .gitignore.

Quick Start

1. Initialise the project

va init --project-name "AMBA Interconnect VP"

Creates .veriassist/config.yaml with sane defaults.

2. Ingest your specifications

va ingest --spec docs/apb_spec.pdf --type spec --subsystem amba
va ingest --spec docs/ahb_vplan.md --type vplan --subsystem amba

Artifacts stored under .veriassist/:

project_manifest.json — index of every ingested document
<DocumentTitle>.md — structured markdown for review
vector_store/ — ChromaDB collection with chunk embeddings

3. Chat against your specs

# Reasoning engine ON (default)
va chat -q "How does write happen in APB?"

# Scope to a specific subsystem/protocol
va chat -q "@amba:APB what is PREADY timing?"

# See each reasoning phase printed
va chat -q "What is the APB setup phase?" --verbose-reasoning

# Single-shot fast mode (no reasoning engine)
va chat -q "What is PREADY?" --no-reasoning

4. Analyze RTL designs

va analyze-rtl --file examples/RTL/ip_amba_apb_master_top.v

Output: Module ports, parameters, FSM state machines, protocol inference, optional spec cross-check.

5. Interactive Chat TUI

va ui

Opens a full Textual-based chat interface with:

Mode switching between Spec/Protocol and Design RTL
RTL file loading with parsed module summary
Reasoning toggle, verbosity, and top-k controls
Session logging to .veriassist/chat_session.log
catppuccin-macchiato theme

6. Re-ingest everything after config changes

va reingest          # smart — skips unchanged documents
va reingest --force  # force re-embed everything

Architecture

See ARCHITECTURE.md for the full specification.

High-level system map

User Query
    │
    ├─── va chat (CLI) ──────────────────┐
    ├─── va ui (Chat TUI) ──────────────┤
    │                                     ▼
    │                              ┌─────────────┐
    │                              │  ChatAgent   │──── Dual Mode ──┐
    │                              │  (balanced)  │                 │
    │                              └──────┬───────┘                 │
    │                                     │                         │
    │                    ┌────────────────┤─────────────────┐       │
    │                    │ Spec/Protocol  │   Design RTL    │       │
    │                    │                │                  │       │
    │                    ▼                ▼                  │       │
    │              ┌───────────┐   ┌────────────┐           │       │
    │              │ RAGSystem │   │ RTL Parser │           │       │
    │              │  + Reason │   │ (pyslang)  │           │       │
    │              │  Engine   │   │  + RAG ctx │           │       │
    │              └─────┬─────┘   └────────────┘           │       │
    │                    │                                   │       │
    │              ┌─────▼──────┐                            │       │
    │              │ ChromaDB   │                            │       │
    │              │ + BM25     │                            │       │
    │              └────────────┘                            │       │
    │                                                       │       │
    ├─── va ingest ──► IngestionAgent ──► ChromaDB          │       │
    └─── va analyze-rtl ──► RTLAnalysisAgent ───────────────┘       │
                                                                     │
                          ┌──────────────────────────────────────────┘
                          │  Dynamic Token Management
                          │  4096 → 8192 → condense (Haiku)
                          └──────────────────────────────────

LLM Tier System

Tier	Model	Usage
Fast (Tier 1)	`claude-haiku-4-5-20251001`	Decomposition, gap-detection, JSON tasks, condensation
Balanced (Tier 2)	`claude-sonnet-4-5-20250929`	Chat queries, RTL analysis, single-shot answers
Powerful (Tier 3)	`claude-sonnet-4-6`	CoT synthesis, complex ingestion extraction

RTL Analysis

VeriAssist parses Verilog/SystemVerilog RTL using pyslang (IEEE 1800-2017 compliant) and extracts:

Module ports — direction, width, type
Parameters & localparams — with resolved values
FSM detection — state registers, states, transitions, encoding
Protocol inference — heuristic pattern matching (APB/AXI/AHB) with optional RAG confidence boosting
Report generation — Markdown tables + JSON for downstream consumers

CLI usage

va analyze-rtl --file path/to/module.v
va analyze-rtl --file path/to/module.v --top-module my_top
va analyze-rtl --file path/to/module.v --cross-check-spec

Chat TUI RTL mode

In the TUI, switch to Design RTL mode, load a Verilog file, and ask questions like:

"How do signals toggle during a write transaction?"
"Explain the FSM state transitions"
"What happens when PSLVERR is asserted?"

The agent builds a rich system prompt from the parsed module context and optionally enriches answers with spec evidence from the RAG knowledge base.

Chat TUI

The interactive Chat TUI (va ui) provides:

Feature	Description
Dual mode	Spec/Protocol ↔ Design RTL mode switching via sidebar
RTL loading	File path input + parsed module summary
Reasoning toggle	Enable/disable 4-phase reasoning engine
Top-k control	Adjust retrieval budget (3–20 chunks)
Session log	All Q&A saved to `.veriassist/chat_session.log`
Theme	catppuccin-macchiato dark theme
Keyboard	Ctrl+Q to quit, Enter to send

Dynamic Token Management

RTL-mode responses use a tiered token strategy:

Normal call at 4096 tokens (cost-efficient for most queries)
If response truncated → retry at 8192 tokens
If still truncated → condense via fast LLM (Haiku) — removes repetition while preserving all technical facts

CLI Reference

va init        [--project-name NAME]
va ingest      --spec FILE [--type spec|vplan|protocol|bug_db|vip_doc]
               [--subsystem TAG] [--force]
va reingest    [--force]
va chat        [-q QUERY] [--top-k N]
               [--reasoning | --no-reasoning]
               [--verbose-reasoning]
va analyze-rtl --file FILE [--top-module NAME] [--cross-check-spec]
va stats                     # show knowledge-base statistics
va validate    [--test-connection]
va ui                        # launch Chat TUI
va ingest-ui                 # launch Ingestion TUI

3D Knowledge Scoping

Every chunk stored in ChromaDB carries three scope dimensions:

Dimension	Metadata key	Example values
Subsystem	`subsystem`	`amba`, `coresight`, `pcie`
Protocol	`protocol`	`AHB`, `APB`, `AXI`
Doc type	`document_type`	`spec`, `vplan`, `protocol`, `bug_db`

Prefix syntax

@<subsystem>                   →  filter by subsystem only
@<protocol>                    →  filter by protocol only
@<subsystem>:<protocol>        →  subsystem AND protocol
@<subsystem>:<protocol>:<type> →  all three dimensions

Auto-detection

When no @ prefix is given, VeriAssist auto-detects scope from:

Protocol signal names — HREADY → AHB, PSEL → APB, ARVALID → AXI
Known subsystem names — queried live from the collection
Doc-type keywords — "vplan", "coverage plan", "bug" etc.

Reasoning Engine

The 4-phase reasoning engine replaces single-shot retrieval:

Phase 1 — Query Decomposition  [fast LLM, 1 call]
  Break query into main_intent + ≤4 sub-questions

Phase 2 — Multi-angle Retrieval  [0 LLM calls]
  Original query → 5 chunks, each sub-question → 3 chunks
  Deduplicate → up to 20 unique evidence chunks

Phase 3 — Gap Detection  [fast LLM, 1 call]
  Score coverage 0–1. If < 0.75: fire ≤2 follow-up queries

Phase 4 — CoT Synthesis  [powerful LLM, 1 call]
  <thinking>step-by-step reasoning</thinking>
  <answer>final answer with source citations</answer>

LLM call budget

Mode	LLM calls	Unique chunks
`--no-reasoning`	1	5
Default (reasoning)	2–3	8–20

Configuration

.veriassist/config.yaml (auto-created by va init):

project:
  name: "My DV Project"

llm:
  provider: anthropic
  model: claude-sonnet-4-6                    # Tier 3: CoT synthesis
  balanced_model: claude-sonnet-4-5-20250929  # Tier 2: standard queries
  cheap_model: claude-haiku-4-5-20251001      # Tier 1: decompose, gap-detect
  use_tiered_models: true
  temperature: 0.2
  max_tokens: 2048
  max_input_tokens: 10000

ingestion:
  vector_store_dir: .veriassist/vector_store
  output_dir: .veriassist/ingestion
  embedding_model: BAAI/bge-small-en-v1.5
  enable_bm25: true
  chunk_size: 2000
  chunk_overlap: 400

Development

Project structure

veriassist-ai/
├── src/veriassist/
│   ├── agents/
│   │   ├── ingestion_agent.py      # Document ingest pipeline
│   │   ├── chat_agent.py           # Dual-mode Chat Agent (Spec/RTL)
│   │   └── rtl_analysis_agent.py   # RTL analysis orchestrator
│   ├── cli/
│   │   └── main.py                 # Click commands
│   ├── core/
│   │   ├── config.py               # LLMConfig, Config, Settings
│   │   ├── exceptions.py
│   │   └── manifest.py             # Ingestion manifest tracker
│   ├── rag/
│   │   └── vector_store.py         # RAGSystem, ScopeFilter, hybrid search
│   ├── reasoning/
│   │   └── engine.py               # 4-phase reasoning pipeline
│   ├── rtl/
│   │   ├── module_model.py         # Pydantic models (PortInfo, FSMInfo, ModuleInfo)
│   │   ├── sv_parser.py            # pyslang wrapper
│   │   ├── protocol_inferrer.py    # Heuristic + RAG protocol matching
│   │   └── report_generator.py     # Markdown + JSON output
│   ├── ui/
│   │   ├── ingestion_tui.py        # Textual TUI for ingestion
│   │   └── chat_tui.py             # Textual TUI for chat
│   └── utils/
│       └── llm_factory.py          # LLM provider factory
├── tests/
│   └── unit/                       # 118 tests
│       ├── test_config.py          # (3 tests)
│       ├── test_scope_filter.py    # (23 tests)
│       ├── test_reasoning_engine.py # (15 tests)
│       ├── test_ingestion_tui.py   # (3 tests)
│       ├── test_chat_agent.py      # (23 tests)
│       ├── test_chat_tui.py        # (7 tests)
│       ├── test_sv_parser.py       # (25 tests)
│       └── test_module_model.py    # (19 tests)
├── examples/
│   └── RTL/                        # APB master sample Verilog
├── ARCHITECTURE.md
├── CHANGELOG.md
└── pyproject.toml

Running tests

# All 118 unit tests
pytest tests/unit/ --override-ini="addopts=" -v

# Quick without verbose
pytest tests/unit/ --override-ini="addopts=" -q

Install extras

pip install -e ".[ui]"     # Textual TUI
pip install -e ".[rtl]"    # pyslang RTL parser
pip install -e ".[dev]"    # pytest, ruff, coverage
pip install -e ".[all]"    # everything

License

MIT — see LICENSE.

Built by verification engineers, for verification engineers.

Name		Name	Last commit message	Last commit date
.github/instructions		.github/instructions
Invoices		Invoices
docs		docs
examples		examples
scripts		scripts
src/veriassist		src/veriassist
testbench		testbench
tests		tests
.copilotignore		.copilotignore
.env.example		.env.example
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Planning_Agent.txt		Planning_Agent.txt
README.md		README.md
TB_Generation.md		TB_Generation.md
config.yaml		config.yaml
pyproject.toml		pyproject.toml
setup.ps1		setup.ps1
setup.sh		setup.sh

Latest commit

History

Folders and files

Repository files navigation