README.md

metadata

title: GridGuard AI
emoji: ⚡
colorFrom: yellow
colorTo: red
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
pinned: false

GridGuard AI

AI-powered revenue assurance & energy-theft detection for distribution utilities

A proof-of-concept built on fully synthetic data, demonstrating hierarchical non-technical-loss (NTL) detection: transformer-level energy balance → neighbourhood peer comparison → household behavioural anomaly detection → combined Fraud Risk Score for field-agent triage.

Built for: Session 2, "Circuit Breaker: From Student to Builder" — NIEEES Sensitization Seminar, University of Jos.

---

How it works (3-minute pitch)

1. Level 1 — Transformer energy balance. Compare energy injected into each transformer vs. the sum of metered readings from its households. A gap above the normal technical-loss range (~6-8%) signals theft somewhere on that feeder.
2. Level 2 — Neighbourhood peer comparison. Within a transformer, compare each household against peers of similar income class / house size in the same neighbourhood. Consumption far below peers is suspicious — but only in context.
3. Level 3 — Household behavioural anomaly. An Isolation Forest learns what "normal" consumption change looks like (drop ratio, trend slope, peer deviation) and scores every household for anomalousness, without needing fraud labels.
4. These three signals combine into a single Fraud Risk Score (0-100) and tier (Low/Medium/High) used to prioritise field inspections.

Why this isn't "just flag low consumption": the synthetic data deliberately includes genuinely low-consumption households (small, efficient families) and households with a real lifestyle change (fewer occupants) that look like a consumption drop but involve no theft. The model has to use peer and transformer context — not just an individual reading — to tell these apart. On held-out data: ~79% precision, ~94% recall for the supervised benchmark (trained on the synthetic ground-truth labels, for evaluation only) and 100% of true fraud cases land in Medium/High risk tier under the unsupervised approach (which is what you'd actually deploy, since real fraud labels are scarce).

Files

gridguard/
├── 01_data_generation.py     # synthetic households/readings/transformers
├── 02_train_model.py         # feature engineering + IsolationForest + XGBoost eval
├── app.py                    # Gradio demo (4 tabs)
├── requirements.txt
├── data/                      # generated CSVs (run script 1 then 2)
└── models/                    # saved model artifacts (run script 2)

Run in Colab

# Cell 1
!pip install -q xgboost gradio plotly

# Cell 2 — paste contents of 01_data_generation.py, run
# Cell 3 — paste contents of 02_train_model.py, run
# Cell 4 — paste contents of app.py, run
# demo.launch(share=True)   <- use share=True in Colab for a public demo link

Colab note: replace os.path.dirname(__file__) in each script with a fixed path (e.g. "/content/gridguard") if you paste cells individually rather than running the .py files directly, since __file__ isn't defined in a notebook cell. Easiest fix: at the top of the notebook run !mkdir -p /content/gridguard/data /content/gridguard/models and set BASE = "/content/gridguard" in each cell instead of using __file__.

Deploy to Hugging Face Spaces

1. Create a new Space → SDK: Gradio.
2. Upload app.py, requirements.txt, and the generated data/ and models/ folders (run the two scripts locally/Colab first, then upload the outputs — Spaces won't regenerate them automatically unless you also upload and run the generation scripts as part of a build step).
3. Space auto-builds and launches — same URL pattern as your other projects (huggingface.co/spaces/Samdutse/gridguard-ai).

Limitations to state up front in the talk (good for Q&A / academic credibility)

• All data is synthetic — real deployment needs real AMI/meter data, and the technical-loss baseline assumption (6-8%) should be calibrated per feeder, not assumed.
• The supervised XGBoost numbers use injected ground-truth labels that won't exist in production; the unsupervised + rules layers are the realistic deployment path, and their precision will be lower in practice.
• Flagging a household is the start of an inspection process, not proof of theft — false positives (genuine low consumers, lifestyle changes) are expected and the workflow should always end in human field verification before any legal action, exactly as in your original write-up.
• Real-world graph-based methods (treating the feeder as a graph, GNN anomaly detection) are a natural next step beyond this POC, and a good "future work" slide if asked about extending this for a thesis/PhD angle.