AI-powered real-time inverter diagnostics, predictive maintenance, and operator guidance for utility-scale solar farms.

Team Fantastic4 | Built for HACKaMINeD 2026

1. Executive Summary
2. The Problem
3. Our Solution
4. System Architecture
5. Technology Stack
6. Module Deep Dive
   • ML Pipeline (ml/)
   • ML Inference Server (mlinference/)
   • GenAI Explanation Layer (genai/)
   • Web Application (nextjs/)
7. ML Model Selection Rationale
8. Predictive Digital Twin Architecture
9. Data Pipeline & Real-Time Flow
10. API Reference
11. Explainable AI (XAI)
12. LLM Ablation Study & Model Selection
13. Hallucination Prevention
14. Prompt Engineering
15. LangSmith Observability
16. Infrastructure & Deployment
17. Quick Start Guide
18. Hackathon Criteria Coverage
19. Performance Benchmarks
20. Future Roadmap
21. Connect With Us

LUMIN.AI is a full-stack, production-grade platform that monitors solar plant inverters in real time, predicts equipment failures before they happen, and translates complex ML predictions into actionable guidance that plant operators can immediately act on.

The system spans four independently deployable microservices:

Utility-scale solar farms deploy thousands of inverters across vast areas. When an inverter begins degrading or approaches failure, operators receive raw telemetry — voltage drops, temperature spikes, alarm codes — but lack the expertise to interpret what these numbers mean or what actions to take.

Current pain points:

• ML models output risk scores and SHAP values — operators can't interpret them
• No automated triage — operators manually inspect each alert
• Maintenance tickets are written by hand — slow and error-prone
• No centralized view across multiple plants, blocks, and inverters
• Historical fault patterns are lost — the same failures recur

LUMIN.AI solves this end-to-end:

Raw Sensor Data → ML Prediction → GenAI Explanation → Operator Dashboard
     (SCADA)       (XGBoost+SHAP)   (LLM+RAG+Tickets)   (Next.js+MySQL)

What operators see:

CRITICAL SHUTDOWN RISK (89%)

Summary:
Inverter INV-P1-L2-0 is experiencing severe overheating with temperature
at 78.6°C, significantly above the safe operating threshold. Combined
with high ambient temperature (47.3°C) and alarm code 4003, immediate
intervention is required to prevent equipment damage.

Key Risk Factors:
- Temperature (HIGH IMPACT): 78.6°C exceeds thermal protection threshold
- Ambient Temperature (MEDIUM IMPACT): 47.3°C reduces cooling efficiency
- Alarm Code 4003 (MEDIUM IMPACT): Over-temperature protection triggered

Recommended Actions:
1. Immediately inspect cooling fans and air filters
2. Check for blocked ventilation or debris accumulation
3. Verify ambient temperature sensors are functioning
4. Review alarm code 4003 in manual Section 7.3
5. Consider temporary shutdown if temperature exceeds 80°C

Urgency: IMMEDIATE

Plus auto-generated PDF maintenance tickets, multi-turn conversational Q&A, and plant-wide risk reports.

Simulator generates realistic sensor readings (CSV-derived ranges)
    │
    ▼
POST /simulate → GenAI Server (orchestrator)
    │
    ├─ 1 reading  → POST /predict on ML Inference (single)
    ├─ N readings → POST /predict/batch on ML Inference (batch)
    │
    ▼
ML Inference returns:
    - Category (A–E)
    - Confidence score
    - Probabilities {no_risk, degradation_risk, shutdown_risk}
    - SHAP top features + values
    - SHAP bar chart (base64 PNG)
    - Fault description
    │
    ▼
GenAI stores predictions + returns to Simulator
    │
    ▼
Simulator stores in MySQL (AWS RDS) → inverter_readings table
    │
    ▼
