User Setup Guide

Set up a working Python and Conda environment on your computer, then connect to the VeriQuest DVA server.

Provisioning Flow

Follow these three steps in order to get your computer ready for VeriQuest DVA:

Step 1: Create the veriquest Conda environment with Python 3.12.
Step 2: Install veriquest-client package into the environment.
Step 3: Run veriquest --help to verify installation and explore commands.

Order matters: Run the OS setup script first, then install veriquest-client, then use veriquest --help to confirm the installation.

1. Create the VeriQuest environment

Choose your operating system to show the matching setup commands.

Run Setup Script

chmod +x user_setup.sh
./user_setup.sh

2. Install veriquest-client

Activate the new environment, then install the client package.

Installation access required: Please connect to the VeriQuest team to get access to the private VeriQuest packages and installation instructions.

3. Verify the installation

Confirm that the client is ready and see the available commands.

Run

conda activate veriquest
veriquest --help
veriquest --version

Command Reference

Complete reference for the VeriQuest CLI commands.

Command	Description
CONFIGURATION
`veriquest configure`	Interactive menu for PostgreSQL, Jira, and Bug Memory. Add `--show` to print current status without changing anything.
`veriquest llm`	View, validate, restore, or personally override your LLM API key. Flags: `--show`, `--validate`, `--restore`.
LICENSE
`veriquest license activate`	Validate a license key with the server and lock this machine.
`veriquest license status`	Show the machine ID and whether a license key is present locally.
AUTHENTICATION
`veriquest login`	Login and start a session.
`veriquest reset-password`	Change your password and sync it to the server.
`veriquest logout`	Logout and clear session data.
STORAGE & WORKSPACE
`veriquest init`	Build the Spec KB and Design KB from the RTL and spec files named in the config.
ANALYSIS ENGINE
`veriquest parse`	Parse simulation logs → clustering + triage → unified JSON. Optional `--export` / `-e` writes a copy elsewhere.
`veriquest analyze`	Find the root cause of each failure and write one report. Optional `--failure` / `-f` investigates a single cluster id.
`veriquest jira`	Use analysis report(s) to raise a single Jira ticket.
ASSERTION MINING
`veriquest assertion plan`	Prepare requirements and select supporting spec evidence into an assertion plan.
`veriquest assertion code`	Generate SystemVerilog Assertion `.sv` code from the plan.
COVERAGE CLOSURE
`veriquest analyze_coverage`	RCA-style coverage-closure agent: explain every coverage gap and recommend a fix.
CHATBOT
`veriquest chat`	Start the terminal-first VeriQuest assistant.
PLAN & USAGE
`veriquest usage`	Show your company's remaining tokens and daily runs.

4. Configure your environment

After installation, connect the client to your infrastructure services.

Run (one time)

veriquest configure

A menu opens with three entries — 1 Database (PostgreSQL), 2 Jira (optional), 3 Bug Memory (optional). Each shows a green ✓ once its credentials are stored. The wizard runs a live connectivity test and only writes the credentials when the connection succeeds.

PostgreSQL is required. login and reset-password refuse to run without it. Jira and Bug Memory are optional.

Check what is already configured

veriquest configure --show

5. Activate your license

Bind the license to this computer. Run only once per machine.

Run (one time)

veriquest license activate

Only one time per machine. Enter your license key VQ-XXXXXXXX-XXXXXXXX-XXXX. The license is bound to this computer — it cannot be used on another machine. To check it later run veriquest license status. Do not run activate again unless your admin gives you a new key.

6. Set your own password

Your admin created your account with a temporary password. Change it the first time you log in.

Run (first time)

veriquest reset-password

It will ask for the old password, then your new password.

7. Login

Start a session.

Run

veriquest login

Enter your password when asked.

8. Configure your LLM API key

Every AI command — init, parse, analyze, assertion plan, assertion code, analyze_coverage and chat — runs on an AI provider key. Your company key is synced to this machine when you activate the license; use this command to check it or to set your own instead.

Run (one time)

veriquest llm

With no flags it shows where your current key comes from, then offers to walk you through setting your own — provider (e.g. OpenRouter), API key, and model.

Check & Validate

veriquest llm --show
veriquest llm --validate

--show prints current provider/model (no key shown). --validate tests the key against the provider.

Restore organization key

veriquest llm --restore

9. Make a project config file

There is no separate "create project" step. A project is defined by one JSON config file, and every work command reads it. Create e.g. aes.json anywhere you like:

