watt-the-hack 0.2.0__tar.gz

watt_the_hack-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepNeuron / Watt The Hack contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

watt_the_hack-0.2.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: watt-the-hack
+Version: 0.2.0
+Summary: Watt The Hack 24-hour energy grid simulation hackathon engine
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Provides-Extra: api
+Requires-Dist: fastapi; extra == "api"
+Requires-Dist: uvicorn; extra == "api"
+Requires-Dist: python-dotenv; extra == "api"
+Provides-Extra: playtest
+Requires-Dist: matplotlib>=3.5; extra == "playtest"
+Requires-Dist: openai>=1.0; extra == "playtest"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# Watt The Hack Engine
+
+The simulation engine for the **Watt The Hack** energy grid hackathon (DeepNeuron).
+
+This is the public engine package — controllers, scenarios authoring, and the judging server live in private repos. Participants use this package to develop and test their controllers locally before submitting to the hackathon evaluation server.
+
+## How it works
+
+You write a **controller**. The engine runs a grid as a simulation in 15-minute steps (`duck_curve` = 96 steps over 24 h). At each step it hands your controller a snapshot of the grid and asks for an action:
+
+```
+every 15 minutes:
+
+   state  ──►  your controller  ──►  action  ──►  engine simulates  ──►  cost
+  (demand, solar,   step(state)      (battery,     physics + market
+   price, soc, …)                     diesel, …)
+
+   score  =  sum of cost over all 96 steps        (lower wins)
+```
+
+You see only the **current** step (plus a forecast in later scenarios) and return how much to charge/discharge the battery, run diesel, or curtail solar. The engine simulates that 15 minutes — clipping to physical limits, then applying the market — and charges you a cost. Your score is the total over every step.
+
+**One worked step — the duck curve at noon.** Solar is 80 MW, demand 30 MW: a 50 MW surplus. Do nothing and that surplus floods the grid past its 50 MW export cap → an **overvoltage penalty**. Instead, charge the battery (`battery_flow_mw = -20`): you bank cheap midday energy and release it into the 6 pm peak, when grid power is dear. *Store the midday glut, spend it at the evening peak* — that trade-off is the duck curve, and it's exactly what the starter below does. Every run also prints how your cost compares to a do-nothing and a best-known baseline, so you always know whether a change helped.
+
+## Quick start
+
+Three steps: install, write `strategy.py`, run `python strategy.py`.
+
+> **⚠️ Make a virtual environment first.** Installing into your system Python (or conda base) can clash with other tools; a venv isolates it and you can delete it with `rm -rf .venv` if anything goes wrong. **Colab users:** skip the venv — run the `pip install` line in a cell, or just [open the starter notebook](https://colab.research.google.com/github/AaronEliasZachariah/Watt-The-Hack-Engine-Public/blob/main/notebooks/training_starter.ipynb).
+
+**1. Create a venv and install the engine.** The `[playtest]` extra adds plots and the agentic-track OpenAI client.
+
+macOS / Linux:
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install "watt_the_hack[playtest] @ git+https://github.com/AaronEliasZachariah/Watt-The-Hack-Engine-Public.git@main"
+```
+
+Windows (PowerShell):
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install "watt_the_hack[playtest] @ git+https://github.com/AaronEliasZachariah/Watt-The-Hack-Engine-Public.git@main"
+```
+
+Your prompt should now start with `(.venv)`. (`python -m pip` — not bare `pip` — guarantees you install into the active venv on every OS.)
+
+**2. Create `strategy.py`.** Your controller *and* its local test live in one file:
+
+```python
+# strategy.py — edit the controller, then run:  python strategy.py
+def controller(state):
+    # Duck curve 101: bank the midday solar surplus, spend it at the evening peak.
+    demand, solar, soc = state["demand"], state["solar"], state["soc"]
+    surplus = solar - demand                      # +ve = excess solar right now
+    flow = 0.0
+    if surplus > 5 and soc < 0.9:                 # midday: store the excess
+        flow = -min(20.0, surplus)                # negative = charge
+    elif surplus < 0 and soc > 0.2:               # evening: cover the shortfall
+        flow = min(20.0, -surplus)                # positive = discharge
+    net = demand - solar - flow                   # what's left for the grid
+    curtail = max(0.0, -net - 50.0)               # dump unstorable export
+    return {"battery_flow_mw": flow, "curtail_solar": curtail}
+
+
+# --- Local playtest. Runs on `python strategy.py`; the judge ignores this block. ---
+if __name__ == "__main__":
+    from watt_the_hack.playtest import run_playtest
+    result = run_playtest(__file__, "duck_curve", plots=True, open_report=True)
+    print(f"\nRaw cost (lower wins): ${result['metrics']['final_score']:,.2f}")
+```
+
+**3. Run it:**
+
+```bash
+python strategy.py
+```
+
+It prints your cost breakdown and opens an HTML report (plots, worst timesteps, diagnostics). In an IDE (VS Code, PyCharm) this is just the ▶ Run button — no command line at all. Edit the controller, re-run, repeat.
+
+`result["metrics"]["final_score"]` is your **raw cost in dollars — lower wins.** The 0–150 leaderboard points are computed server-side on the hidden judging variants; locally you minimise the raw cost.
+
+### Scenarios you can run offline
+
+The wheel bundles two: `duck_curve` (rule-based track) and `agentic_demo` (LLM / `plan`-`replan` track). List them any time:
+
+```bash
+python -m watt_the_hack.playtest --list-scenarios
+```
+```text
+duck_curve    synthetic  The Duck Curve
+agentic_demo  synthetic  Agentic Demo — Your First LLM Controller
+```
+
+Switch scenario by changing the id in `run_playtest(__file__, "duck_curve", ...)`. The scored judging variants stay on the server — a green local run translates directly to a submission.
+
+### Updating as new scenarios drop
+
+Scenarios are released incrementally. Update inside the same venv:
+
+```bash
+python -m pip install --upgrade --force-reinstall "watt_the_hack[playtest] @ git+https://github.com/AaronEliasZachariah/Watt-The-Hack-Engine-Public.git@main"
+```
+
+### Power user: the CLI
+
+`run_playtest` is the easy path. The CLI runs the same harness without editing the file, and adds a **sweep** — compare several controllers on one scenario, ranked side by side:
+
+```bash
+python -m watt_the_hack.playtest strategy.py --scenario duck_curve --open-report
+python -m watt_the_hack.playtest a.py b.py c.py --scenario duck_curve
+```
+
+## What's in here
+
+- `watt_the_hack/engine/` — physics + market step
+- `watt_the_hack/metrics/` — scoring metrics
+- `watt_the_hack/simulation/` — runner glue
+- `watt_the_hack/controllers/` — reference controllers (rule-based, parametric)
+- `watt_the_hack/data_loaders/` — scenario loading utilities
+
+## License
+
+MIT

watt_the_hack-0.2.0/README.md

@@ -0,0 +1,125 @@
+# Watt The Hack Engine
+
+The simulation engine for the **Watt The Hack** energy grid hackathon (DeepNeuron).
+
+This is the public engine package — controllers, scenarios authoring, and the judging server live in private repos. Participants use this package to develop and test their controllers locally before submitting to the hackathon evaluation server.
+
+## How it works
+
+You write a **controller**. The engine runs a grid as a simulation in 15-minute steps (`duck_curve` = 96 steps over 24 h). At each step it hands your controller a snapshot of the grid and asks for an action:
+
+```
+every 15 minutes:
+
+   state  ──►  your controller  ──►  action  ──►  engine simulates  ──►  cost
+  (demand, solar,   step(state)      (battery,     physics + market
+   price, soc, …)                     diesel, …)
+
+   score  =  sum of cost over all 96 steps        (lower wins)
+```
+
+You see only the **current** step (plus a forecast in later scenarios) and return how much to charge/discharge the battery, run diesel, or curtail solar. The engine simulates that 15 minutes — clipping to physical limits, then applying the market — and charges you a cost. Your score is the total over every step.
+
+**One worked step — the duck curve at noon.** Solar is 80 MW, demand 30 MW: a 50 MW surplus. Do nothing and that surplus floods the grid past its 50 MW export cap → an **overvoltage penalty**. Instead, charge the battery (`battery_flow_mw = -20`): you bank cheap midday energy and release it into the 6 pm peak, when grid power is dear. *Store the midday glut, spend it at the evening peak* — that trade-off is the duck curve, and it's exactly what the starter below does. Every run also prints how your cost compares to a do-nothing and a best-known baseline, so you always know whether a change helped.
+
+## Quick start
+
+Three steps: install, write `strategy.py`, run `python strategy.py`.
+
+> **⚠️ Make a virtual environment first.** Installing into your system Python (or conda base) can clash with other tools; a venv isolates it and you can delete it with `rm -rf .venv` if anything goes wrong. **Colab users:** skip the venv — run the `pip install` line in a cell, or just [open the starter notebook](https://colab.research.google.com/github/AaronEliasZachariah/Watt-The-Hack-Engine-Public/blob/main/notebooks/training_starter.ipynb).
+
+**1. Create a venv and install the engine.** The `[playtest]` extra adds plots and the agentic-track OpenAI client.
+
+macOS / Linux:
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install "watt_the_hack[playtest] @ git+https://github.com/AaronEliasZachariah/Watt-The-Hack-Engine-Public.git@main"
+```
+
+Windows (PowerShell):
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install "watt_the_hack[playtest] @ git+https://github.com/AaronEliasZachariah/Watt-The-Hack-Engine-Public.git@main"
+```
+
+Your prompt should now start with `(.venv)`. (`python -m pip` — not bare `pip` — guarantees you install into the active venv on every OS.)
+
+**2. Create `strategy.py`.** Your controller *and* its local test live in one file:
+
+```python
+# strategy.py — edit the controller, then run:  python strategy.py
+def controller(state):
+    # Duck curve 101: bank the midday solar surplus, spend it at the evening peak.
+    demand, solar, soc = state["demand"], state["solar"], state["soc"]
+    surplus = solar - demand                      # +ve = excess solar right now
+    flow = 0.0
+    if surplus > 5 and soc < 0.9:                 # midday: store the excess
+        flow = -min(20.0, surplus)                # negative = charge
+    elif surplus < 0 and soc > 0.2:               # evening: cover the shortfall
+        flow = min(20.0, -surplus)                # positive = discharge
+    net = demand - solar - flow                   # what's left for the grid
+    curtail = max(0.0, -net - 50.0)               # dump unstorable export
+    return {"battery_flow_mw": flow, "curtail_solar": curtail}
+
+
+# --- Local playtest. Runs on `python strategy.py`; the judge ignores this block. ---
+if __name__ == "__main__":
+    from watt_the_hack.playtest import run_playtest
+    result = run_playtest(__file__, "duck_curve", plots=True, open_report=True)
+    print(f"\nRaw cost (lower wins): ${result['metrics']['final_score']:,.2f}")
+```
+
+**3. Run it:**
+
+```bash
+python strategy.py
+```
+
+It prints your cost breakdown and opens an HTML report (plots, worst timesteps, diagnostics). In an IDE (VS Code, PyCharm) this is just the ▶ Run button — no command line at all. Edit the controller, re-run, repeat.
+
+`result["metrics"]["final_score"]` is your **raw cost in dollars — lower wins.** The 0–150 leaderboard points are computed server-side on the hidden judging variants; locally you minimise the raw cost.
+
+### Scenarios you can run offline
+
+The wheel bundles two: `duck_curve` (rule-based track) and `agentic_demo` (LLM / `plan`-`replan` track). List them any time:
+
+```bash
+python -m watt_the_hack.playtest --list-scenarios
+```
+```text
+duck_curve    synthetic  The Duck Curve
+agentic_demo  synthetic  Agentic Demo — Your First LLM Controller
+```
+
+Switch scenario by changing the id in `run_playtest(__file__, "duck_curve", ...)`. The scored judging variants stay on the server — a green local run translates directly to a submission.
+
+### Updating as new scenarios drop
+
+Scenarios are released incrementally. Update inside the same venv:
+
+```bash
+python -m pip install --upgrade --force-reinstall "watt_the_hack[playtest] @ git+https://github.com/AaronEliasZachariah/Watt-The-Hack-Engine-Public.git@main"
+```
+
+### Power user: the CLI
+
+`run_playtest` is the easy path. The CLI runs the same harness without editing the file, and adds a **sweep** — compare several controllers on one scenario, ranked side by side:
+
+```bash
+python -m watt_the_hack.playtest strategy.py --scenario duck_curve --open-report
+python -m watt_the_hack.playtest a.py b.py c.py --scenario duck_curve
+```
+
+## What's in here
+
+- `watt_the_hack/engine/` — physics + market step
+- `watt_the_hack/metrics/` — scoring metrics
+- `watt_the_hack/simulation/` — runner glue
+- `watt_the_hack/controllers/` — reference controllers (rule-based, parametric)
+- `watt_the_hack/data_loaders/` — scenario loading utilities
+
+## License
+
+MIT

watt_the_hack-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "watt-the-hack"
+version = "0.2.0"
+description = "Watt The Hack 24-hour energy grid simulation hackathon engine"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+api = [
+    "fastapi",
+    "uvicorn",
+    "python-dotenv",
+]
+playtest = [
+    "matplotlib>=3.5",
+    "openai>=1.0",
+]
+test = [
+    "pytest",
+    "pytest-cov",
+]
+
+[tool.setuptools.packages.find]
+include = ["watt_the_hack*"]
+
+# Ship scenario JSONs that live in-package. The public mirror keeps released
+# scenarios under watt_the_hack/scenarios/ for pip distribution. In this source
+# repo scenarios live top-level, so this glob matches nothing here — harmless.
+[tool.setuptools.package-data]
+watt_the_hack = ["scenarios/*/*.json"]
+
+[tool.pytest.ini_options]
+# Only collect the real test suite. Keeps bare `pytest` from scanning stray
+# scratch dirs (e.g. codex-pytest-tmp) that can trip collection on Windows.
+testpaths = ["tests"]

watt_the_hack-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+