RISC-V Architectural Parameter Extractor

An AI-assisted pipeline to automatically extract, structure, and validate architectural parameters from the RISC-V ISA Manual using Open-Source Large Language Models.

Overview

Hardware specifications often hide critical parameters within dense text using specific phrasing (e.g., "implementation-specific", "optional", "may/might"). This project uses Qwen2.5-7B-Instruct to reliably parse these documents, outputting strictly formatted YAML without hallucinating external knowledge.

Architecture

The solution is divided into two modular components to handle both simple text snippets and massive HTML specification pages:

flowchart TD
    %% Branch 1: PDF Processing
    PDF["Input: PDF Snippet"] --> HFSpace["Hugging Face Space (Gradio UI)"]
    HFSpace --> YAMLOut1["YAML Output"]

    %% Branch 2: Live HTML Spec Processing
    HTML["Input: Live HTML Spec URL"] --> Scraper["Python Scraper & Chunker"]
    Scraper --> SpaceAPI["Space API"]
    SpaceAPI --> YAMLOut1

    %% Post-processing
    YAMLOut1 --> Dedupe["YAML Deduplication"]
    Dedupe --> FinalYAML["Final YAML"]

Loading

Live Demo

No local installation required. You can test the core extraction model directly in your browser:

Launch RISC-V Extractor on Hugging Face

Local Setup & Pipeline Execution

If you want to run the full automated pipeline (which scrapes the live RISC-V spec, converts HTML tables to Markdown, and processes them via the API), follow these steps:

Prerequisites

• Python 3.8

• A Hugging Face account token Get one here

Installation

1. Clone this repository:

git clone https://github.com/YOUR_GITHUB_USERNAME/riscv-param-extractor.git

cd riscv-param-extractor

2. Install the required Python packages:

pip install -r huggingface_space/requirements.txt beautifulsoup4 gradio_client pyyaml requests

Running the Extraction

1. Open pipeline/run_extraction.py.
2. Replace "hf_YOUR_TOKEN_HERE" with your actual Hugging Face token.
3. Run the script:

python pipeline/run_extraction.py

4. The script will output a deduplicated full_riscv_extraction.yaml file in the results/ directory.

Model & Prompt Engineering Details

• Model: Qwen/Qwen2.5-7B-Instruct

• Infrastructure: Hugging Face Spaces (ZeroGPU - Free NVIDIA RTX Pro 6000 Blackwell allocation)

• Temperature: 0.0 (Greedy decoding for deterministic, reproducible outputs)

Anti-Hallucination Strategies

1. Strict Negative Constraints: Prompt enforces "ONLY use information in the provided text" and outputs null for unstated fields.
2. Structural Forcing: Forces the model to begin output strictly with - name: and uses regex post-processing to strip accidental markdown code fences.
3. Table-Aware Chunking: Standard text scraping destroys HTML tables. The pipeline converts tables to Markdown format before chunking, preventing the LLM from hallucinating relationships between separated text.
4. Automated Deduplication: Character-based chunking can slice tables in half. The Python script automatically merges and deduplicates extracted YAML lists based on the name field.
5. Human-in-the-Loop Post-Processing: Manual review step to catch and collapse LLM "range explosions" (e.g., expanding vsie2-vsie26 into 25 identical entries) and truncation artifacts.

Project Structure

riscv-param-extractor/
│
├── README.md                  # You are here
├── .gitignore                 # Prevents uploading HF tokens / large model caches
│
├── huggingface_space/         # The interactive web UI & model host
│   ├── app.py                 # Gradio + ZeroGPU inference code
│   └── requirements.txt       # transformers, accelerate, gradio, pyyaml
│
├── pipeline/                  # The automation scripts
│   ├── run_extraction.py      # HTML-to-Markdown scraper & API caller
│   └── prompts.txt            # The exact System Prompt used for extraction
│
└── results/                   # The final deliverables
    ├── snippet_extraction.yaml     # Parameters from the provided PDF snippets
    └── full_page_extraction.yaml   # Parameters scraped from the full priv-csrs.html URL

UDB Schema Alignment (PoC)

This directory contains an early experimental attempt to force the LLM to output natively in the strict csr_schema.json format required by the RISC-V Unified Database.

Status: The pipeline successfully adopts the structural schema (kind, priv_mode, nested fields as keys, msb/lsb objects). However, as expected with 7B parameter models, mathematical accuracy on msb/lsb extraction currently sits at ~70-80%.

Mentorship Goal: The upcoming mentorship will focus on pushing this accuracy to >99% using techniques like Code-Interpreter agents for bit-math, strict Pydantic validation loops, and fine-tuning on the ground-truth UDB YAML files.

License

This project is licensed under the MIT License - see the LICENSE file for details.