# Bedienungsanleitung – Math Model Generator & Solver
Diese Anleitung beschreibt Schritt für Schritt, wie man das Programm installiert, eine Aufgabe lösen lässt, das Ergebnis liest und ohne erneute LLM-Kosten weiterarbeitet. Einen Überblick über Aufbau und Idee gibt die [README](README.md); die Abwägung hinter der Bauweise steht in [docs/Konzeptionelle_Fragen_und_Antworten.md](docs/Konzeptionelle_Fragen_und_Antworten.md).
## Inhalt
1. [Was das Programm tut](#1-was-das-programm-tut)
2. [Installation](#2-installation)
3. [Schnellstart](#3-schnellstart)
4. [Aufgaben gut formulieren](#4-aufgaben-gut-formulieren)
5. [Aufrufvarianten](#5-aufrufvarianten)
6. [Was das Programm ausgibt](#6-was-das-programm-ausgibt)
9. [Weiterarbeiten ohne neue LLM-Kosten](#9-weiterarbeiten-ohne-neue-llm-kosten)
10. [Kosten und Laufzeit steuern](#10-kosten-und-laufzeit-steuern)
11. [Alle Einstellungen im Überblick](#11-alle-einstellungen-im-überblick)
12. [Benchmark und Tests](#12-benchmark-und-tests)
13. [Fehlerbehebung](#13-fehlerbehebung)
14. [Sicherheit und Datenschutz](#14-sicherheit-und-datenschutz)
15. [Grenzen](#15-grenzen)
---
## 1. Was das Programm tut
Sie geben eine Optimierungsaufgabe in deutscher Sprache ein – etwa „Wie viele Tonnen von X und Y sollen gekauft werden, damit die Kosten minimal sind?“. Das Programm
1.**versteht** die Aufgabe: zerlegt sie in Teilfragen und erfasst jede Zahl des Textes,
3.**prüft** das Modell – teils ohne LLM, teils mit einer zweiten LLM-Prüfung – und **korrigiert** es,
4.**löst** es: ein LLM schreibt ein Python-Programm, das in einer abgeschotteten Umgebung mit einem echten Solver rechnet,
5.**nimmt das Ergebnis ab**: setzt die Lösung in alle Restriktionen ein, prüft die Antworten auf belegte Zahlen und Einheiten und kennzeichnet unzuverlässige Ergebnisse.
Sie erhalten einen **Report** (HTML oder Markdown) mit Antwort, Erklärung, Tabellen, Diagrammen, Modell und Prüfbericht, das **Ergebnis als JSON** und auf Wunsch das **Solver-Programm** als eigenständiges Python-Skript.
Unterstützt werden lineare, ganzzahlige, quadratische und nichtlineare Optimierung, Constraint Programming (Schicht- und Personalplanung) und kürzeste Wege. Die Tabelle der Problemklassen steht in der [README](README.md#unterstützte-problemklassen).
---
## 2. Installation
### Voraussetzungen
- **Linux** und **Python ≥ 3.10**
- **bubblewrap** für die Sandbox des erzeugten Codes:
```bash
sudo apt install bubblewrap
```
- für nichtlineare Aufgaben die **Ipopt-Bibliothek**, falls pip kein fertiges Paket für `cyipopt` findet:
```bash
sudo apt install coinor-libipopt-dev pkg-config
```
- ein **API-Schlüssel** für OpenRouter (Standard) oder Google Gemini
### Einrichten
Im Projektverzeichnis:
```bash
python -m venv .venv
.venv/bin/pip install -r requirements.txt
```
Alle Befehle dieser Anleitung rufen Python über `.venv/bin/python` auf; ein Aktivieren der Umgebung ist nicht nötig.
### API-Schlüssel setzen
Den Schlüssel **nur als Umgebungsvariable** setzen, nie in eine Datei im Projekt schreiben:
export GEMINI_API_KEY="…" # nur für Gemini-Modelle
```
Welcher Anbieter benutzt wird, entscheidet der Modellname: mit `/` (z. B. `deepseek/deepseek-v4.1-flash`) geht die Anfrage an OpenRouter, ohne `/` (z. B. `gemini-2.5-flash`) an Gemini. Damit der Schlüssel in jeder neuen Shell gesetzt ist, gehört die `export`-Zeile in `~/.bashrc` oder in einen Passwortmanager.
### Installation prüfen
```bash
.venv/bin/python -m pytest -q # alle Tests, offline, kostenlos
.venv/bin/python -m pytest -q -k sandbox # Sandbox: Schreiben außerhalb des Laufs muss scheitern
```
Beide Befehle müssen ohne Fehler durchlaufen. Die Tests brauchen keinen API-Schlüssel.
---
## 3. Schnellstart
Eine kleine Beispielaufgabe liegt bei. Lösen, Report und Programm speichern:
echo $? # 0 = Ergebnis zuverlässig (direkt danach abfragen)
```
Während des Laufs zeigt das Terminal den Fortschritt (Verstehen, Extraktion, Prüfung, Solver …) und am Ende Kosten und Laufzeit je Stufe. Die Aufgabe kostet etwa zwei Cent und dauert ein bis drei Minuten.
Danach:
```bash
xdg-open output/lp_klein.html # Report im Browser öffnen
.venv/bin/python output/lp_klein.py # Solver-Programm erneut ausführen, ohne LLM
Die Qualität des Ergebnisses hängt stark vom Aufgabentext ab. Bewährt hat sich:
| Empfehlung | Warum |
|---|---|
| **Alle Zahlen vollständig angeben**, am besten als Tabelle | Fehlende Werte muss das Programm annehmen; das wird zwar gekennzeichnet, macht das Ergebnis aber zur Schätzung. |
| **Einheiten ausdrücklich nennen** („in Tausend Euro“, „in Stunden“, „Rendite in %“) | Das Programm übernimmt Zahlen so, wie sie dastehen. „6,9“ ohne Einheit bleibt 6,9 – nicht 0,069. Antworten dürfen nur Einheiten nennen, die im Text stehen. |
| **Das Ziel eindeutig formulieren** („Kosten minimieren“, „Volatilität minimieren“) | Die Prüfstufe kontrolliert, ob die Zielfunktion genau die gefragte Größe liefert – z. B. Volatilität statt Varianz. |
| **Teilfragen markieren** (`a)`, `b)`, `Teil 2`) | Jede erkannte Teilfrage bekommt eine eigene Antwort. Fehlt eine, gilt die Aufgabe als nicht erfüllt. |
| **Bedingungen genau sagen**: „wenn A, dann B“ ist etwas anderes als „A genau dann, wenn B“ | Unklare Stellen werden als Annahme mit verworfener zweiter Lesart ausgewiesen – besser ist, wenn es keine gibt. |
| **Ganzzahligkeit nennen** („nur ganze Stück“, „Mengen beliebig teilbar“) | Entscheidet über Problemklasse und Solver. |
| **Externe Daten beilegen** statt auf Webquellen zu verweisen | Das Solver-Programm hat keinen Netzzugang. Verlangt die Aufgabe z. B. Kursdaten aus dem Internet, erzeugt es Ersatzdaten und kennzeichnet das. |
Die Aufgabe kann als `.txt` oder `.md` vorliegen; Markdown-Tabellen und Formeln wie `min z = 17*x1 + 23*x2` werden verstanden.
**Was abgelehnt wird:** Texte, in denen nichts zu entscheiden ist – etwa eine Gleichung, die nur ausgerechnet werden soll. Das Programm bricht dann nach der ersten Stufe ab (Exit-Code 3) und nennt im Report den Grund. Zulässigkeitsfragen („Ist dieser Plan überhaupt machbar?“) gelten dagegen als Aufgabe.
-`--report` braucht die Endung `.html`, `.htm` oder `.md`.
-`--code` ist mit `--no-solve` nicht möglich – es entsteht dann kein Programm.
- Das **Ergebnis-JSON geht auf die Standardausgabe**. Ohne `> datei.json` erscheint es im Terminal und ist danach für `--resolve` und `--von` nicht verfügbar. Es empfiehlt sich, es immer umzuleiten.
- Der Ordner `output/` ist von Git ausgeschlossen und eignet sich für alle Ergebnisse.
---
## 6. Was das Programm ausgibt
### Terminal (Standardfehlerausgabe)
Der Fortschritt jeder Stufe, Befunde der Prüfungen, Reparaturversuche und am Ende eine Übersicht:
```text
LLM-Nutzung: 5 Aufrufe, 36874 Input- (davon 12000 aus dem Cache, 33 %)/53898 Output-Tokens (davon 31152 Reasoning), Kosten $0.0738, Anbieter: {...}
- **HTML** (`--report datei.html`): im Browser öffnen. Formeln werden mit MathJax gesetzt – dafür braucht der Browser beim Öffnen Internet. Diagramme sind eingebettet und funktionieren offline, im hellen und dunklen Modus. Das Solver-Programm lässt sich per Kopier-Symbol übernehmen.
- **Markdown** (`--report datei.md`): z. B. in VS Code mit Strg+Umschalt+V als Vorschau; Formeln stehen als `$…$`.
Einen Report kann man auch **nachträglich** aus einem gespeicherten Ergebnis erzeugen – ohne LLM-Kosten, auch im anderen Format:
Ein eigenständiges, ausführbares Python-Skript: Docstring mit Aufgabe, Modell und Begründung des Verfahrens, alle Eingabewerte im Wörterbuch `DATA`, kommentierter Code, `main()`. Es gibt Status, Zielwert, Tabellen und Variablenwerte lesbar aus und endet mit einer maschinenlesbaren Zeile `RESULT_JSON: {...}`.
```bash
.venv/bin/python output/aufgabe.py
```
Man kann `DATA` im Skript von Hand ändern und neu rechnen – eleganter geht es mit `--resolve` (Abschnitt 9).
---
## 7. Das Ergebnis richtig lesen
Der Report beginnt mit dem Ergebnis und erklärt, bevor er Tabellen zeigt. Empfohlene Lesereihenfolge:
1.**Antwortsatz und Antworten auf die Aufgabe**– eine je Teilfrage. Jede Zahl darin stammt aus dem Ergebnis oder dem Aufgabentext.
2.**Status und Kennzahlen.**
3.**Warnkästen (⚠) – immer lesen.** „Ergebnis unzuverlässig – bitte nicht verwenden“ bedeutet genau das.
4.**„Wie das Modell die Aufgabe sieht“** – die Erklärung in Alltagssprache. Stimmt sie nicht mit Ihrer Absicht überein, ist das Modell falsch, auch wenn die Zahl plausibel aussieht.
5.**Ergebnistabellen und Diagramme**, bindende Restriktionen (welche Grenzen voll ausgeschöpft sind).
6.**Sensitivität**– was eine Lockerung einer Grenze bringen würde.
7. Weiter unten: **„Was in der Aufgabe steht“** (erkannte Teilfragen und Zahlen), **Modell mit Annahmen**, **Prüfbericht**, **Programm**.
### Wann ein Ergebnis als unzuverlässig gilt
| Grund (`reliability_issues`) | Bedeutung | Was tun |
|---|---|---|
| Zielgröße passt nicht | Das Modell optimiert etwas anderes als gefragt; es wurde **kein** Solver gestartet. | Ziel im Aufgabentext eindeutiger formulieren und neu starten. |
| Check-Fehler im Modell | z. B. Solver passt nicht zur Klasse, gemischte Einheiten in der Zielfunktion | Report „Prüfbericht“ ansehen; oft hilft `--von pruefung`. |
| Zulässigkeitsprüfung | Die gemeldete Lösung verletzt Restriktionen, Schranken oder Ganzzahligkeit. | `--von solver` versuchen. |
| Datenherkunft | Das Programm hat Eingabedaten erzeugt, ohne sie auszuweisen. | Daten beilegen (`--daten`) oder fehlende Werte in den Text schreiben. |
| Szenario ohne Ergebnis | Eine verglichene Konfiguration hat keinen Wert, ist aber nicht als unlösbar belegt (z. B. Zeitlimit). | `--von solver`. |
| Unlösbar, Gegenprobe uneindeutig | Der Solver meldet „unlösbar“, eine unabhängige zweite Modellierung konnte das weder bestätigen noch widerlegen. | Aufgabe auf widersprüchliche Bedingungen prüfen. |
### Besondere Ergebnisse
- **„infeasible“ (unlösbar)** wird nicht einfach geglaubt: Eine zweite, unabhängige Modellierung prüft es. Bestätigt sie es, steht im JSON `infeasible_confirmed: true`, und die Antworten erklären, welche Bedingungen sich widersprechen.
- **Angenommene Daten** stehen im Report unter „Angenommene Daten“ und in `solver_code.data_assumptions`. Das Ergebnis beruht dann nicht allein auf Ihren Angaben.
- **Nichtlineare Aufgaben (Ipopt)** werden von mehreren Startpunkten aus gelöst. Streuen die Ergebnisse, ist das gefundene Optimum nur die beste gefundene *lokale* Lösung – der Abschnitt „Stabilität über mehrere Startpunkte“ zeigt das.
- **Warnungen** (`solver_run.warnings`) sind Hinweise, keine Fehler – etwa eine Tabelle, deren Summe nicht zum Zielwert passt, oder ein Fachbegriff, der nicht erklärt wurde.
- Unterstützt werden **CSV** (Trennzeichen Komma, Semikolon oder Tabulator werden erkannt, deutsche Dezimalkommas ebenfalls) und **Excel** (`.xlsx`, `.xls`).
- Das Programm erstellt **ohne LLM** ein Profil je Datei (Zeilen, Spalten, Typen, Spannweiten, Lücken, Beispielwerte). Nur dieses Profil geht an das LLM, nicht der vollständige Inhalt.
- Die Dateien selbst werden ins Arbeitsverzeichnis des Solver-Programms kopiert; das Programm liest sie über ihren Dateinamen.
- Im Aufgabentext auf die Datei Bezug nehmen („Die Kurse stehen in kurse.csv“).
**Exportiertes Programm mit Daten ausführen:** Es erwartet die Dateien im selben Verzeichnis, sonst endet es mit `FileNotFoundError`:
Stehen Daten nur in einer Abbildung – ein Graph mit bewerteten Pfeilen, eine Tabelle als Bild –, kann die Aufgabe die Abbildung als Markdown-Bild enthalten. Beide Formen, die docling erzeugt, werden erkannt:
1. Die Bilder werden aus dem Text gelöst; im Text steht dort `[Abbildung 1]`.
2.**Nur die Verstehensstufe** bekommt die Bilder und überträgt jede Abbildung vollständig in Text (jede Zahl, jeder Pfeil mit Richtung und Bewertung, unsicher Gelesenes wird benannt).
3.**Gegenprobe:** Ein zweiter, unabhängiger Aufruf überträgt die Abbildungen noch einmal. Weichen die Zahlen ab, entscheidet eine dritte Lesung; stimmen keine zwei überein, gilt das Ergebnis als unzuverlässig.
4. Alle weiteren Stufen rechnen mit der Übertragung – das Bild selbst wird nicht erneut gesendet.
5. Der Report zeigt im Abschnitt „Aufgabe“ **Original und Übertragung nebeneinander**. Bitte vergleichen: Ein verlesener Wert ändert das ganze Ergebnis, und eine vertauschte Pfeilrichtung bei gleichen Zahlen fällt der Gegenprobe nicht auf.
Voraussetzungen und Grenzen:
- Das Modell der Verstehensstufe muss Bilder lesen können. `deepseek/deepseek-v4.1-flash` kann das; sonst ein Bildmodell über `LLM_MODEL_UNDERSTANDING` wählen (z. B. `qwen/qwen3.8-flash`).
- Höchstens 6 Abbildungen, je 5 MB.
- Mehrkosten: ein bis zwei zusätzliche kleine Aufrufe für die Gegenprobe.
- Verweise auf Webadressen werden nicht geladen (das Programm lädt nichts aus dem Internet).
Alle Eingabewerte des Programms stehen im Wörterbuch `DATA` (im JSON unter `solver_run.data`). Mit `--resolve` rechnet das gespeicherte Programm neu –**ohne einen einzigen LLM-Aufruf**, inklusive Zulässigkeits- und Sensitivitätsprüfung:
**Richtwerte** (DeepSeek V4.1 Flash über OpenRouter, September 2026): kleine Aufgaben etwa 0,02–0,05 $ und 1–3 Minuten, mittlere 0,05–0,15 $ und 3–10 Minuten, große mehrteilige Aufgaben mit Datenanhang bis etwa 0,20 $ und 15 Minuten. Die tatsächlichen Werte stehen am Ende jedes Laufs im Terminal und im JSON unter `usage`.
Wo das Geld hingeht: rund zwei Drittel der Kosten sind **erzeugter Output**, davon der Großteil internes „Nachdenken“ (Reasoning) des Modells; die Laufzeit hängt fast nur am Output. Die teuerste Stufe ist die Erzeugung des Solver-Codes.
| Hebel | Wirkung |
|---|---|
| `--no-solve` | nur Modell und Prüfung; spart die teuerste Stufe |
| `--von solver` / `--resolve` | Wiederholung ohne erneute Modellierung bzw. ganz ohne LLM |
| `--max-revisions 0`, `MAX_RESTARTS=0`, `SOLVER_RETRIES=0` | weniger Nacharbeit – billiger, aber Fehler bleiben eher stehen |
| `LLM_REASONING_EFFORT=low` | weniger Nachdenken, schneller und billiger; Qualität kann sinken |
| `LLM_MODEL_SOLVER=…` usw. | anderes Modell nur für einzelne Stufen, z. B. ein schnelles für den Code |
**Prompt-Cache:** Alle Aufrufe eines Laufs gehen an denselben OpenRouter-Anbieter, damit dessen Cache wiederholt gelesene Prompt-Teile billiger abrechnen kann. Der Cache-Anteil steht in der Abschlusszeile.
**Feste Modellnamen verwenden** (z. B. `deepseek/deepseek-v4.1-flash`), keine `…-latest`-Aliase – sonst ändern sich Ergebnisse unbemerkt.
`benchmark/cases/` enthält 19 Aufgaben mit unabhängig verifiziertem Optimum. Gemessen wird, ob der Zielwert stimmt und ob die Aufgabe erfüllt ist (jede Teilfrage beantwortet, jede Zahl belegt).
Ein voller Lauf über alle Fälle mit 2 Läufen kostet etwa 1,30 $ und dauert rund 50 Minuten. Die Tabelle erscheint im Terminal, Details in `benchmark/results/<Zeitstempel>.json`. Einen Report zu einem einzelnen Benchmark-Lauf erzeugt:
**Eigene Fälle** anlegen: Verzeichnis `benchmark/cases/<name>/` mit `task.txt` und `expected.json` (`problem_class`, `target_stack`, `sense`, `objective_value`, `tolerance`). Nur Fälle mit vollständigen Daten und unabhängig nachgerechnetem Optimum aufnehmen. Weitere Dateien im Verzeichnis werden als Datenanhang übergeben.
Mit dem Gemini-Gratiskontingent ist der Benchmark praktisch nicht durchführbar; dort höchstens `--jobs 1`.
---
## 13. Fehlerbehebung
| Meldung / Symptom | Ursache | Lösung |
|---|---|---|
| `KeyError: 'OPENROUTER_API_KEY'` | Schlüssel nicht gesetzt | `export OPENROUTER_API_KEY=…` in derselben Shell |
| `RESOURCE_EXHAUSTED` | Gemini-Kontingent erschöpft | später erneut oder OpenRouter-Modell |
| `Vorübergehender LLM-Fehler – neuer Versuch in … s` | Überlastung, Ratelimit, Zeitüberschreitung | nichts tun; es wird automatisch bis zu dreimal wiederholt |
| Lauf dauert sehr lange | langsamer Anbieter oder viel Reasoning | `OPENROUTER_MIN_THROUGHPUT` erhöhen, `LLM_REASONING_EFFORT=low` |
| `SOLVER_SANDBOX=bwrap verlangt bubblewrap, es ist aber nicht installiert.` | bubblewrap fehlt | `sudo apt install bubblewrap`; prüfen mit `which bwrap` |
| `pip` scheitert bei `cyipopt` | Ipopt-Bibliothek fehlt | `sudo apt install coinor-libipopt-dev pkg-config`, dann erneut installieren |
| `--report braucht die Endung .md oder .html` | falsche Dateiendung | `.html` oder `.md` verwenden |
| `--data wirkt nur zusammen mit --resolve` | `--data` allein angegeben | `--resolve ERGEBNIS.JSON --data …` |
| Exit-Code 3 | keine Optimierungsaufgabe erkannt | Entscheidung und Ziel im Text ausdrücklich formulieren |
| `FileNotFoundError` beim exportierten Programm | Datendateien fehlen im Verzeichnis des Skripts | Dateien daneben kopieren (Abschnitt 8) |
| Formeln im HTML-Report erscheinen als Rohtext | kein Internet beim Öffnen (MathJax) | online öffnen oder Markdown-Report verwenden |
| Report zeigt „Angenommene Daten“, obwohl Daten gemeint waren | Aufgabe verlangt Daten aus dem Internet, das Programm hat keinen Netzzugang | Daten als Datei beilegen (`--daten`) |
| Antwort in falscher Größenordnung (Faktor 100 oder 1000) | Einheit im Text mehrdeutig | Einheit ausdrücklich nennen („in %“, „in Tausend Euro“) |
| Seltsame Importfehler von `instructor` | eine Datei `instructor.py` im Projekt | Datei umbenennen |
---
## 14. Sicherheit und Datenschutz
- **Der Aufgabentext und das Datenprofil werden an den LLM-Anbieter gesendet** (OpenRouter und die dahinterliegenden Modellanbieter bzw. Google). Keine vertraulichen oder personenbezogenen Daten eingeben, die diesen Weg nicht gehen dürfen. Datendateien selbst verlassen den Rechner nicht, wohl aber ihr Profil mit Beispielwerten.
- **Der Solver-Code stammt von einem LLM.** Er läuft in einer bubblewrap-Sandbox: kein Netzzugang, Dateisystem nur lesbar, beschreibbar nur das Temp-Verzeichnis des Laufs. Zusätzlich sind nur Mathematik- und Solver-Bibliotheken erlaubt, `open`, `eval` und `exec` verboten, und es gilt ein Zeitlimit.
- **Ohne bubblewrap läuft der Code ungeschützt mit Ihren Benutzerrechten – und zwar ohne Warnung** (Standard `SOLVER_SANDBOX=auto`). Prüfen mit `which bwrap`. Wer sichergehen will, setzt `export SOLVER_SANDBOX=bwrap`: Dann wird ein Lauf ohne bubblewrap abgelehnt, statt ungeschützt ausgeführt.
- **Ein exportiertes Programm (`--code`) läuft außerhalb der Sandbox**, wenn Sie es selbst starten. Vorher kurz ansehen.
- **API-Schlüssel** nur als Umgebungsvariable; `.env`-Dateien sind von Git ausgeschlossen, gehören aber trotzdem nicht ins Projekt.
---
## 15. Grenzen
- **Ergebnisse vor Verwendung prüfen.** Die Prüfungen fangen viele, aber nicht alle Fehler. Besonders die Erklärung („Wie das Modell die Aufgabe sieht“) mit der eigenen Absicht vergleichen.
- **Deutsch** ist die vorgesehene Sprache von Aufgaben, Erklärungen und Antworten.
- **Größe:** Richtwerte je Klasse – lineare Programme bis etwa 10⁴ Variablen, ganzzahlige und Constraint-Modelle 10²–10³, quadratische 10³, gemischt-ganzzahlig quadratische und nichtlineare etwa 10². Darüber bleibt die Lösung möglich, Optimalität lässt sich im Zeitlimit aber oft nicht beweisen; das wird als Annahme ausgewiesen.
- **Zeitlimit des Programms:** 60 Sekunden je Ausführung.
- **Kein Netz im Programm:** Webdaten (Kurse, Wetter, Karten) müssen als Datei beigelegt werden.
- **Nichtlineare Aufgaben** liefern ohne globales Verfahren nur lokale Optima; das Programm berichtet die Streuung über mehrere Startpunkte.
- **Schlecht gestellte Aufgaben** (fehlende Angaben, mehrdeutige Einheiten, mehrteilige Projektaufträge) sind die größte Fehlerquelle. Das Programm soll dann ehrlich scheitern – Annahmen kennzeichnen, Unlösbarkeit melden, fehlende Daten zugeben –, kann eine fehlende Angabe aber nicht ersetzen.
