ALLSHIFT/AICONTROL/README.md

AICONTROL — the AI & Control cluster's folder

Everything our cluster writes lives here: the placeholder environment, the forecasting harness, the training rig, the evaluation pipeline, the safety layer and the dashboard. The plan we work from is docs/01-project/ai-control-cluster-plan-2026-2027.md.

Clone and run

The whole team shares one Python environment, pinned at the repository root. You need Python 3.12 and uv (one-off: pip install uv).

git clone https://git.teamshiftenergy.com/pepe/ALLSHIFT.git
cd ALLSHIFT
uv sync          # first time: creates .venv/ with everyone's tools, a few minutes
uv run pytest    # runs our tests; all green means your setup works

uv sync reads uv.lock, so everyone gets exactly the same versions. Never commit .venv/. If you add a package, add it to the root pyproject.toml, run uv lock, and commit the updated uv.lock with your change.

What is where

AICONTROL/
├── aicontrol/            ← Python package (import aicontrol)
│   └── env/
│       └── spaces.py     ← what the agent sees and controls, built from configs/env.yaml
├── configs/
│   └── env.yaml          ← plant sizes, observation ranges, forecast layout, PLACEHOLDER reward weights
├── docs/
│   └── interface-draft.md← the Simulations → AI handover, drafted for the November session
├── tests/                ← pytest; run from the repository root with `uv run pytest`
└── README.md

Folders that will appear as the work does: env/placeholder.py (the placeholder environment), forecast/, train/, evaluate/, safety/, dashboard/.

Who does what

Person	Seats
Lead	RL Environment + Safety
Person 2	RL Training
Person 3	RL Evaluation + Explainability & Dashboard
Person 4	Forecasting

Q1 goal — what runs on Friday 16 October

1. The placeholder environment, with a determinism test and an energy test.
2. A training script (PPO or SAC on the placeholder, three seeds, logged to Weights & Biases).
3. The results pipeline: any controller × any scenario → one row; the comparison table; the column list for Business. Controller names reserved: rule_based, mpc, perfect_knowledge, agent.
4. The forecasting harness with "same as yesterday" baselines and a skill score.
5. The interface document, ready for the joint session with Simulations.

Rules we keep

• Never commit .venv/, Weights & Biases run folders, or raw data downloads (the .gitignore covers them).
• Machine-made tables are Parquet; hand-written settings are YAML; documents are Markdown.
• The placeholder environment never gets better physics. The day the twin runs, we point at it and delete the placeholder.