Metadata-Version: 2.4
Name: rtlguard
Version: 0.3.0
Summary: AI-assisted verification gap analysis for safety-critical FPGA/RTL designs
Author: RTLGuard.ai
License: MIT
Project-URL: Homepage, https://github.com/kingsleyamiah/rtl-guard-ai
Project-URL: Repository, https://github.com/kingsleyamiah/rtl-guard-ai
Project-URL: Issues, https://github.com/kingsleyamiah/rtl-guard-ai/issues
Keywords: rtl,vhdl,systemverilog,fpga,verification,coverage,safety-critical
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Testing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: anthropic>=0.40.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: google
Requires-Dist: google-genai>=0.5.0; extra == "google"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: google-genai>=0.5.0; extra == "all"

# RTLGuard

**Find what your testbench is missing.**

RTLGuard is a command-line tool for verification gap analysis on safety-critical FPGA and RTL designs. It parses VHDL and SystemVerilog source files, runs static analysis to identify untested logic, and generates structured reports with concrete test scenarios. An optional AI review pass enriches findings with deeper rationale and an executive risk assessment — supporting Anthropic, OpenAI, and Google AI providers.

Designed for engineers working to IEC 61508, DO-178C, ISO 26262, MIL-STD-882, and IEC 62061.

---

## Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Commands](#commands)
  - [analyze](#rtlguard-analyze)
- [Output Formats](#output-formats)
- [Understanding the Report](#understanding-the-report)
  - [Coverage Percentage](#coverage-percentage)
  - [Findings](#findings)
  - [Scenarios](#scenarios)
- [AI Review](#ai-review)
- [Multi-File Analysis](#multi-file-analysis)
- [Examples](#examples)

---

## Installation

Requires Python 3.10 or later.

```bash
pip install rtlguard
```

That's it. The `rtlguard` command is available immediately after install — no cloning, no build steps.

### Optional: AI provider packages

To use the AI review feature, install the package for your chosen provider:

| Provider | Install | API Key |
|----------|---------|---------|
| Anthropic (default) | included | `ANTHROPIC_API_KEY` |
| OpenAI | `pip install rtlguard[openai]` | `OPENAI_API_KEY` |
| Google Gemini | `pip install rtlguard[google]` | `GOOGLE_API_KEY` |
| All providers | `pip install rtlguard[all]` | — |

Set your API key before running with `--ai`:

```bash
# macOS / Linux
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=AIza...

# Windows (Command Prompt)
set ANTHROPIC_API_KEY=sk-ant-...

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

Verify the install:

```bash
rtlguard --help
```

---

## Quick Start

```bash
# Analyze a single VHDL file, write all report formats to ./rtlguard_out/
rtlguard analyze my_module.vhd

# Analyze a SystemVerilog file, HTML output only, custom output directory
rtlguard analyze counter.sv -f html -o reports/

# Analyze multiple files — findings and scenarios are merged and deduplicated
rtlguard analyze ctrl.vhd datapath.sv top.sv -o reports/

# AI review with the default provider (Anthropic)
rtlguard analyze my_module.vhd --ai

# AI review with OpenAI
rtlguard analyze my_module.vhd --ai --provider openai

# AI review with Google Gemini
rtlguard analyze my_module.vhd --ai --provider google

# Verbose output: shows parser warnings and per-field validation issues
rtlguard analyze my_module.vhd -v
```

---

## Commands

### `rtlguard analyze`

Parses one or more RTL source files, runs the full static analysis pipeline, and writes a verification gap report.

```
rtlguard analyze FILE [FILE ...] [options]
```

**Positional arguments**

| Argument | Description |
|----------|-------------|
| `FILE`   | One or more VHDL (`.vhd`, `.vhdl`) or SystemVerilog (`.sv`, `.v`) source files to analyze. Multiple files trigger multi-file merge mode. |

**Options**

| Flag | Default | Description |
|------|---------|-------------|
| `-o DIR`, `--output-dir DIR` | `./rtlguard_out` | Directory to write reports into. Created automatically if it does not exist. |
| `-f FORMAT`, `--format FORMAT` | `all` | Report format(s) to produce. Choices: `json`, `markdown`, `html`, `all`. |
| `--ai` | off | Run AI-assisted gap enrichment. Requires an API key for the chosen provider. Adds three analysis passes: gap enrichment, scenario enrichment, and an executive risk review. |
| `--provider PROVIDER` | `anthropic` | AI provider to use. Choices: `anthropic`, `openai`, `google`. |
| `--model MODEL` | provider default | Model name for the AI review passes. If not specified, uses the provider's default (see [AI Review](#ai-review)). |
| `--no-dedup` | off | Skip deduplication when merging results from multiple files. By default, findings and scenarios with the same semantic key are deduplicated, keeping the highest-priority copy. |
| `-v`, `--verbose` | off | Print parser warnings, validation issues, and per-step detail during analysis. Useful for diagnosing unexpected results. |
| `-h`, `--help` | — | Show help and exit. |

**Pipeline (per file)**

1. **Parse** — VHDL or SystemVerilog parser extracts entity/module structure, ports, generics, internal signals, processes, and architecture body.
2. **Signal graph** — builds a directed dependency graph; detects clocks, resets, floating signals, and undriven outputs.
3. **Coverage analysis** — identifies every measurable coverage point: reset handlers, branch conditions, toggle requirements, FSM states and transitions, functional requirements.
4. **Gap detection** — compares the coverage map against the signal graph to produce `GapFinding` objects sorted by priority.
5. **Scenario generation** — converts each gap into one or more concrete `Scenario` objects with stimulus, expectations, preconditions, and rationale.
6. **Validation** — validates the entity, scenarios, and coverage map against named rule sets (RTL-001–009, SCN-001–009, COV-001–006).

---

## Output Formats

All formats are written to `<output-dir>/` with the filename `<entity_name>_report.<ext>` for single-file runs, or `merged_report.<ext>` for multi-file runs.

| Format | File | Description |
|--------|------|-------------|
| `json` | `.json` | Machine-readable JSON. Suitable for CI pipelines, dashboards, and custom tooling. Contains the full report including all findings, scenarios, and coverage points. |
| `markdown` | `.md` | Human-readable Markdown with severity badges, summary tables, and per-finding detail. Renders well in GitHub, GitLab, and most documentation tools. |
| `html` | `.html` | Self-contained HTML with inline CSS. No external dependencies — open directly in any browser. Colour-coded by severity with a summary grid and collapsible cards. |
| `all` | all three | Produces JSON, Markdown, and HTML in a single run. Default behaviour. |

---

## Understanding the Report

### Coverage Percentage

RTLGuard reports **static coverage** — what it can determine from source code alone, without running simulation. Coverage points have one of five statuses:

| Status | Meaning |
|--------|---------|
| `covered` | Statically confirmed: the design has this property (e.g. clock signal present, reset handler exists). |
| `uncovered` | Statically confirmed: the property is missing (e.g. output port is never driven). |
| `unknown` | Cannot determine without simulation (e.g. whether a branch is actually taken in tests). |
| `partial` | Some but not all sub-conditions met. |
| `excluded` | Intentionally out of scope. |

The coverage percentage is calculated over **deterministic points only** (`covered`, `uncovered`, `partial`). Points with `unknown` status are excluded from the denominator — they are gaps in simulation coverage, not in structural correctness, and including them would make every static report show artificially low numbers.

```
coverage % = covered / (covered + uncovered + partial) × 100
```

A typical well-structured design with clock, reset, and process handlers scores 60–80% on a fresh (untested) analysis. Remaining gaps are the test scenarios RTLGuard generates for you.

### Findings

Each finding (`FND-XXX`) represents a specific verification gap:

| Severity | Meaning |
|----------|---------|
| `critical` | Safety-critical gap that must be closed before sign-off |
| `high` | Significant gap that will likely cause failures in production |
| `medium` | Coverage gap that reduces confidence in the design |
| `low` | Minor gap or informational finding |

**Gap kinds detected:**

| Kind | Description |
|------|-------------|
| `missing_reset_test` | Sequential process has no reset handler |
| `missing_normal_op_test` | No test for normal (non-reset) operation path |
| `undriven_output` | An output port has no signal path driving it |
| `floating_signal` | Internal signal has no driver |
| `untested_toggle` | Signal is never toggled in any known test |
| `untested_fsm_state` | An FSM state is never visited |
| `untested_fsm_transition` | An FSM transition is never exercised |
| `missing_clock` | No clock signal detected in the design |
| `missing_reset_signal` | No reset signal detected in the design |
| `missing_power_on_state` | No sequential process defines reset/power-on behaviour |
| `sensitivity_list_gap` | Reset signal missing from a process sensitivity list |
| `unobservable_signal` | Internal signal has no path to any output |
| `missing_branch` | A branch of a conditional (if/case) is not exercised |

### Scenarios

Each scenario (`SCN-XXX`) is a concrete test case generated from a finding. Scenarios include:

- **Stimulus** — which signals to drive and to what values
- **Expectations** — what outputs or internal signals should respond
- **Preconditions** — system state required before the test
- **Rationale** — why this scenario is needed and which gap it closes
- **Confidence** — 0.0–1.0 score indicating how certain RTLGuard is the scenario is correct
- **Safety reference** — applicable standard clause (IEC 61508, DO-178C, etc.)

---

## AI Review

The `--ai` flag enables three additional analysis passes using an AI provider of your choice:

| Pass | Description |
|------|-------------|
| **Gap enrichment** | Deepens each static finding with AI-generated rationale, additional context, and standard references specific to the design. |
| **Scenario enrichment** | Adds pseudocode, assertion templates, and step-by-step test procedures to each scenario. |
| **Executive review** | Produces a risk-level assessment (`low` / `medium` / `high` / `critical`), an executive summary, compliance notes, and recommended actions. |

AI output is merged with static analysis results in the report — AI-discovered gaps are appended alongside static findings, and enriched rationale replaces the static rationale where available.

### Providers and default models

| Provider | Flag | Default model | API key env var |
|----------|------|---------------|-----------------|
| Anthropic | `--provider anthropic` | `claude-sonnet-4-6` | `ANTHROPIC_API_KEY` |
| OpenAI | `--provider openai` | `gpt-4o` | `OPENAI_API_KEY` |
| Google | `--provider google` | `gemini-2.0-flash` | `GOOGLE_API_KEY` |

### Usage

```bash
# Default (Anthropic, claude-sonnet-4-6)
rtlguard analyze my_module.vhd --ai

# Anthropic — specific model
rtlguard analyze my_module.vhd --ai --model claude-opus-4-7

# OpenAI — default model (gpt-4o)
rtlguard analyze my_module.vhd --ai --provider openai

# OpenAI — specific model
rtlguard analyze my_module.vhd --ai --provider openai --model gpt-4o-mini

# Google Gemini — default model (gemini-2.0-flash)
rtlguard analyze my_module.vhd --ai --provider google

# Google Gemini — specific model
rtlguard analyze my_module.vhd --ai --provider google --model gemini-1.5-pro
```

Token usage and cache statistics are printed after the AI review completes. The Anthropic provider uses prompt caching on system blocks to reduce cost on repeated runs against the same design.

**Note:** If the AI API call fails, RTLGuard prints the error and continues — the static report is always written regardless of AI availability.

---

## Multi-File Analysis

Pass multiple source files to analyze an entire design in one run:

```bash
rtlguard analyze ctrl.vhd alu.vhd datapath.vhd top.sv -o reports/
```

RTLGuard processes each file through the full pipeline independently, then:

1. **Merges** all findings and scenario lists
2. **Deduplicates** by semantic key: `(gap kind, entity name, signals involved)` — keeping the highest-priority copy when duplicates exist
3. **Re-sequences** scenario IDs globally (`SCN-001`, `SCN-002`, …)
4. Writes a single `merged_report.<ext>` to the output directory

To disable deduplication and keep every finding from every file:

```bash
rtlguard analyze a.vhd b.sv --no-dedup
```

---

## Examples

**Single VHDL file, all formats:**
```bash
rtlguard analyze my_module.vhd
# Writes: rtlguard_out/my_module_report.{json,md,html}
```

**SystemVerilog, HTML only, custom output directory:**
```bash
rtlguard analyze counter.sv -f html -o reports/
# Writes: reports/counter_report.html
```

**Multi-file, merged report:**
```bash
rtlguard analyze ctrl.vhd datapath.sv alu.sv -f markdown -o reports/
# Writes: reports/merged_report.md
```

**With AI review (Anthropic):**
```bash
export ANTHROPIC_API_KEY=sk-ant-...
rtlguard analyze my_module.vhd --ai -f html
```

**With AI review (OpenAI):**
```bash
export OPENAI_API_KEY=sk-...
rtlguard analyze my_module.vhd --ai --provider openai
```

**With AI review (Google Gemini):**
```bash
export GOOGLE_API_KEY=AIza...
rtlguard analyze my_module.vhd --ai --provider google
```

**Verbose output (shows validation issues and parser warnings):**
```bash
rtlguard analyze my_design.vhd -v
```

**CI pipeline (JSON only):**
```bash
rtlguard analyze src/top.sv -f json -o ci_reports/
```

---

## Requirements

| Requirement | Version |
|-------------|---------|
| Python | ≥ 3.10 |
| anthropic | ≥ 0.40.0 (installed automatically) |
| openai | ≥ 1.0.0 (optional: `pip install rtlguard[openai]`) |
| google-genai | ≥ 0.5.0 (optional: `pip install rtlguard[google]`) |

---

## Contributing / Source

Source code and issue tracker: [github.com/kingsleyamiah/rtl-guard-ai](https://github.com/kingsleyamiah/rtl-guard-ai)
