ALLSHIFT/AICONTROL/docs/interface-draft.md

The Simulations → AI interface — draft for the November session

What this is	Our side of the handover the Project Manual calls "the environment interface": what the agent sees, what it controls, how it is scored. Written by the RL Environment seat; to be finished jointly with Simulations' Simulation Core Developer early in Q2 and frozen before Christmas
Where it lives in code	aicontrol/env/spaces.py builds the spaces from configs/env.yaml. Run uv run python -m aicontrol.env.spaces to print the current layout
Grown from	The manual's interface list (section 3.2) and our older Simulator I/O sheet, whose names we keep where they exist
Status	Draft, 11 Sep 2026. Everything marked to agree is open until the joint session

The idea in one paragraph

The agent and the simulated hospital talk through a Gymnasium environment: reset() starts a run, step(action) advances five minutes and returns what the agent may see next, plus a score. Simulations owns everything inside step (the physics, the KPIs); we own everything outside it (the agent, the safety layer, the evaluation). The two only have to agree on three lists, below. Until the twin exists, a placeholder environment with toy physics exposes exactly these lists so our side can be built now.

1. What the agent sees

One flat vector of 64 numbers per step, laid out from configs/env.yaml. The first sixteen are the present; the remaining 48 are the forecasts.

#	name	size	unit	range	source
0	time_of_day	2	sin, cos	−1 … 1	calendar
2	time_of_year	2	sin, cos	−1 … 1	calendar
4	P_PV	1	kW	0 … 460	twin: solar output now
5	L_tier1	1	kW	0 … 1000	data: critical load now
6	L_tier2	1	kW	0 … 1000	data: essential load now
7	L_tier3	1	kW	0 … 1000	data: non-critical load now
8	SoC	1	fraction 0–1	0 … 1	twin: battery state of charge
9	H2_level	1	kg	0 … 200	twin: hydrogen in the tank
10	p_tank	1	bar	0 … 30	twin: tank pressure
11	price	1	currency/kWh	−1 … 5	data: electricity price now
12	CO2_int	1	kg CO₂/kWh	0 … 1.5	data: grid carbon intensity now
13	grid_on	1	0/1	0 … 1	data: grid available
14	ele_on	1	0/1	0 … 1	twin: electrolyser running
15	fc_on	1	0/1	0 … 1	twin: fuel cell running
16–63	fcst_<quantity>_<horizon>min	3 each	kW	0 … max	forecaster: p10, p50, p90 for solar, tier1, tier2, tier3 at +60, +180, +360, +1440 min

Why sin and cos for time: a clock hand, not a number that jumps from 23:59 to 00:00. Why ranges: they scale the numbers for the network and let a test catch nonsense; they are not physical guarantees.

To agree with Simulations: which of these the twin reports directly (tank pressure or only kilograms; equipment state as on/off or as a mode); the forecast horizons and whether four are enough; the load upper bound once the dataset scale is known; the currency.

2. What the agent controls

Four floats per step.

name	range	meaning
u_ele	0 … 1	fraction of electrolyser rated power; 0 is off, anything below the minimum load becomes off
u_fc	0 … 1	fraction of fuel cell rated power
u_batt	−1 … 1	fraction of battery max power; positive discharges, negative charges
shed	0 … 2	rounded to a shedding level: 0 nothing, 1 Tier 3 shed, 2 Tiers 2 and 3 shed. Tier 1 is never an option

The grid is not an action: it absorbs whatever is left after the four above, within its connection limit. Load shedding is an action here, as the manual lists it, but the safety layer will refuse anything that would touch Tier 1.

To agree with Simulations: the shedding encoding (a continuous number rounded inside the environment is the simplest thing that works with Stable-Baselines3, which cannot mix continuous and discrete actions; the alternative is making all four discrete); whether the twin wants setpoints in kW or in fractions; ramp limits applied inside the twin or reported back as a clipped action.

3. How it is scored

The score per step is a weighted sum of the terms the manual lists. The terms are ours to propose; the weights are agreed with Energy Management and Business, because they say how much a euro, a kilo of CO₂ and a shed ward are worth relative to each other. The numbers in configs/env.yaml are placeholders so that code can run.

term	sign	what it measures
energy cost	−	money paid for grid electricity this step, minus money earned exporting
CO₂	−	grid electricity used × carbon intensity
Tier 1 unserved	− −	any critical load not supplied; must dominate every other term
Tier 2 / Tier 3 shed	−	non-critical load cut, priced far below Tier 1
limit violation	−	battery or tank pushed past a safe limit
switching	−	equipment turned on or off this step, to stop chattering

To agree: whether a clipped action (the twin refused part of it) counts as a violation or only as a reported difference; whether the perfect-knowledge benchmark and MPC are scored on exactly this sum, so the comparison is fair.

4. What the twin must return so we can compute all of the above

Per step: served load per tier, grid import and export, PV used and curtailed, battery power, electrolyser and fuel cell power, hydrogen produced and consumed, any limit clipping, and the KPI increments. The manual's four KPIs (Self-Sufficiency Rate, Grid Dependency Ratio, Critical Load Uptime, SoC Violation Rate) are computed by Simulations' KPI calculator; we read them, we do not recompute them.

5. What happens when the twin replaces the placeholder

Nothing on our side, if the three lists hold. The training rig, the evaluation pipeline, the safety wrapper and the dashboard all read the lists above, never the physics. That is the whole point of drafting this now.