|
| 1 | +# Smart Grid Data Provenance |
| 2 | + |
| 3 | +*Created: 2026-05-01* |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The Smart Grid 7th-domain MCP servers in this package operate over **synthetic |
| 8 | +data only**. No proprietary or course-restricted data is shipped with the AOB |
| 9 | +codebase. Runtime data location is configured via the `SG_DATA_DIR` |
| 10 | +environment variable. |
| 11 | + |
| 12 | +The source project for this port is |
| 13 | +[`HPML6998-S26-Team13/hpml-assetopsbench-smart-grid-mcp`](https://github.com/HPML6998-S26-Team13/hpml-assetopsbench-smart-grid-mcp). |
| 14 | + |
| 15 | +## What `SG_DATA_DIR` is |
| 16 | + |
| 17 | +`SG_DATA_DIR` is an environment variable pointing at the directory containing |
| 18 | +the synthetic Smart Grid CSV datasets the servers read at runtime. |
| 19 | + |
| 20 | +**Default path:** `./data/sg_processed/` relative to the current working |
| 21 | +directory (wherever the server process is launched from). |
| 22 | + |
| 23 | +Resolution order in [`src/servers/smart_grid/base.py`](../src/servers/smart_grid/base.py): |
| 24 | + |
| 25 | +1. `SG_DATA_DIR` environment variable — absolute or cwd-relative path. |
| 26 | +2. `./data/sg_processed/` relative to cwd (fallback if the variable is unset). |
| 27 | + |
| 28 | +The path is not required to exist at import time; existence is enforced on the |
| 29 | +first data-loading call, which raises a clear `FileNotFoundError` with |
| 30 | +remediation instructions if the path is missing. |
| 31 | + |
| 32 | +## What's in `SG_DATA_DIR` |
| 33 | + |
| 34 | +Six synthetic CSV files, one per logical data slice: |
| 35 | + |
| 36 | +| File | Server(s) | Description | |
| 37 | +|---|---|---| |
| 38 | +| `asset_metadata.csv` | IoT | Static nameplate data per transformer (`transformer_id`, `name`, `manufacturer`, `location`, `voltage_class`, `rating_kva`, `install_date`, `age_years`, `health_status`, `fdd_category`, `rul_days`, `in_service`) | |
| 39 | +| `sensor_readings.csv` | IoT, TSFM | Time-series sensor readings (load current, winding temp, oil temp, voltage) | |
| 40 | +| `failure_modes.csv` | FMSR | Failure mode catalogue with severity, IEC code, and recommended action | |
| 41 | +| `dga_records.csv` | FMSR | Dissolved Gas Analysis (DGA) records per transformer, per sample date | |
| 42 | +| `rul_labels.csv` | TSFM | Remaining-useful-life labels and health index per transformer | |
| 43 | +| `fault_records.csv` | WO | Historical fault and maintenance event records | |
| 44 | + |
| 45 | +All values are synthetic. Gas concentrations in `dga_records.csv` are derived |
| 46 | +from the source project's data pipeline; the IEC 60599:2022 Rogers Ratio |
| 47 | +fault-table boundaries used for DGA classification are encoded in that |
| 48 | +project's `data/knowledge/transformer_standards.json`. |
| 49 | + |
| 50 | +## No-CSV-port policy |
| 51 | + |
| 52 | +The source project's processed CSVs (under `data/processed/`) are **not** |
| 53 | +copied into AssetOpsBench. Reasons: |
| 54 | + |
| 55 | +1. **Licensing** — three of the five Kaggle source datasets are CC0; two |
| 56 | + (Transformer Health Index — ODbL, and Current & Voltage Monitoring — author |
| 57 | + copyright) have redistribution restrictions and are treated as local-only in |
| 58 | + the source pipeline. No processed outputs derived from restricted sources are |
| 59 | + ported to AOB, which avoids a licensing audit for upstream reviewers. |
| 60 | +2. **Reproducibility** — the synthetic data can be regenerated from |
| 61 | + `data/generate_synthetic.py` in the source project. Any downstream user with |
| 62 | + the generator and the IEC encoding can produce equivalent datasets without |
| 63 | + needing the source project's processed CSVs. |
| 64 | +3. **AOB cleanliness** — no course-internal preprocessing outputs in the package |
| 65 | + simplifies upstream review scope. |
| 66 | + |
| 67 | +**For a reviewer or downstream user needing Smart Grid data:** |
| 68 | + |
| 69 | +```bash |
| 70 | +git clone https://github.com/HPML6998-S26-Team13/hpml-assetopsbench-smart-grid-mcp.git |
| 71 | +cd hpml-assetopsbench-smart-grid-mcp |
| 72 | +pip install -r requirements.txt |
| 73 | +python data/generate_synthetic.py # produces data/processed/*.csv |
| 74 | +export SG_DATA_DIR=$(pwd)/data/processed |
| 75 | +``` |
| 76 | + |
| 77 | +## Scenario schema and identifiers |
| 78 | + |
| 79 | +`src/scenarios/local/smart_grid.json` follows the AOB local scenario array |
| 80 | +convention: each file is a JSON array and each record has an `id`, `type`, |
| 81 | +`text`, `category`, and `characteristic_form`. |
| 82 | + |
| 83 | +Smart Grid records also carry evaluator-facing metadata: |
| 84 | + |
| 85 | +| Field | Purpose | |
| 86 | +|---|---| |
| 87 | +| `asset_id` | Transformer identifier used by the scenario, when applicable. | |
| 88 | +| `difficulty` | Coarse difficulty label (`easy`, `medium`, or `hard`). | |
| 89 | +| `domain_tags` | Smart Grid domains exercised by the prompt. | |
| 90 | +| `expected_tools` | Intended tool path, using `iot.*`, `fmsr.*`, `tsfm.*`, and `wo.*` names. | |
| 91 | +| `ground_truth` | Lightweight grading hints such as required concepts, thresholds, or intermediate values. | |
| 92 | + |
| 93 | +These extended fields are advisory metadata for evaluators and are safe for |
| 94 | +scenario consumers to ignore if they only need the core AOB prompt fields. |
| 95 | + |
| 96 | +Identifier prefixes are intentional: |
| 97 | + |
| 98 | +- `AOB-FMSR-*` records are domain-level catalogue probes that do not depend on a |
| 99 | + specific synthetic transformer. |
| 100 | +- `SGT-*` records are transformer-grounded Smart Grid task scenarios. |
| 101 | +- `SG-NEG-*` records are negative fixtures used to test validation behavior, not |
| 102 | + main benchmark prompts. |
| 103 | + |
| 104 | +## Source datasets |
| 105 | + |
| 106 | +The source pipeline draws from five Kaggle datasets; licensing varies: |
| 107 | + |
| 108 | +| Dataset | License | Domain servers | |
| 109 | +|---|---|---| |
| 110 | +| Power Transformers FDD & RUL | CC0 | IoT, TSFM | |
| 111 | +| DGA Fault Classification | CC0 | FMSR | |
| 112 | +| Smart Grid Fault Records | CC0 | WO | |
| 113 | +| Transformer Health Index | ODbL (redistribution restricted; local-only) | FMSR (supplemental) | |
| 114 | +| Current & Voltage Monitoring | Author copyright (redistribution restricted; local-only) | IoT, TSFM (supplemental) | |
| 115 | + |
| 116 | +Dataset licensing details and row counts are documented in |
| 117 | +`docs/hpml_datasets.pdf` in the source project. |
| 118 | + |
| 119 | +## IEC / IEEE standards encoding |
| 120 | + |
| 121 | +DGA-related ground truth (fault codes, condition tiers, gas thresholds) is |
| 122 | +encoded in `data/knowledge/transformer_standards.json` in the source project. |
| 123 | +That artifact reflects: |
| 124 | + |
| 125 | +- **IEC 60599:2022** (4th ed., publication 66491) — Rogers Ratio method, |
| 126 | + fault-table boundaries, representative gas profiles |
| 127 | +- **IEEE C57.104-2019** — condition framework (C1–C4) and gas threshold values |
| 128 | + |
| 129 | +The FMSR server's `analyze_dga` tool implements the Rogers Ratio method |
| 130 | +using the fault-table boundaries from that artifact. Note: the AOB fork |
| 131 | +server encodes the table directly in `src/servers/smart_grid/fmsr/main.py` |
| 132 | +rather than reading the JSON at runtime. Downstream users regenerating DGA |
| 133 | +records should verify that generated gas values round-trip correctly through |
| 134 | +`analyze_dga` for their intended fault labels before using them as benchmark |
| 135 | +ground truth. |
| 136 | + |
| 137 | +## Citation |
| 138 | + |
| 139 | +SmartGridBench: A Smart Grid transformer maintenance benchmark for MCP-enabled |
| 140 | +LLM agents. Columbia University, 2026. |
| 141 | +*Citation will be updated when the NeurIPS 2026 Datasets & Benchmarks |
| 142 | +submission is finalized.* |
0 commit comments