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:

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

Frontend starten:

cd webapp/frontend
npm install
npm run dev

Preprocessing direkt ausfuehren:

uv run python src/preprocessing/exploration_preprocess.py

Optimierung direkt ausfuehren:

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

Docker-All-in-One:

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:

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:

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.