{
  "project_name": "opentitan",
  "work_dir": "C:/sample dataset/opentitan/opentitan",
  "logs": [
    "hw/ip/aes/scratch/master/errorneous_log.log"
  ],
  "rtl": [
    "hw/ip/aes/rtl/"
  ],
  "test_bench": [
    "hw/ip/aes/dv/tb",
    "hw/ip/aes/dv/env",
    "hw/ip/aes/dv/sva"
  ],
  "test_case": [
    "hw/ip/aes/dv/tests",
    "hw/ip/aes/dv/env/seq_lib"
  ],
  "wave": [],
  "spec": [
    "hw/ip/aes/doc/theory_of_operation.md",
    "hw/ip/aes/doc/registers.md",
    "hw/ip/aes/doc/interfaces.md"
  ],
  "Assertion_requirements": "hw/ip/aes/op_titan_requirement.txt",
  "coverage": [
    "hw/ip/aes/scratch/master/aes_masked-sim-questa/passed/cov_report/merged.ucdb",
    "cov_html/index.html"
  ]
}

Field	Used by	Description
`project_name`	all	Names the Design KB folder and every output file. Case is preserved — `Caravel` stays `Caravel` — so spell it identically in every command.
`work_dir`	all	Your project root folder. Every other path in the file is relative to it.
`logs`	parse, analyze	The simulation log file(s) to parse and analyze.
`rtl`	init, analyze	Design source files or folders. Folders are scanned for `.v .sv .vh .vhd .vhdl .svh`.
`spec`	init, assertion plan	Specification documents. Required before `assertion plan` will run.
`test_bench / test_case / wave`	analyze	Extra evidence the root-cause agent may read.
`Assertion_requirements`	assertion plan	One DV requirement document. Must be `.md`, `.txt`, `.csv`, or `.xlsx`.
`coverage`	analyze_coverage	Coverage report(s) — UCDB, HTML, CSV, or the tool's text export.

Project names: letters, numbers, underscores and hyphens are all fine (aes_core, uart_top, pcie), up to 100 characters. Avoid path separators and Windows reserved names such as CON or NUL.

10. Init — build the Spec KB and Design KB

Reads the RTL and spec files named in your config and builds the two knowledge bases the later commands rely on.

Run (one time, or when RTL/spec changes)

veriquest init --config aes.json

Output: <work_dir>/dva_analysis/design_kb/<project_name>/ (Design KB) and one <work_dir>/dva_analysis/<specfile>_specs.json per spec document (Spec KB).

Nothing leaves your machine. Init scans the files in place and the engine reads them straight from work_dir — no source code is uploaded anywhere.

Run it again only when the RTL or the spec documents change. assertion plan needs both knowledge bases, so init must succeed before it.

11. Parse the simulation log

Runs the unified pipeline — vendor detect → parsing → clustering → triage. One scan across all logs, deduplication of repeated failures, then an LLM agent analyzes each unique failure and determines signal, module, protocol, failure_type, and clusters.

Run

veriquest parse --config aes.json

Optional — also write a copy elsewhere

veriquest parse --config aes.json --export results.json

Output: <work_dir>/dva_analysis/<project_name>_parsed_<date>_<time>.json — one file per run, so a re-parse never overwrites the previous run's failures. analyze reads the most recent one.

Always run parse before analyze — analyze does not parse by itself.

12. Analyze — AI root-cause analysis

Works out why each failure happened. It reads the failures from the newest _parsed_<date>_<time>.json that parse wrote, then investigates each one against your own files — the design, testbench, tests and specification named in the config.

Run

veriquest analyze --config aes.json

Optional — investigate a single failure

veriquest analyze --config aes.json --failure <cluster_id>

Report: ONE report covering the whole run, at <work_dir>/dva_analysis/<project_name>_rca_<date>_<time>.md

Every claim is checked against the files on disk before it reaches the report — the agent cannot quote lines it never opened. A failure it cannot place is reported as such rather than guessed at. Nothing is uploaded anywhere.

13. Assertion plan (optional)

Turns your DV requirement document into a reviewable assertion plan, backed by evidence selected from the Spec KB.

Prerequisites: The config needs an Assertion_requirements path and at least one spec entry, and veriquest init --config aes.json must have run.

Run

veriquest assertion plan --config aes.json

DV requirements only

veriquest assertion plan --config aes.json --only-dv-requirements

Output: <work_dir>/dva_analysis/assertion_agent_output/assertion_plan.json plus a human-readable assertion_plan.md next to it. Review the Markdown before generating code.

14. Assertion code (optional)

Translates the reviewed plan into compilable SystemVerilog Assertion properties.

Run

veriquest assertion code --config aes.json

DV-derived entries only

veriquest assertion code --config aes.json --only-dv-requirements

Output: Both in <work_dir>/dva_analysis/assertion_agent_output/: <project_name>_assertions.sv (property blocks) and <project_name>_assertions_bind.sv (per-module checker wrappers).

15. Coverage closure (optional)

An RCA-style agent that explains every coverage gap and recommends a fix. It groups gaps by type and scope, then investigates each group by reading RTL, testbench, logs and specification before handing in an evidence-checked recommendation.

