nitishmehta/solar-design-auditor

Solar Design Auditor - Multimodal RAG Pipeline

A Python-based agent that audits solar project designs by cross-referencing structured documents (BOQ, PVsyst), unstructured text (PRDs), and visual documents (AutoCAD PDFs, site photos) against engineering standards.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Solar Design Auditor                        │
├──────────────┬──────────────┬──────────────┬──────────────────┤
│  Document    │   Vision     │   RAG KB     │   Consistency    │
│  Parsers     │  Analyzer    │ (Standards)  │    Checker       │
│              │              │              │                  │
│ • BOQ/Excel  │ • Qwen2.5-VL │ • FAISS      │ • Capacity cross-│
│ • PVsyst     │   (or Mock)  │ • BGE-large  │   verify         │
│ • PRD/PDF    │ • CAD→Image  │ • 16 built-in│ • DC/AC ratio   │
│ • Generation │ • Site Photo │   standards  │ • Roof/mounting  │
│              │              │              │ • Shading/Vdrop  │
└──────────────┴──────────────┴──────────────┴──────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │  Audit Report   │
                    │  JSON + Markdown│
                    └─────────────────┘

Features

1. Document Parsing (document_parsers.py)

• BOQ Parser: Extracts module count, wattage, inverter capacity, mounting items from CSV/Excel. Computes DC/AC ratio.
• PVsyst Parser: Parses simulation CSVs or text reports for tilt, azimuth, module count, PR, annual generation, string details.
• PRD Parser: Extracts target capacity, roof type, module type, inverter type, special requirements from text/PDF.
• Generation Sheet Parser: Reads monitoring CSV/Excel for daily averages.

2. Vision Analysis (vision_analyzer.py)

• Uses Qwen/Qwen2.5-VL-7B-Instruct (or falls back to mock mode) to analyze:
  • AutoCAD PDF exports (roof type, obstructions, walkways, module density)
  • Site survey photos (shading, roof material, structural concerns)
• Includes pdf_page_to_image() for rendering PDFs to PNG via PyMuPDF.

3. RAG Knowledge Base (knowledge_base.py)

• 16 built-in solar engineering standards covering:
  • Roof mounting (Standing Seam, Trapezoidal, RCC, Corrugated, Tile)
  • Ground mounting / Carports (foundation, drainage, height clearance)
  • Electrical (DC cable drop <1%, DC/AC ratio 1.2-1.4, string sizing)
  • Safety (walkways ≥300mm, fire clearance, rapid shutdown)
  • Design (tilt optimization, bifacial gain, shading, wind load)
• Vector search via FAISS + BAAI/bge-large-en-v1.5 embeddings
• BM25 fallback if FAISS unavailable
• Supports custom standards injection

4. Consistency Checker (consistency_checker.py)

Cross-verifies:

• Capacity: PRD target vs BOQ modules vs PVsyst DC
• DC/AC Ratio: flags undersized (<1.1) or excessive (>1.5) inverters
• Roof/Mounting: PRD roof type vs BOQ hardware vs visual analysis
• Shading: Site/CAD shading vs PVsyst documentation; explicit "not performed" detection
• Walkways: Width checks from vision data
• Electrical: Cable sizing present; voltage drop estimation from string length + cable size
• Tilt: Extreme values; bifacial optimization opportunities
• Edge Cases: Ground mount foundation data, carport drainage/height

5. Report Generator (report_generator.py)

• Markdown: Human-readable with emojis, severity scoring, compliance checklist
• JSON: Structured machine-readable with full metadata
• Auto-saves timestamped files to ./audit_reports/

6. Reasoning Agent (reasoning_agent.py)

• Optional smolagents CodeAgent with InferenceClientModel
• Retrieves standards dynamically during reasoning
• Can find additional issues beyond rule-based checks

Quick Start

Installation

pip install -r requirements.txt

For full vision capabilities (requires GPU):

pip install transformers accelerate qwen-vl-utils

Run an Audit

# Basic audit (no vision)
python -m solar_auditor.agent /path/to/project_folder --no-vision --output-dir ./reports

