Why do we need GridGuard?
Modern electric grids face volatile demand, temperature extremes, generation outages, and rapidly changing reserve conditions. Operators must interpret multiple signals and make high-stakes decisions quickly.
Traditional forecasting tools provide a number but often fail to explain the operational consequence. Fully autonomous AI can create the opposite problem: recommendations that are difficult to inspect, govern, or safely challenge.
GridGuard AI bridges that gap. It combines XGBoost forecasting, a seasonal-naive benchmark, SHAP explanations, deterministic risk rules, local policy retrieval, selectable LLM reasoning, and an optional three-agent debate committee. Every recommendation remains advisory until a human operator approves, rejects, or escalates it.
System Architecture Breakdown
The shared pipeline prepares the evidence once, then routes it through the decision method selected by the operator.
1. Data Ingestion & Normalization
Ingests reproducible synthetic data, historical Kaggle CSV/ZIP files, or recent EIA balancing-authority demand. Source adapters normalize timestamps, detect missing hours, apply the selected quality policy, and output one canonical hourly schema.
2. XGBoost Forecasting & Benchmarking
Builds lag, rolling, calendar, and temperature features for a recursive 12–48 hour demand forecast. A chronological holdout compares XGBoost against a seasonal-naive weekly-lag baseline.
3. Explainability & Risk Evidence
SHAP identifies the drivers behind the forecast. The risk engine then evaluates peak load, available capacity, reserve margin, high-risk hours, generation outages, and demand shocks.
4. X-Decision Orchestration
X-Decision means explainable decision intelligence. It assembles forecast facts, fired expert rules, model-quality evidence, scenario assumptions, local RAG policy chunks, and recent bounded decision memory.
5. Selectable Reasoning Path
The operator selects the Internal Expert System, Groq, or Gemini. Groq and Gemini can produce a single grounded briefing or convene the optional Multi-Agent Debate Committee.
6. Human Control, Audit & Operations
The Streamlit Control Tower requires an operator decision and rationale. Records persist to JSON or PostgreSQL, while Flask/Waitress endpoints expose health, readiness, audit, memory, and token status.
End-to-End Architecture
One governed data and forecasting pipeline supplies evidence to several decision paths without giving any AI component direct control authority.
1. Shared Forecasting and Governance Pipeline
Every decision engine receives the same normalized data, forecast, benchmark, scenario, risk, and policy evidence.
The numerical forecast and the decision explanation remain separate, making each stage easier to test, audit, and replace.
2. Three Decision Engines and Two Reasoning Styles
The debate committee is an optional orchestration mode for Groq or Gemini; it is not a fourth provider and is never used by the internal deterministic engine.
Provider failures never remove the internal expert system. LLM output remains advisory and cannot execute grid actions.
3. Multi-Agent Debate Committee
When enabled for Groq or Gemini, the committee divides the reasoning task into quantitative analysis, policy compliance, and final dispatch synthesis.
The transcript is displayed in the dedicated Committee Transcript tab, preserving visibility into each agent's contribution.
Three Decision-System Options
The forecasting evidence stays constant; the selected engine changes how that evidence is interpreted and communicated.
Internal Expert System
A transparent zero-token path that applies hard-coded boolean rules and produces a structured X-Decision briefing without an external model.
- No API key or hosted LLM required
- Every fired rule and evidence item is visible
- Always available as the resilient fallback
- Does not use the Debate Committee
Groq Reasoning
Produces a fast grounded operator briefing from forecast facts, expert rules, local RAG context, and bounded conversation memory.
- Selectable hosted Groq model
- Single-shot grounded briefing mode
- Optional Multi-Agent Debate Committee
- Prompt, completion, and total-token tracking
Gemini Reasoning
Generates a policy-grounded briefing from the same governed evidence package and can participate in the committee workflow.
- Selectable Gemini model
- Single-shot grounded briefing mode
- Optional Multi-Agent Debate Committee
- Provider-specific usage and reset controls
Operational Capabilities
GridGuard is designed as an explainable decision-support control tower rather than an autonomous grid controller.
Scenario Lab
Stress-tests the forecast under weather, demand, capacity, and generation assumptions before a recommendation is made.
- Temperature adjustments
- Demand-shock simulation
- Generation-outage scenarios
- Baseline versus stressed risk comparison
Peak & Reserve-Risk Detection
Converts raw forecast values into operating signals by assessing effective capacity, reserve pressure, and the number of high-risk hours.
- Peak demand and peak timestamp
- Reserve-margin evidence
- Low, watch, elevated, and critical states
- Human verification when confidence is weak
Local RAG & Decision Memory
Retrieves relevant local Markdown or text policy chunks and combines them with bounded JSON-backed conversation history.
- TF-IDF and cosine-similarity retrieval
- Visible source and chunk identifiers
- Grounded prompts for hosted models
- Memory limits to control prompt growth
Model Governance
Measures whether the trained XGBoost model actually improves upon a straightforward time-series baseline.
- Chronological holdout evaluation
- MAE and RMSE reporting
- Seasonal-naive weekly-lag comparison
- Warning when XGBoost fails to outperform
Human Approval Workflow
No recommendation becomes a recorded operational decision until a human reviews the evidence and enters a rationale.
- Approve, reject, or escalate
- Operator notes and rationale
- Data source and model provenance
- Decision history for later review
Audit & System Operations
Separates application health, decision records, memory, RAG status, and token usage into inspectable operational surfaces.
- JSON or PostgreSQL persistence
- Flask/Waitress health and readiness API
- Provider and global token counters
- Seven focused Streamlit tabs
What Makes GridGuard Different?
The project goes beyond a forecasting notebook by connecting predictive evidence to governed, explainable, and reviewable operational decisions.
| Capability | Traditional Forecasting Tool | GridGuard AI |
|---|---|---|
| Forecast output | Demand values or a chart | 12–48 hour forecast plus peak, reserve, scenario, and risk evidence |
| Explainability | Limited or model-specific | SHAP drivers, fired-rule trace, benchmark metrics, and policy sources |
| Decision reasoning | One fixed analytical path | Internal deterministic, Groq, or Gemini with optional agent debate |
| Governance | Recommendation may be detached from policy | Local RAG, compliance review, human rationale, and persisted provenance |
| Resilience | Hosted model failure may block output | Zero-token Internal Expert System remains available |
| Control authority | Varies by implementation | Advisory only; no autonomous generation, transmission, or load control |
What This Project Demonstrates
A production-minded AI portfolio project spanning time-series forecasting, data engineering, model governance, RAG, multi-agent orchestration, APIs, persistence, and human-centered decision support.
Adaptable Data Architecture
Switches between synthetic, historical Kaggle, and recent EIA data while preserving the same downstream feature, forecasting, and decision workflow.
Engines and Agents
Offers three selectable decision engines and, when enabled for a hosted provider, a transparent three-role debate committee with a visible transcript.
Human-Controlled Decisions
Recommendations never execute automatically. Approval, rejection, escalation, rationale, evidence, model version, and source provenance are retained for audit.
Responsible-AI Boundary
GridGuard is an operational analytics demonstration. It does not autonomously control generation, transmission, customer load, or other critical infrastructure. Forecasts, LLM briefings, and agent debate are decision-support evidence for qualified human review.