README.md

---
title: Appliance Health & Leakage Monitor
emoji: ⚡
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
---

# ⚡ Appliance Health & Leakage Monitor

A live monitoring dashboard built on the **AMPds2** household power dataset. It plays back the
records hour-by-hour, builds a per-appliance **expected band with TimesFM 2.5**, and raises
dashboard alerts for two independent problems:

1. **Appliance health** — an appliance drawing **more** (wear / fault) or **less** (under-draw / off)
   than its healthy rated power.
2. **Whole-house leakage** — the gap between the metered mains and the sum of all appliances
   (unaccounted load).

You can **inject faults** into any appliance (over-draw / under-draw / off) and **inject house
leakage**, then watch the dashboard respond in real time.

## Files

| File | Purpose |
|------|---------|
| `app.py` | Gradio dashboard (playback, injection controls, charts, alerts) |
| `engine.py` | Simulation + detection logic, TimesFM envelope builder |
| `prepare_data.py` | One-time: AMPds2 zip → `data/ampds2_hourly.parquet` |
| `requirements.txt` | Pinned dependencies |

## Quick start

**1. Get the data.** Download AMPds2 (`dataverse_files.zip`) from
[Harvard Dataverse](https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/FIE0S4).

**2. Build the compact parquet** the app reads (resamples the minutely data to hourly):
```bash
python prepare_data.py /path/to/dataverse_files.zip
# -> writes data/ampds2_hourly.parquet
```

**3. Run locally:**
```bash
pip install -r requirements.txt
python app.py
```

## Deploy to Hugging Face Spaces

1. Create a new **Gradio** Space.
2. Push `app.py`, `engine.py`, `prepare_data.py`, `requirements.txt`, `README.md`.
3. Add the data: commit `data/ampds2_hourly.parquet` (it's small after hourly resampling), or upload
   it via the Space's **Files** tab. (Run `prepare_data.py` locally first to create it.)
4. The Space builds from `requirements.txt`. **TimesFM 2.5** installs from GitHub and its weights
   download on first launch.

**Hardware:** runs on the free **CPU** tier — first launch takes ~1–2 min while TimesFM loads and
forecasts the expected bands. A **T4 GPU** makes initialization noticeably faster. If `timesfm`
can't be imported, the app automatically falls back to a seasonal (hour-of-day) expected band so it
still works.

## How to use

1. Set the **playback window** and **healthy context** lengths, click **Initialize**
   (the context window trains the baselines and TimesFM bands).
2. **▶ Play** (or **Step**) to stream the records; **Speed** sets hours per tick.
3. **Inject an appliance fault**: pick an appliance, choose Over-draw / Under-draw / Off, set the
   magnitude and when in the timeline it begins, then **Apply**.
4. **Inject leakage**: set a continuous phantom load (W) and a start point, then **Apply**.
5. Watch the **Alerts & status** panel and the two charts react.

## How detection works

- **Expected band** is forecast once by **TimesFM 2.5** from the healthy context window, per
  appliance (shown as the q10–q90 ribbon on the focus chart).
- **Over / under / off** fire when an appliance's trailing **ON-power** deviates from its healthy
  **rated** value — robust to normal on/off cycling. (The forecast band is the visual evidence; the
  rated comparison is the trigger, which avoids false alarms on sharp on/off loads.)
- **Leakage** = `mains − Σ(appliances)`, compared to the normal hour-of-day residual band.
  Importantly, an appliance fault raises the mains by the same amount, so it does **not** move the
  residual — only a true leak does. That keeps the two alert types independent and physically
  consistent.
- AMPds2 has no real fault/leak labels, so the system is validated by **injection** — exactly what
  the controls let you do.

## Notes

- Power is in **watts**; hourly energy in kWh = W / 1000.
- The mains meter is `WHE`; `UNE` (unmetered) is excluded from the appliance sum.
- TimesFM is used **zero-shot** (pretrained, no training on AMPds2).