ALLSHIFT/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository is

ALLSHIFT is Team SHIFT's single shared repository (TU/e student team; an AI-managed hospital hydrogen microgrid, Beth Israel Deaconess Boston as the case). It is public on Gitea (git.teamshiftenergy.com/pepe/ALLSHIFT). Four kinds of content live side by side:

• docs/ — the documentation hub. Every project document exists here as a markdown report; docs/README.md is the index and ends with the project-wide open-questions list. Retired material goes to superseded/ with a stated reason.
• Shift Matlab Drive/ — a mirror of the team's MATLAB Drive: Simulink models and raw data. The Simulink work belongs to the Simulations cluster (see docs/04-simulations/simulink-model-inventory.md; the live framework needs R2026a). No Python goes here.
• website/ — the public Astro site, with its own website/CLAUDE.md and pnpm commands. No Python goes here either.
• Root pyproject.toml + uv.lock — the one pinned Python environment for every cluster. Cluster code lives in top-level folders registered as uv workspace members; AICONTROL/ (AI & Control cluster) is the first.

Commands (from the repository root)

uv sync                                   # create/refresh .venv from uv.lock (Python 3.12; ~1.3 GB, torch included)
uv run pytest                             # all tests (pytest testpaths = AICONTROL/tests)
uv run pytest AICONTROL/tests/test_spaces.py::test_action_space_and_shedding_level   # one test
uv run python -m aicontrol.env.spaces     # print the current observation/action layout as a table
uv lock                                   # after editing dependencies; commit the updated uv.lock

Adding a dependency: edit dependencies in the root pyproject.toml, run uv lock, commit uv.lock. Adding a cluster folder: give it its own pyproject.toml (hatchling, packages = [...]), add the folder to [tool.uv.workspace] members, and add its package name to the root dependencies and to [tool.uv.sources] as { workspace = true }.

Website: cd website && pnpm dev | pnpm build | pnpm preview — details in website/CLAUDE.md.

Architecture

Clusters and the three handovers

The team leader's Project Manual (not in the repo) fixes four clusters and exactly three written handovers between them:

1. Energy Management → Simulations: the Parameter Book (a spreadsheet of every rating and efficiency, versioned) and the clean 5-minute BIDMC dataset with Tier 1 / 2 / 3 load assigned, as Parquet.
2. Simulations → AI: a Gymnasium environment. Simulations owns everything inside step() — the twin's physics, the KPI calculator, and the benchmark controllers (rule-based, MPC on forecasts, perfect knowledge; Pyomo + HiGHS). AI owns everything outside it: the agent, the safety layer, evaluation, dashboard. Written jointly early in Q2, frozen before Christmas.
3. AI → Business: one results file, one row per controller × scenario × run, Parquet with a CSV beside it.

Fixed by the manual, not up for local decision: 5-minute timestep (105,120 steps per year); a full simulated year must run in under a minute; Boston with ISO New England prices and carbon; Tier 1 load is never shed; reward weights are agreed across clusters and never tuned by code.

AICONTROL/ — the AI & Control cluster package

• Everything is built from AICONTROL/configs/env.yaml, so the joint session with Simulations can change a number without touching code. Values marked PLACEHOLDER there (plant sizes, load bound, reward weights) are stand-ins owned by other clusters; keep the marker until the owning cluster confirms a value.
• aicontrol/env/spaces.py is the single source of the interface shape. observation_slots(cfg) defines the flat 64-value observation in order (calendar 4, present-state 12, forecasts = quantities × horizons × quantiles = 48); build_action_space gives a Box(4): u_ele [0, 1], u_fc [0, 1], u_batt [−1, 1] with positive = discharge, shed [0, 2] rounded by shedding_level() because Stable-Baselines3 cannot mix continuous and discrete actions. Names follow the Simulator I/O sheet (P_PV, SoC, H2_level, p_tank, price, CO2_int, grid_on).
• AICONTROL/docs/interface-draft.md is the handover document; keep its tables in step with spaces.py (regenerate the observation table with describe()).
• The placeholder environment (next: aicontrol/env/placeholder.py) exposes exactly these spaces with toy physics. It never gets better physics and is deleted the day the twin runs. Do not build a competing simulator in this folder.
• Planned subpackages: forecast/, train/, evaluate/, safety/, dashboard/. Tooling is fixed by the manual: LightGBM / scikit-learn / Optuna for forecasting, Gymnasium + Stable-Baselines3 for RL, Weights & Biases for logging (not MLflow), SHAP + Streamlit.

Documentation conventions

• A markdown report of a non-markdown source opens with a provenance table (Source, Format, MD5, Status, Report generated). Reconstructed tables are labelled as such; observations that go beyond the source are attributed to the audit, not the author.
• docs/02-specifications/ is owned by the AI cluster. The RL state / action / reward documents there are superseded by the manual's interface list but kept for the rationale behind individual terms.
• docs/01-project/ai-control-cluster-plan-2026-2027.md is the AI cluster's plan: seats, Q1 week by week, later blocks, open items for the leader.

Data: what actually exists

Under Shift Matlab Drive/Shift Matlab Drive/Energy_Managment/: hospital load is the NREL ComStock building 89993-0.parquet (2018, 15-minute, simulated; MA_hourly_load.csv is a mis-named numerical twin of it). Weather is NSRDB 2019, hourly, timestamps in UTC. PV is a PVWatts 4 kW typical-year run that aligns with neither. There is no price, carbon-intensity, outage or measured-load series. hospital_communication_energy_system.csv is synthetic noise; derive nothing from it. Provenance and licences: docs/06-data/dataset-inventory.md.

Things to know

• Formats: machine-made tables are Parquet, hand-written settings are YAML, documents are Markdown.
• .venv/, wandb/ run folders and **/data/raw/ are gitignored; uv sync rebuilds the environment from uv.lock on any machine.
• website/CLAUDE.md embeds live third-party keys that are due for rotation; do not copy them anywhere.
• Interview Questions-*.md at the root is personal recruitment data, gitignored on purpose.