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