README.md

---
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

```python
# 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.