# 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`](../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](https://docs.astral.sh/uv/) (one-off: `pip install uv`).

```bash
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.