LEAG-COALLOG/AGENTS.md

in Agents.md steht alles drin, was du brauchst# AGENTS.md

## Projektkontext

LEAG-COALLOG ist ein Proof of Concept zur Optimierung der Braunkohle-Logistik.
Das System verarbeitet eine Excel-Parameterdatei, erzeugt daraus normalisierte
Parquet-Tabellen und loest anschliessend ein Pyomo-Optimierungsmodell fuer
Lieferungen von Tagebauen zu Kraftwerken und Veredlung.

Ziel ist eine planbare Rohkohleverteilung unter Beruecksichtigung von Nachfrage,
Toleranzen, Mischungsverhaeltnissen, Foerder- und Verladungskapazitaeten,
Verfuegbarkeiten, Schichtmustern, Bunkerlogik und Solver-Limits. Die Webapp dient
als Bedienoberflaeche fuer Upload, Parametrisierung, Laufstatus, Logs,
Visualisierung und Ergebnisdownload.

## Architektur

Die Anwendung besteht aus drei Hauptteilen:

1. **Preprocessing**
   - Datei: `src/preprocessing/exploration_preprocess.py`
   - Liest die Excel-Datei aus `POC1_INPUT_XLSX`.
   - Schreibt vorbereitete Tabellen als Parquet nach `POC1_OUTPUT_DIR`.
   - Die Logik stammt aus einem Notebook-Export und ist stark an die Struktur der
     Eingabe-Excel gebunden.

2. **Optimierung**
   - Einstieg: `src/optimization/run_optimization.py`
   - Modell: `src/optimization/model_builder.py`
   - Laedt alle Parquet-Dateien aus einem Datenverzeichnis.
   - Baut ein Pyomo `ConcreteModel`.
   - Loest mit `highs`, `gurobi` oder `scip`.
   - Exportiert `output.xlsx` und optional `warmstart.json`.

3. **Webapp**
   - Backend: `webapp/backend/main.py`
   - Frontend: `webapp/frontend/src/App.jsx`
   - FastAPI nimmt Uploads entgegen, legt Job-Verzeichnisse unter `var/jobs` an
     und startet Preprocessing und Optimierung als Subprozesse.
   - React/Vite stellt Upload, Solver-Parameter, Job-Status, Logs, Plots,
     Warmstart und Downloads bereit.

## Datenfluss

Standardablauf eines Webapp-Laufs:

1. Browser sendet Excel-Datei, Solver und Parameter an `POST /api/run`.
2. FastAPI erstellt ein Job-Verzeichnis unter `var/jobs/<job_id>/`.
3. Die Upload-Datei wird als `input.xlsx` gespeichert.
4. `exploration_preprocess.py` schreibt `processed/*.parquet`.
5. `run_optimization.py` liest `processed/*.parquet`, baut und loest das Modell.
6. Ergebnisse landen in `output/output.xlsx` und `output/warmstart.json`.
7. Logs liegen unter `logs/preprocess.log` und `logs/optimization.log`.
8. Das Frontend pollt Status, Logs und abgeleitete Visualisierungsdaten.

Wichtige API-Endpunkte:

- `GET /api/health`
- `POST /api/run`
- `GET /api/jobs/{job_id}`
- `POST /api/jobs/{job_id}/cancel`
- `GET /api/jobs/{job_id}/output`
- `GET /api/jobs/{job_id}/warmstart`
- `GET /api/jobs/{job_id}/monthly-flows`
- `GET /api/jobs/{job_id}/capacity-timeseries`
- `GET /api/jobs/{job_id}/logs/{log_name}`
- `GET /api/jobs/{job_id}/logs/{log_name}/stream`

## Optimierungsmodell

Das Modell bildet Liefermengen als ganzzahlige Schritte ab:

- Quellen `I`: `Reichwalde`, `Nochten`, `Welzow`
- Ziele `J`: `J`, `SP`, `B3`, `B4`, `V`
- Tage `D`: Bergbauwoche Samstag bis Freitag
- Schichten `S`: `F`, `S`, `N`
- Entscheidung `k[i,j,w,d,s]`: ganzzahlige Anzahl Lieferschritte
- Fluss `x[i,j,w,d,s] = step_size_tonnes * k[i,j,w,d,s]`

Wichtige Nebenbedingungen und Konzepte:

- Tages-, Wochen- und Monatstoleranzen fuer Kraftwerke
- separate Veredlungsbedarfe fuer Nochten- und Welzower-Kohle
- harte Mix-Min/Max-Grenzen und weiche Zielabweichungen
- Foerderkapazitaeten pro Monat
- Verladungskapazitaeten pro Schicht und Tag
- Verfuegbarkeiten aus `Verfuegbarkeiten.parquet`
- feste Routenverbote und kombinierte Flussgrenzen
- Schichtglaettung und Schichtmuster
- optionale Bunkerlogik fuer Ziele mit Bunkerparametern
- Warmstart Import/Export fuer Folgelaeufe