Frontend fetches via /api/operator/* and /api/chatbot/*
    │
    ▼
Operator sees: color-coded cards, SHAP charts, AI explanations,
               PDF tickets, conversational chatbot

| Layer | Technology | Purpose | | ML Training | Python, XGBoost, Optuna, SHAP, scikit-learn, SMOTE | Model training + hyperparameter optimization | | ML Inference | FastAPI, XGBoost, SHAP, NumPy, Matplotlib | Real-time prediction API with explainability | | GenAI | FastAPI, Groq (Llama 3.3 70B), LangSmith | LLM explanations, RAG, ticket generation | | RAG | PyMuPDF, SentenceTransformers, FAISS | Inverter manual retrieval-augmented generation | | Backend API | Express.js, MySQL2, JWT, bcrypt, Zod | REST API, auth, data ingestion | | Frontend | Next.js 15, TailwindCSS v4, shadcn/ui, Recharts | Operator + Admin dashboards | | Database | AWS RDS MySQL (ap-south-1) | Production cloud database | | Observability | LangSmith (LangChain) | LLM tracing, latency monitoring, token analytics | | PDF Generation | ReportLab | Professional maintenance ticket PDFs |

End-to-end machine learning pipeline for solar inverter failure-risk prediction.

Predict maintenance disruptions before they happen by classifying each inverter's operational state into three risk categories:

The pipeline runs sequentially through run_pipeline.py, with each stage caching output in .parquet/.pkl format:

• Walk-Forward Cross Validation — Strictly chronological: training window expands forward through time, preventing future-data leakage
• SMOTE (Synthetic Minority Over-sampling) — Generates synthetic failure instances so the model pays equal attention to rare failure events
• SHAP (Game-Theoretic Explainability) — Isolates the marginal impact of every sensor reading on the risk prediction (e.g., "v_r_rmean_24h being 12V below average increased shutdown probability by 14%")
• Optuna Hyperparameter Search — Explores tree depth, learning rates, bagging ratios, L1/L2 regularization across 40 intelligent trials

ml/
├── config.py                   # Hyperparameters, columns, thresholds
├── run_pipeline.py             # Main entry point (7-stage pipeline)
├── utils.py                    # I/O helpers
├── requirements.txt
├── preprocessing/
│   ├── data_ingestion.py       # CSV ingestion + schema standardization
│   ├── data_cleaning.py        # Missing values + outlier filtering
│   ├── feature_engineering.py  # Rolling windows, deltas (→ 183 features)
│   └── label_creation.py       # Heuristic auto-labeling
├── anomaly/
│   └── anomaly_detector.py     # Isolation Forest anomaly scores
├── model/
│   ├── split_and_scale.py      # Chrono split, SMOTE, StandardScaler
│   └── train_xgb.py            # Optuna XGBoost + SHAP
├── data/                       # Raw CSVs (gitignored)
├── processed/                  # Intermediate parquets (gitignored)
├── models/                     # Trained model pickles (gitignored)
└── outputs/                    # SHAP plots, reports

FastAPI server that serves the trained XGBoost model for real-time single and batch predictions with per-prediction SHAP explanations.

{
  "inverter_id": "INV-P1-L1-0",
  "dc_voltage": 620.5,
  "dc_current": 68.3,
  "ac_power": 42.1,
  "module_temp": 38.5,
  "ambient_temp": 31.2,
  "irradiation": 890.0,
  "alarm_code": 0,
  "op_state": 5120,
  "power_factor": 0.97,
  "frequency": 50.01,
  "include_shap": true,
  "include_plot": true
}

{
  "inverter_id": "INV-P1-L1-0",
  "category": "A",
  "confidence": 0.9542,
  "predicted_class": "no_risk",
  "probabilities": {
    "no_risk": 0.9542,
    "degradation_risk": 0.0312,
    "shutdown_risk": 0.0146
  },
  "fault": null,
  "readings": {
    "dc_voltage": 620.5,
    "dc_current": 68.3,
    "ac_power": 42.1,
    "module_temp": 38.5,
    "ambient_temp": 31.2,
    "irradiation": 890.0
  },
  "shap": {
    "top_features": [
      {"feature": "power_rmean_24h", "shap_value": 0.342, "rank": 1},
      {"feature": "temp_rstd_6h", "shap_value": -0.128, "rank": 2}
    ],
    "all_values": {"power": 0.34, "temp": -0.12},
    "plot_base64": "data:image/png;base64,..."
  },
  "timestamp": "2026-03-07T09:03:39+05:30"
}

The 3-class XGBoost output maps to 5 operational categories using confidence thresholds:

• Uses shap.TreeExplainer for XGBoost-native SHAP computation
• Returns top-N features ranked by absolute SHAP value
• Generates horizontal bar charts (base64 PNG) with red (risk-increasing) / blue (risk-decreasing) coloring
• Supports both list-format and 3D-array SHAP outputs across SHAP library versions

Contextual fault descriptions based on category + sensor readings:

mlinference/
├── main.py               # FastAPI server + Pydantic schemas + endpoints
├── inference.py           # XGBoost inference engine (183-feature alignment)
├── shap_explainer.py      # SHAP TreeExplainer + bar chart rendering
├── models/
│   ├── xgb_best.pkl       # Trained XGBoost model
│   ├── inference_artifacts.pkl  # Scaler + label encoder + feature columns
│   └── xgb_optuna_study.pkl    # Optuna study results
├── requirements.txt
├── start_server.bat / .sh
├── setup_env.bat / .sh
└── test_api.py / test_batch_shap.py / test_top5.py

GenAI-powered explanation layer that transforms ML risk predictions into human-readable operator guidance with RAG, agentic ticket generation, and conversational Q&A.

Inverter Manual PDF (34 MB)
    │
PyMuPDF Parser (text extraction)
    │
Text Chunking (800 words, 200 overlap)
    │
SentenceTransformer Embeddings (all-MiniLM-L6-v2)
    │
FAISS Vector Store (cached to disk)
    │
Cosine Similarity Search → Top-K relevant chunks

• First run: 2–5 minutes (builds embeddings + FAISS index)
• Subsequent runs: Instant (loads from vector_store/ cache)

The agent performs an autonomous multi-step workflow — no human intervention required:

1. Retrieve prediction data for the inverter
2. Validate SHAP features (guardrail layer 1)
3. RAG: Fetch troubleshooting context from manual
4. Format data for LLM
5. LLM generates ticket content (JSON)
6. Parse and validate JSON (guardrail layer 3)
7. Render professional A4 PDF via ReportLab
8. Return ticket ID + PDF download path

PDF Ticket Contents: Ticket ID, Priority badge, Risk score, Issue description, Root cause analysis (SHAP-based), Recommended actions, Estimated downtime, Parts needed, Safety notes, Escalation flag.

Complete ablation study comparing 3 LLMs across 27 test cases with 7 auto-generated graphs. See LLM Ablation Study.

genai/
├── app/
│   ├── main.py              # FastAPI server (15+ endpoints)
│   ├── config.py            # Environment configuration
│   ├── models.py            # Pydantic data models
│   ├── llm.py               # LLM client (Groq/OpenAI) + LangSmith
│   ├── rag.py               # RAG pipeline (PDF → FAISS)
│   ├── prompts.py           # All prompt templates
│   ├── guardrails.py        # 4-layer hallucination prevention
│   ├── explainer.py         # Risk → plain-English explanation
│   ├── agent.py             # Agentic ticket generation
│   ├── conversation.py      # Multi-turn chat memory
│   ├── ticket.py            # PDF ticket generator (ReportLab)
│   ├── synthetic_data.py    # Mock ML backend + dynamic update
│   ├── ml_client.py         # HTTP client for ML Inference server
│   └── langsmith_client.py  # LangSmith API client
├── comparative_analysis/    # 3-model ablation study
│   ├── run_ablation.py      # 27 test cases
│   ├── evaluate.py          # 5-metric auto-evaluation
│   ├── generate_report.py   # 7 comparative graphs
│   └── graphs/              # PNG charts
├── simulation_dashboard.html
├── langsmith_dashboard.html
├── requirements.txt
└── .env.example

Full-stack web application with Operator and Admin dashboards, real-time inverter monitoring, and AI chatbot integration.

UI Stack: Next.js 15 (App Router), TailwindCSS v4, shadcn/ui (Radix), Recharts, Lucide icons.

The simulator generates realistic sensor data derived from actual Plant 2 CSV statistical profiles:

Fallback: When ML servers are unavailable, the simulator gracefully falls back to local prediction generation — the frontend never goes blank.

Why we chose XGBoost — and what we considered, rejected, and plan for the future.

Both XGBoost and LightGBM are gradient-boosted tree frameworks, but XGBoost was the superior choice for this specific dataset:

Bottom line: On our 183-feature, ~50K-row solar SCADA dataset, XGBoost delivered better generalization (lower variance across walk-forward CV folds) and exact SHAP values — both critical requirements for a production explainability system.

LSTM networks are excellent for pure time-series forecasting, but they were not implemented due to time constraints. Here's the full analysis:

Our workaround: Instead of LSTM's implicit temporal learning, we engineered 183 rolling-window features (means, standard deviations, deltas over 1h/6h/24h windows) that capture the same temporal patterns XGBoost can learn from — achieving similar temporal awareness without the training/inference overhead.

Future Plan: LSTM or Transformer-based architectures (e.g., Temporal Fusion Transformer) are on our roadmap for v2, where sequence-to-sequence forecasting could predict failure windows (not just current risk state).

Ensemble stacking (e.g., XGBoost + Random Forest + LightGBM + neural net) was considered but not implemented due to GPU and compute constraints:

• Memory: Stacking 3–4 models with 183 features each would require ~4x memory at inference time
• Latency: Our real-time pipeline requires <50ms single predictions — ensemble stacking would push this to 200ms+
• SHAP Complexity: SHAP explanations for ensemble models require approximation methods (KernelSHAP), losing the exactness of TreeExplainer
• Marginal Gain: For tabular data of our scale, XGBoost with Optuna tuning typically captures 95%+ of the accuracy benefit that ensembles provide

Future Plan: If deployed at scale with GPU infrastructure, a stacked ensemble with meta-learner could be explored for marginal accuracy gains.

While ML models excel at pattern recognition, advanced statistical approaches offer compelling advantages for long-term solar asset management:

Why we didn't use them now: These methods require longer historical baselines (6–12 months minimum), domain-specific priors, and more sophisticated deployment pipelines. Our hackathon timeline favored the rapid-iteration, high-accuracy approach of XGBoost + SHAP.

Future Plan: A hybrid architecture combining XGBoost for real-time classification with Bayesian survival models for long-term remaining-useful-life (RUL) estimation would be the optimal production system.

A real-time, interactive 3D representation of the solar inverter that mirrors its physical state, health, and financial performance. Not implemented due to time constraints — architecture fully designed for future deployment.

Traditional solar monitoring relies on reactive "run-to-fail" alarms, often leading to prolonged downtime and unnecessary maintenance dispatches. By rendering a Predictive Digital Twin, we bridge the gap between raw data and physical context. Operators can visually pinpoint hardware stress (like thermal throttling) before failure occurs. When combined with predictive machine learning and a GenAI Copilot for root-cause analysis, this architecture transforms an overwhelming stream of CSV telemetry into actionable, enterprise-grade financial insights.

The Digital Twin pipeline consists of three interconnected layers: the 3D asset, the data stream, and the dynamic user interface.

The physical inverter is modeled and exported as a highly compressed .glb file — the industry standard for lightweight, zero-lag web rendering. Specific internal components are uniquely named during the 3D design phase:

• Targetable Meshes (For Click Events): Chassis, Cooling_System, Status_Screen
• Targetable Materials (For Color/Warning Changes): Chassis_Mat, Screen_Mat

The backend rapid-streams high-frequency telemetry (e.g., via WebSockets) to the frontend. The frontend catches this JSON payload and triggers real-time visual changes:

The UI features a context-switching mechanism (dropdown) to filter data by Inverter MAC address across our fleet. The dynamic payload maps to these critical parameters:

• mac — Unique Inverter ID (dataset filtering)
• timestampDate — Temporal context for predictive windows
• inverters[0].op_state — Current mode (0 = Night, 4 = Generating, 7 = Fault)
• inverters[0].alarm_code — Triggers GenAI Copilot workflows

• pv1_voltage, pv2_voltage
• pv1_current, pv1_power

• power — Active Power in kW
• meters[0].freq — Grid Frequency in Hz (spikes indicate external grid disturbances)
• meters[0].v_r, meters[0].v_y, meters[0].v_b — Phase Voltages
• meters[0].pf — Power Factor tracking

• inverters[0].temp — Internal Temperature (drives 3D model's thermal glowing effects)
• inverters[0].limit_percent — Thermal throttling percentage
• sensors[0].ambient_temp — External weather context

• smu[0].string1 through smu[0].string14 — Panel row currents (used to calculate variance for Eco-Optimized Soiling/Dirt Detection)

Status: Architecture fully designed and documented. Implementation deferred to post-hackathon due to time constraints. The current platform is production-ready without the Digital Twin — it serves as a planned premium feature for enterprise deployment.

LUMIN.AI implements explainability at every layer:

• TreeExplainer computes exact Shapley values for every prediction
• Top 5 features ranked by absolute contribution
• Visual bar charts rendered as base64 PNG
• Per-class SHAP breakdown (no_risk / degradation_risk / shutdown_risk)

• SHAP values + raw sensor readings → structured natural language
• RAG-grounded in the inverter technical manual (34 MB PDF)
• Urgency taxonomy: immediate | within_24h | scheduled | routine
• Numbered action lists with manual section references

• Color-coded inverter grid (A–E categories)
• SHAP horizontal bar charts on inverter detail view
• Trend charts showing 24h sensor history
• Fault history timeline

3 models × 3 tasks × 3 risk scenarios = 27 test cases, auto-evaluated on 5 weighted metrics.

Groq and Qwen tie on accuracy (91.7%), but Groq is 21x faster.

Figure 1: Overall performance scores across all evaluation metrics. Groq and Qwen achieve identical 91.7% scores, while Gemini lags at 79.4%.

Figure 2: Radar chart showing normalized scores across 5 evaluation dimensions. Groq and Qwen nearly overlap on every axis except latency, while Gemini shows clear dips in JSON validity and completeness.

Figure 3: Average response latency comparison. Groq delivers sub-second responses (1.0s), 8.8x faster than Gemini and 21.2x faster than Qwen.

Figure 4: Performance breakdown by task type (Explanation, Ticket Generation, Chat). Groq and Qwen achieve perfect 100% scores on structured tasks.

Figure 5: Score vs Latency scatter plot. The ideal model is in the top-left corner (high score, low latency). Groq clearly dominates the efficiency frontier.

Figure 6: Heatmap showing detailed performance across all metrics. Darker colors indicate better performance.

Figure 7: Average token usage per response. Groq is the most token-efficient (~248 tokens/response), while Gemini produces longer outputs (~444 tokens/response).

1. 21x faster than Qwen — critical for real-time operator diagnostics
2. Tied for highest accuracy (91.7%)
3. Zero hallucinations across all test cases
4. Best JSON compliance (67% vs Gemini's 44%)
5. Most token-efficient (~248 tokens/response avg)
6. Production-reliable — consistent sub-2s latency, no cold starts

cd genai
python -m comparative_analysis.run_ablation    # Run 27 test cases
python -m comparative_analysis.generate_report  # Generate 7 graphs

7 auto-generated comparison charts in comparative_analysis/graphs/:

1. Overall scores bar chart
2. Radar comparison (5 dimensions)
3. Latency comparison
4. Per-task score breakdown
5. Score vs Latency efficiency frontier
6. Detailed metric heatmap
7. Token usage comparison

LUMIN.AI implements a 4-layer guardrail system ensuring the LLM never fabricates sensor data:

Result: 0% hallucination rate across all 27 ablation test cases for all 3 evaluated models.

Key improvements in v2:

• Explicit STRICT RULES forbidding fabricated values
• Required JSON output schema for programmatic validation
• Listed exact SHAP features — LLM must reference only these
• Included raw sensor values as ground truth
• RAG manual context for grounded troubleshooting
• 4-level urgency taxonomy (immediate | within_24h | scheduled | routine)

Real-time LLM tracing for complete transparency into AI decision-making.

Public Trace Link (no login needed): https://smith.langchain.com/public/25d80aa6-41b8-4e01-9bf2-8414babc32f3/r

Every LLM call is automatically captured:

• Full prompts (system + user context)
• LLM responses (pre-guardrail output)
• Token usage (input/output per call)
• Latency (per-step timing)
• RAG retrieval (chunks + relevance scores)
• Agent reasoning chains (multi-step ticket workflows)

Open genai/langsmith_dashboard.html to see:

• KPI cards (total traces, success rate, avg latency, total tokens)
• Latency over time (line chart)
• Token usage over time (stacked bar)
• Calls by endpoint (doughnut)
• Traces table with click-to-expand detail

• Python 3.10+
• Node.js 18+
• MySQL (or AWS RDS)

cd mlinference
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8001 --reload

cd genai
pip install -r requirements.txt
cp .env.example .env
# Edit .env: add LLM_API_KEY (Groq), ML_INFERENCE_URL
uvicorn app.main:app --reload --port 8000

cd nextjs/server
cp env.example .env
# Edit .env: add AWS RDS credentials
npm install
node index.js

cd nextjs/client
npm install
npm run dev

• ML Inference: http://localhost:8001/health
• GenAI: http://localhost:8000/docs (Swagger UI)
• Backend: http://localhost:3001/api/operator/dashboard
• Frontend: http://localhost:3000

• Few-shot Prompting — Gold-standard examples in system prompts
• Chain-of-Thought — Step-by-step LLM reasoning before JSON output
• Self-Critique Loop — Second LLM call reviews first output for hallucinations
• Email Alerts — Auto-send tickets to maintenance team
• Historical Trend Analysis — Predict future failures from degradation curves

• Docker + Kubernetes — Containerized deployment
• Redis Caching — Frequently accessed predictions
• Dedicated Vector DB — Pinecone/Weaviate for RAG at scale
• Prometheus + Grafana — Infrastructure monitoring
• CI/CD Pipeline — Automated testing + deployment
• Multi-language Support — Regional languages for operators

Hackamine/
├── ml/                         # ML Training Pipeline
│   ├── config.py               # Hyperparameters & column config
│   ├── run_pipeline.py         # 7-stage pipeline entry point
│   ├── preprocessing/          # Ingestion, cleaning, features, labels
│   ├── anomaly/                # Isolation Forest
│   ├── model/                  # Split, scale, SMOTE, XGBoost+Optuna
│   └── outputs/                # SHAP plots, reports
│
├── mlinference/                # ML Inference Server (FastAPI)
│   ├── main.py                 # API endpoints
│   ├── inference.py            # XGBoost inference engine
│   ├── shap_explainer.py       # SHAP TreeExplainer
│   └── models/                 # Trained model artifacts
│
├── genai/                      # GenAI Explanation Layer (FastAPI)
│   ├── app/                    # Core modules (LLM, RAG, Agent, etc.)
│   ├── comparative_analysis/   # 3-model ablation study
│   ├── simulation_dashboard.html
│   ├── langsmith_dashboard.html
│   └── requirements.txt
│
├── nextjs/                     # Web Application
│   ├── client/                 # Next.js 15 frontend
│   ├── server/                 # Express.js backend
│   │   ├── db/                 # MySQL connection (AWS RDS)
│   │   ├── routes/             # Auth, Operator, Admin, Chatbot, Metrics
│   │   ├── simulator/          # Real-time data simulator
│   │   └── middleware/         # JWT auth middleware
│   └── BACKEND_SPEC.md         # Complete system specification
│
└── README.md                   # This file

Interested in our work? We'd love to connect. Whether it's for internships, collaborations, or hiring — reach out to any of us.

Team Fantastic4

	Tirth Patel	Neal Daftary	Parshva Shah	Priyanshu Doshi
Role	Full Stack Developer	ML Engineer	Data Researcher	GenAI Developer
LinkedIn
Portfolio	—	—	—

We're a team of second-year engineering students who built a production-grade, 4-microservice platform in a hackathon timeframe — spanning ML training pipelines, real-time inference servers, GenAI explanation engines, and full-stack web applications with cloud infrastructure.

We ship production code, not just prototypes.

Built with dedication by Team Fantastic4 for HACKaMINeD 2026