Prerequisite: The config needs a coverage entry pointing at your coverage report — UCDB, HTML, CSV, or text export.

Run

veriquest analyze_coverage --config aes.json

Note the underscore: this command is analyze_coverage, not analyze-coverage. Report saved at <work_dir>/dva_analysis/<project_name>_coverage_closure_<DDMMYYYY_HHMMSS>.md

16. Chat — the VeriQuest assistant (optional)

A persistent assistant in your terminal that can discover a project, build the config for you, and run the tools conversationally. Requires a login.

Start from an existing config

veriquest chat --config aes.json

Or let it discover a project folder

veriquest chat --project "C:/sample dataset/opentitan/opentitan"

One-shot, for scripts

veriquest chat --config aes.json --once "summarise the last run"

17. Raise a Jira ticket (optional)

Attach one or more reports to a single Jira bug. Configure Jira first with veriquest configure (menu entry 2).

Single report

veriquest jira --report "C:/proj/dva_analysis/opentitan_rca_20260827_101500.md"

Multiple reports in one ticket

veriquest jira -r "path/report1.md" -r "path/report2.md"

18. Logout

Log out when finished.

Run (when finished)

veriquest logout

★ Daily workflow

Steps 1–8 are one-time per machine; step 9 is once per project. Day to day you pick one of three tracks — all of them start with a login and end with a logout.

Debug a failing regression:

Debug Track

veriquest login --email you@company.com
veriquest parse --config aes.json
veriquest analyze --config aes.json
veriquest jira -r <report.md>
veriquest logout

Mine assertions from requirements:

Assertion Mining Track

veriquest assertion plan --config aes.json
veriquest assertion code --config aes.json

Close a coverage gap:

Coverage Track

veriquest analyze_coverage --config aes.json

⚑ Quick problem fixes

Problem	What to do
command not found: veriquest	Activate the conda env: `conda activate veriquest`
Not logged in	Run `veriquest login` first
PostgreSQL is not configured	Run `veriquest configure` and complete menu entry 1 Database — login and reset-password both require it
HTTP 403, or an LLM key error	Check the key with `veriquest llm --validate`; set your own with `veriquest llm`, or go back to company key with `veriquest llm --restore`
PARSE_REQUIRED on analyze	Run `veriquest parse --config ...` first
Spec KB project mismatch	Add `spec` entries to config, then run `veriquest init --config ...`. Make sure `project_name` is spelled identically everywhere.
assertion code finds no plan	Run `veriquest assertion plan --config ...` first — code reads `assertion_plan.json`, not requirements.
License error: bound to another machine	The key was already activated elsewhere — contact your admin. Check local state with `veriquest license status`
Python version issues	Run the checker: `.\setup-scripts\check-python.bat` (Windows) or `./setup-scripts/check-python.sh` (Linux/macOS)

Server Setup Guide

Everything an admin needs to provision and bootstrap the central VeriFast server — Python, PostgreSQL, MinIO, Ollama, Qdrant, and the database bootstrap.

1. Run server_setup

Installs the server prerequisites on the central VeriFast server (Python 3.12+, PostgreSQL 16, MinIO, Ollama, Qdrant).

Run Server Setup

chmod +x server_setup.sh
sudo ./server_setup.sh

Verify Qdrant

After the server setup script finishes, verify that Docker is installed, the qdrant container is running, and the REST health endpoint responds.

Installation and startup are automatic: The scripts install or verify Docker, then create or start Qdrant with persistent storage on ports 6333 and 6334.

Verify Qdrant Running

docker --version
docker ps --filter "name=qdrant"
curl http://localhost:6333/healthz

2. Run init_client.py

Bootstrap the client server and configure it to connect to the VeriQuest Verification Intelligence Platform server.

Read before running: Open init_client.py and update the CONFIG block at the top of the file first — set your server URL and credentials. Do not run it until your settings are saved.

Run Init Client

nano init_client.py
conda activate veriquest
python3 --version
python3 init_client.py

3. Install Bug-memory

Install the Bug-memory package into the veriquest conda environment on the client server.

Installation access required: Please connect to the VeriQuest team to get access to the private Bug-memory package and installation instructions.

4. Run Bug-memory

Run Bug-memory to ingest and sync ticket history from your source. Activate the veriquest conda environment first.

Run Ingestion

conda activate veriquest
python -m bug_memory backfill --source acme-jira
python -m bug_memory --since 7D sync --source acme-jira

5. Schedule the cron job

Each source's cron: field in config/sources.yaml declares when it should run. The scripts/setup_cron.py script installs one job per enabled source, so the YAML becomes the single source of truth for both what runs and when.

It picks its backend by platform — cron on Linux/macOS, Task Scheduler on Windows.

Setup Cron Jobs

python scripts/setup_cron.py --help
python scripts/setup_cron.py install --dry-run
python scripts/setup_cron.py install
python scripts/setup_cron.py status