Weitere fachliche Details stehen in:

- `README.md`
- `docs/app-kommunikation.md`
- `notebooks/constraints_overview.md`
- `latex/modellierung.tex`

## Wichtige Verzeichnisse

- `src/preprocessing/`: Excel-zu-Parquet-Datenaufbereitung
- `src/optimization/`: Pyomo-Modell, Solver-Lauf, Ergebnisexport
- `webapp/backend/`: FastAPI-App und Job-Orchestrierung
- `webapp/frontend/`: React/Vite-Frontend
- `data/input/`: lokale Eingabedateien
- `data/processed/`: lokale Preprocessing-Ausgaben
- `data/out/`: lokale Ergebnisartefakte
- `var/jobs/`: persistente Webapp-Jobdaten
- `docs/`: Architektur- und Kommunikationsdokumentation
- `notebooks/`: Analyse- und Modellnotizen
- `results/`: Solver-Debugartefakte wie `iis.ilp`

## Lokale Kommandos

Backend starten:

```bash
uv run python -m uvicorn webapp.backend.main:app --reload
```

Frontend starten:

```bash
cd webapp/frontend
npm install
npm run dev
```

Preprocessing direkt ausfuehren:

```bash
uv run python src/preprocessing/exploration_preprocess.py
```

Optimierung direkt ausfuehren:

```bash
uv run python src/optimization/run_optimization.py --data-dir data/processed --solver highs
```

Docker-All-in-One:

```bash
docker compose up --build
```

## Laufzeit und Solver

Unterstuetzte Solver sind aktuell `highs`, `gurobi` und `scip`, sofern lokal
installiert und fuer Pyomo verfuegbar. Im Docker-Image wird `gurobipy`
installiert. Fuer Gurobi wird entweder eine Lizenzdatei ueber
`GRB_LICENSE_FILE` oder WLS-Umgebungsvariablen verwendet:

- `GRB_LICENSE_FILE`
- `GRB_WLSACCESSID`
- `GRB_WLSSECRET`
- `GRB_LICENSEID`

Die Webapp prueft Solver-Verfuegbarkeit ueber `/api/health`.

## Entwicklungsregeln fuer Agenten

- Aendere keine Eingabe-, Ergebnis- oder Jobdaten ohne expliziten Grund.
- Behandle `var/jobs`, `data/out`, `data/processed` und `results` als erzeugte
  Artefakte, sofern die Aufgabe nicht genau diese Dateien betrifft.
- Respektiere bestehende fachliche Logik im Optimierungsmodell. Viele Grenzen
  sind hart kodiert und fachlich motiviert.
- Bei Aenderungen an `model_builder.py` immer pruefen, ob Export,
  Visualisierung und Warmstart noch konsistent sind.
- Bei Aenderungen am Excel-Output die Backend-Parser in `webapp/backend/main.py`
  mitdenken. Sie lesen konkrete Sheet- und Spaltenstrukturen.
- Bei Aenderungen an API-Antworten das Frontend in `webapp/frontend/src/App.jsx`
  synchron halten.
- Die Preprocessing-Datei ist notebookartig und teilweise redundant. Kleine,
  lokale Korrekturen sind besser als grosse Refactors ohne Tests.
- Keine Gurobi-Lizenzdateien, Credentials oder lokale Pfade committen.
- UI und Backend muessen auch ohne Gurobi sinnvoll starten koennen, wenn HiGHS
  verfuegbar ist.

## Validierung

Es gibt derzeit keine klar etablierte automatisierte Testsuite. Je nach Aenderung
sind diese Checks sinnvoll:

```bash
uv run python src/preprocessing/exploration_preprocess.py
uv run python src/optimization/run_optimization.py --data-dir data/processed --solver highs --time-limit 60
cd webapp/frontend && npm run build
```

Bei Backend- oder Webapp-Aenderungen zusaetzlich:

```bash
uv run python -m uvicorn webapp.backend.main:app --reload
```

Dann im Browser oder per API pruefen:

- `/api/health`
- Upload ueber Frontend
- Statuspolling
- Logs
- Download von `output.xlsx`
- Download von `warmstart.json`
- Plots fuer Monatsfluesse und Kapazitaetszeitreihen

## Bekannte Besonderheiten

- Die Bergbauwoche beginnt fachlich am Samstag. Im Modell wird dafuer ein
  Datum-plus-zwei-Tage-Shift zur ISO-Woche verwendet.
- Lieferabweichungen und Mischungsverhaeltnisse beziehen sich auf Lieferungen,
  nicht auf Bunkerabfluss.
- `no_three_in_a_row` ist laut README aktuell auf `<= 3` gelockert.
- Bei Infeasibility kann Gurobi ein IIS nach `results/iis.ilp` schreiben.
- Der Projektname in Metadaten und README ist teilweise noch `POC1`; fachlich
  entspricht das dem aktuellen LEAG-COALLOG-Prototyp.