ew-energy-models 0.2.0__tar.gz

ew_energy_models-0.2.0/.github/workflows/archive-forecast.yml

@@ -0,0 +1,38 @@
+name: archive-ieso-forecast
+
+# Builds the open IESO forecast archive. IESO keeps every forecast version for
+# only ~45 days, so this runs daily; each run back-fills anything still in
+# IESO's window, then fails (and GitHub emails you) if any date is missing.
+on:
+  schedule:
+    - cron: "17 14 * * *"   # ~09:17 EST
+    - cron: "47 21 * * *"   # ~16:47 EST, after the afternoon day-ahead revision
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: archive-forecast
+  cancel-in-progress: false
+
+jobs:
+  archive:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -e .
+      - name: Back-fill new forecast versions
+        run: python scripts/archive_ieso_forecast.py --skip-check
+      - name: Commit
+        run: |
+          git config user.name "ew-archive-bot"
+          git config user.email "actions@users.noreply.github.com"
+          git add data/ieso_forecast_archive.csv
+          git diff --cached --quiet || git commit -m "data: IESO forecast archive $(date -u +%FT%H:%MZ)"
+          git push
+      - name: Gap check (fails -> email alert)
+        run: python scripts/archive_ieso_forecast.py --check-only

ew_energy_models-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: publish-to-pypi
+
+# Publishes to PyPI when a GitHub Release is published. Uses PyPI Trusted
+# Publishing (OIDC): no API tokens or passwords are stored anywhere.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]" && pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Check tag matches package version
+        run: |
+          V=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          [ "v$V" = "${{ github.event.release.tag_name }}" ] || { echo "Tag ${{ github.event.release.tag_name }} != v$V"; exit 1; }
+      - run: pip install build && python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ew_energy_models-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,23 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

ew_energy_models-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+out/
+.DS_Store
+# never commit meter data
+*.xml
+data/private/

ew_energy_models-0.2.0/CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "ew-energy-models: open, auditable energy-analytics models"
+authors:
+  - family-names: Shah
+    given-names: Tirth
+    affiliation: Enerwyse
+version: 0.2.0
+date-released: 2026-10-22
+license: Apache-2.0
+repository-code: "https://github.com/enerwyse/ew-energy-models"
+url: "https://enerwyse.ca"
+keywords:
+  - energy analytics
+  - global adjustment
+  - industrial conservation initiative
+  - measurement and verification

ew_energy_models-0.2.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ew_energy_models-0.2.0/MAINTENANCE.md