# With vision (requires GPU + Qwen2.5-VL)
python -m solar_auditor.agent /path/to/project_folder --vision-model Qwen/Qwen2.5-VL-7B-Instruct --output-dir ./reports

# With LLM reasoning agent (requires HF API token)
python -m solar_auditor.agent /path/to/project_folder --use-reasoning --output-dir ./reports

# Query standards only
python -m solar_auditor.agent /path/to/project_folder --query "walkway clearance requirements"

Programmatic Usage

from solar_auditor.agent import SolarDesignAuditor

auditor = SolarDesignAuditor(
    enable_vision=False,
    output_dir="./audit_reports"
)

result = auditor.audit("/path/to/project_folder")
print(result['markdown_report'])
print(f"Status: {result['audit_results']['overall_status']}")

Project Folder Layout

Place files with these naming patterns in a folder:

project_folder/
  ├── BOQ_*.csv / BOQ_*.xlsx          # Bill of Quantities
  ├── PVsyst_*.csv / PVsyst_*.txt     # Simulation report
  ├── *PRD*.txt / *Requirement*.pdf  # Client requirements
  ├── Generation_*.csv                # Monitoring data
  ├── *CAD*.pdf / *layout*.png       # Drawings (for vision)
  └── *site*.jpg / *photo*.png       # Site photos (for vision)

Built-in Standards

Feature	Standard	Severity
Standing Seam	Non-penetrative clamps only	CRITICAL
Trapezoidal	Self-drilling screws with EPDM washers	CRITICAL
RCC Roof	≥1m parapet clearance	CRITICAL
Ground Mount	Requires geotechnical + piling data	CRITICAL
Carport	≥2.1m vehicle clearance + drainage	CRITICAL
DC Cable Drop	<1% per IEC 62548	CRITICAL
DC/AC Ratio	1.2-1.4 typical	HIGH
Walkway	≥300mm industrial roofs	HIGH
Shading	Documented in PVsyst (9AM-3PM winter)	HIGH
String Sizing	Voltage within inverter limits	CRITICAL

Demo Results

Good Design (demo_project/)

• 1800 × 550Wp modules = 990 kW DC
• 4 × 250kVA inverters = 1000 kVA AC
• PRD target: 1.0 MWp
• Result: CONDITIONAL PASS — only DC/AC ratio 0.99 slightly below 1.1

Bad Design (demo_project_bad/)

• 1200 × 450Wp = 540 kW DC vs 1.0 MWp target → CRITICAL
• Shading analysis "not performed" in PVsyst → CRITICAL
• 2.5mm2 DC cable, 150m strings → 2.05% voltage drop → CRITICAL
• RCC roof but trapezoidal clamps in BOQ → CRITICAL
• DC/AC ratio 0.54 → HIGH
• Result: FAIL (4 Critical, 1 High)

Customization

Adding New Standards

from solar_auditor.knowledge_base import SolarStandardsKB

kb = SolarStandardsKB()
kb.standards.append({
    "id": "std-017",
    "category": "Safety",
    "feature": "Lightning Protection",
    "requirement": "Class I+II SPD on DC side, Class II on AC side per IEC 62305.",
    "standard_ref": "IEC 62305",
    "severity": "CRITICAL"
})
kb._build_index()  # Rebuild index

Extending Checks

Subclass ConsistencyChecker and override any _check_* method:

from solar_auditor.consistency_checker import ConsistencyChecker

class MyChecker(ConsistencyChecker):
    def _check_custom(self, boq, pvsyst, prd):
        # Add custom logic
        pass

Tech Stack

Component	Library / Model
VLM	Qwen/Qwen2.5-VL-7B-Instruct
Embeddings	BAAI/bge-large-en-v1.5
Vector DB	FAISS-CPU
Fallback Search	BM25Okapi
Agent Framework	smolagents + InferenceClientModel
PDF Rendering	PyMuPDF
Data	pandas, openpyxl

License

Apache-2.0 (aligned with Qwen2.5-VL and HF ecosystem standards).