@@ -0,0 +1,119 @@
+# Maintenance runbook
+
+Expected effort: **2 minutes a week, 15 minutes a month, about 2 hours each May.**
+The forecast archive runs and heals itself. Your job is to notice when it can't.
+
+All commands run from the repo folder with the virtual environment active:
+
+```bash
+cd ~/Desktop/"Tirth Private"/ew-energy-models
+source .venv/bin/activate
+git pull            # always first: the archive bot commits to main twice a day
+```
+
+---
+
+## One-time setup
+
+1. **Push the repo** to `github.com/enerwyse/ew-energy-models` (public).
+2. **Bot commit permission: nothing to change.** Keep the repo/org default at
+   *read-only* (safer). The archive workflow requests `contents: write` in its own
+   file, which is all it needs. Only if its **Commit** step fails with a 403: go to
+   **github.com/enerwyse → Settings → Actions → General → Workflow permissions →
+   "Read and write permissions" → Save** (org level; the repo option is greyed out
+   because the org setting caps it).
+3. **Turn on failure emails:** GitHub (your avatar) → **Settings → Notifications →
+   Actions → "Send notifications for failed workflows only"**, with email enabled.
+4. **First archive run:** repo → **Actions → archive-ieso-forecast → Run workflow**.
+   It should finish green and commit `data/ieso_forecast_archive.csv`.
+5. **Reserve the PyPI name** (5 min): create an account at pypi.org, then
+   `pip install build twine && python -m build && twine upload dist/*`.
+6. Add a calendar reminder: **first Monday of each month, "ew-models check"**, and
+   **May 15, "ICI season update"**.
+
+## Weekly (2 minutes)
+
+- Glance at your email for an `archive-ieso-forecast` failure. **No email = healthy.**
+- Optional: repo → Actions tab. Green ticks on recent runs = fine.
+
+## When a failure email arrives
+
+The failure tells you which step broke. Open the run in the **Actions** tab.
+
+| Failed step | Meaning | What to do |
+|---|---|---|
+| **Gap check** | Recent dates are missing a day-ahead forecast | Click **Re-run all jobs**. Missing dates are recoverable for about 40 days, so you have time, but don't leave it. |
+| **Back-fill** with an HTTP / timeout error | IESO site was down | Ignore it once. The next run heals it. If it fails for 3+ days, investigate. |
+| **Back-fill** with `no ForecastOntDemand/AverageDemand series found` or a parse error | **IESO changed its report format** | See "IESO changed a format" below. |
+| **Commit** with a permission error (403) | Org blocks workflow writes | Org-level fix in one-time setup step 2. |
+
+If anything fails for more than a week, open a Claude session in the Enerwyse
+project, paste the error, and ask for a fix.
+
+## Monthly (15 minutes, first Monday)
+
+1. `git pull`
+2. Check archive health:
+   ```bash
+   python scripts/archive_ieso_forecast.py --check-only
+   ```
+   You want `OK: ...`. "Known permanent gaps" are fine; IESO had already deleted those.
+3. Run the tests: `pytest -q`. All should pass. Warnings about deprecations are
+   a to-do, not an emergency.
+4. Check GitHub **Issues**. Reply to anything new within a week, even just
+   "thanks, looking at it."
+5. GitHub pauses scheduled workflows after 60 days with no repo activity. The bot's
+   commits normally prevent this. If the Actions tab shows a yellow "disabled"
+   banner, click **Enable workflow**.
+
+## Yearly: ICI season update (May 15–31)
+
+The base period closes April 30. IESO publishes the final ICI demand file in early May.
+
+1. `git pull`
+2. Run the full analysis:
+   ```bash
+   python examples/ontario_peak_atlas.py | tee out/run_output.txt
+   ```
+3. Check section 1: **Matching peak hours should be 25/25** (or 5 more each year).
+   If any mismatch appears, stop and investigate before publishing anything.
+4. Note the new season's peak date, threshold, crowding and window coverage.
+5. Once a full summer of the forecast archive exists (first time: May 2027), run the
+   benchmark on real IESO forecasts (ask Claude to wire it in).
+6. Release a version (below) and publish the "ICI season in review" post.
+7. Re-read IESO's ICI page and the Class A eligibility rules for changes
+   (thresholds, PPA offsets, base-period dates). Update `ontario/ici.py` caveats if needed.
+
+## Releasing a new version
+
+1. Update the version in **three places**: `pyproject.toml`, `src/ewmodels/__init__.py`,
+   `CITATION.cff` (plus `date-released`).
+2. `pytest -q` must pass.
+3. Commit, then tag:
+   ```bash
+   git commit -am "vX.Y.Z: <what changed>"
+   git tag vX.Y.Z && git push && git push --tags
+   ```
+4. Publish: `rm -rf dist && python -m build && twine upload dist/*`
+5. GitHub → **Releases → Draft a new release** from the tag, with 3–5 lines on what's new.
+
+## IESO changed a format
+
+Signs: parse errors, missing columns, or the workflow failing every run.
+
+1. Look at a current file in the browser:
+   `https://reports-public.ieso.ca/public/Adequacy3/` or `.../Demand/`
+2. For forecasts, run `python -m ewmodels.data.ieso_forecast --inspect` and see
+   which series it finds.
+3. Ask Claude with the error and the inspect output. Fix, add a test, release.
+4. **Time matters for the forecast archive:** versions disappear after about 45 days.
+
+## Rules that never change
+
+- **No customer data in this repo, ever.** That covers meter data, Green Button
+  files, and anything from the Enerwyse platform, anonymized or not. `.gitignore`
+  blocks XML, but the rule is yours to keep.
+- Every new model returns a `Result` with a receipt: checks plus caveats.
+- Every change comes with a test. Tests must pass before pushing.
+- Charts use fixed axes (never let autoscale exaggerate a small difference).
+- Anything published publicly gets verified against an official source first.

ew_energy_models-0.2.0/NOTICE

@@ -0,0 +1,8 @@
+ew-energy-models
+Copyright 2026 Enerwyse
+
+This product includes software developed by Enerwyse (https://enerwyse.ca).
+
+Data accessed by this software at runtime from the Independent Electricity
+System Operator (IESO) public reports site is the property of the IESO and is
+not redistributed with this package.

ew_energy_models-0.2.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: ew-energy-models
+Version: 0.2.0
+Summary: Open, auditable energy-analytics models from Enerwyse: load analytics, M&V baselines, and Ontario Global Adjustment / ICI peak tools. Every result ships with an evidence receipt.
+Project-URL: Homepage, https://enerwyse.ca
+Project-URL: Source, https://github.com/enerwyse/ew-energy-models
+Author-email: Enerwyse <tirth.shah@enerwyse.ca>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ashrae-guideline-14,emis,energy,global-adjustment,ici,ieso,measurement-and-verification,ontario
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# ew-energy-models
+
+**Open, auditable energy-analytics models from [Enerwyse](https://enerwyse.ca).**
+
+`ewmodels` is a small Python library of energy models for commercial and
+industrial facilities. It covers load analytics, M&V baselines, and Ontario
+Global Adjustment / Industrial Conservation Initiative (ICI) peak tools.
+
+Every model returns a result **and an evidence receipt**. The receipt records:
+
+- the input data hash
+- the detected interval resolution
+- data-sufficiency checks, each pass/fail
+- the simplifying assumptions the result relies on
+- the code version that produced it
+
+A number without its receipt is not a result.
+
+```python
+from ewmodels.data.ieso import fetch_demand
+from ewmodels.ontario import atlas, ici
+
+demand = fetch_demand(range(2022, 2027))["ontario_demand_mw"]
+res = atlas.peak_atlas(demand)
+
+print(res.value["summary"])        # per base period: 5th-peak threshold, crowding
+print(res.receipt.summary())       # what this number rests on
+```
+
+## Why this exists
+
+Energy analytics usually comes as a black box: a vendor's number on a
+dashboard. Facility managers, M&V reviewers and incentive programs then have to
+take it on trust. We think the math should be open and every figure should be
+checkable. The value a platform adds is applying the math reliably to real
+operations, not hiding it.
+
+## What's in v0.2: Ontario ICI toolkit
+
+| Module | What it does |
+|---|---|
+| `ewmodels.data.ieso` | Downloads and parses IESO hourly Ontario demand and the **ICI Demand** reports. Converts hour-ending EST to interval-start timestamps. Caches locally. |
+| `ewmodels.data.ieso_forecast` | Parses IESO's Ontario demand forecasts (Adequacy3) and keeps an **open forecast archive** |
+| `ewmodels.ontario.ici` | Base periods, top-5 peak hours, **Peak Demand Factor** from interval meter data, GA charge, an optional **clean-energy PPA offset**, and curtailment-savings simulation |
+| `ewmodels.ontario.atlas` | **Ontario Peak Atlas**: per-season thresholds, peak timing, and *crowding*, i.e. how many days came within 1–5% of the 5th peak |
+| `ewmodels.ontario.benchmark` | **Open 5CP benchmark**: replays history day by day with no look-ahead and scores any peak-calling strategy on *peaks captured vs. days curtailed*. Supports synthetic or real forecasts, hour-level scoring with a curtailment window, window-length analysis, and a **growth-removed stress test** |
+
+### The open 5CP benchmark
+
+Accuracy scores don't capture what a Class A customer actually trades off. A
+strategy that calls every hot weekday catches every peak and disrupts
+operations all summer. One that calls three days may miss the peak that
+mattered. The benchmark gives a strategy only what was knowable before each
+day, then scores it in operational terms:
+
+```python
+from ewmodels.ontario import benchmark
+
+result = benchmark.evaluate(demand, benchmark.threshold_strategy(margin=0.03),
+                            forecast_error_pct=2.0)
+print(result.value)   # per base period: days_called, peak_hours_captured, capture_rate
+```
+
+Any function `DayContext -> bool` is a strategy, so you can plug in your own
+forecaster and compare it on the same terms.
+
+**Two honesty guards are built in:**
+
+- **Stress test.** Ontario's peak has grown every recent season, which flatters any
+  rule anchored on last year's peaks. `normalize_seasons()` removes that growth, so
+  a strategy has to work in a flat year too.
+- **Real windows.** All five peak hours usually fall on one afternoon, as
+  consecutive hours. `window=(start, hours)` scores what a fixed curtailment window
+  actually catches, and `window_coverage()` shows how long the window has to be.
+
+### The open IESO forecast archive
+
+IESO keeps its Ontario demand forecasts for only about 90 days, so no public
+record exists of what was forecast against what happened. This repo builds one:
+a scheduled workflow snapshots IESO's forecasts twice a day into
+`data/ieso_forecast_archive.csv`. Once a full ICI season is archived, the
+benchmark can score strategies on the forecasts operators actually saw.
+
+## Design principles
+
+1. **Receipts, not just results.** Checks fail loudly: for example, a missing meter
+   reading during a peak hour makes the PDF receipt invalid, rather than
+   silently computing a wrong PDF.
+2. **Resolution is data, not configuration.** Utility interval data arrives at
+   5, 15 or 60 minutes. Models detect the resolution and never assume it.
+3. **Deterministic and reproducible.** The same inputs always give the same
+   outputs, and randomness is seeded.
+4. **No customer data, ever.** The library ships no meter data. Examples use
+   public sources only (IESO, Environment Canada, open building datasets).
+
+## Roadmap
+
+The library will grow to cover the Enerwyse models catalogue:
+
+- **v0.3 Load kernels:** load-profile decomposition, peak ranking, load factor
+- **v0.4 M&V:** ASHRAE Guideline 14 change-point baselines (3P/4P/5P), weather
+  normalization, CUSUM tracking, with CV(RMSE)/NMBE validity in the receipt
+- **Later:** day-ahead load forecasting, load-shifting optimization, and
+  carbon-intensity scheduling
+
+## Install
+
+```bash
+pip install ew-energy-models            # once published
+# or from source
+pip install -e ".[dev]" && pytest
+```
+
+## Important
+
+This is an analysis tool, not a settlement engine. Peak hours reproduced from
+public demand data are provisional until the IESO publishes the official ones.
+PDFs computed with Ontario Demand as the denominator are estimates. Your LDC or
+IESO invoice is authoritative. Nothing here is financial or regulatory advice.
+
+## Maintenance
+
+See [MAINTENANCE.md](MAINTENANCE.md) for the runbook: weekly checks, alerts, yearly updates, releases.
+
+## License & citation
+
+Apache-2.0. If you use this in research, please cite it (see `CITATION.cff`).
+IESO data © Independent Electricity System Operator. It is fetched at runtime,
+not redistributed.