multi-dim-manager

Was macht multi-dim-manager?

Ein eigenständiges Skill, das Ordnung in den Zustand langlaufender,

mehrdimensionaler Berechnungsexperimente bringt. Ihr Berechnungs-Plugin erledigt die

Mathematik; dieses Skill managt das umgebende Chaos: Iteration, Momentaufnahmen,

Prüfpfad und Wiederherstellung.

Das Skill orchestriert nur. Es berechnet selbst nie ein Ergebnis – jede

Zahl stammt von Ihrem Plugin.

Verwendung

• Ein Workflow durchläuft viele Runden über einen Parameterraum (ein kartesisches Gitter von

  Dimensionen) und benötigt die Aufzeichnung des Zustands jeder Runde.

• Momentaufnahmen deklarierter kritischer Dateien sind vor und nach jeder Runde erforderlich.

• Ein vollständiger Prüfpfad (Parameter, Hashes, Zeitstempel, Status) muss für jede Runde existieren.

• Der Benutzer muss in der Lage sein, jede vergangene Runde zerstörungsfrei wiederherzustellen.

• Typische Formen: Längsschnittstudien, Parameterscans oder symbolische/numerische Sweeps, die externe Löser aufrufen (Mathematica, GAP, SymPy, eigene Skripte).

VERPFLICHTENDER WORKFLOW

Abhängigkeiten bootstrappen (bei erster Verwendung)

Vor dem ersten Lauf die Laufzeitabhängigkeiten für dieses Skill prüfen:

• Kern: reine Standardbibliothek – keine Installation erforderlich.
• Optional: PyYAML (nur wenn die Konfiguration eine .yaml-Datei ist; JSON-Konfigurationen funktionieren mit der Standardbibliothek allein).

Wenn PyYAML fehlt und die Konfiguration des Benutzers YAML ist, ihn darauf hinweisen und fragen, ob pip install pyyaml ausgeführt werden soll; nur nach Bestätigung installieren. Niemals ohne ausdrückliche Zustimmung in die globale Umgebung installieren.

Führen Sie diese Schritte in der angegebenen Reihenfolge aus, wenn der Benutzer bittet, ein

mehrdimensionales Experiment auszuführen, zu inspizieren oder wiederherzustellen.

1. Konfiguration laden. Die Experimentkonfiguration lesen (config.example.yaml ist die Vorlage). Sicherstellen, dass param_space.dimensions, critical_paths und der plugin.command vorhanden sind. Bei YAML muss PyYAML installiert sein; sonst JSON verwenden.
2. Raum erweitern. Das kartesische Produkt aller Dimensionen aufzählen. Dem Benutzer die Gesamtzahl der Runden melden, bevor ausgeführt wird.
3. Probelauf bevorzugen. python scripts/run.py dryrun --config <cfg> ausführen, damit der Benutzer den vollständigen Plan (jede Parameterkombination) ohne Nebenwirkungen sieht. Erst nach Bestätigung mit der Ausführung fortfahren.
4. Sweep ausführen. python scripts/run.py run --config <cfg> ausführen. Für jede Runde nacheinander: Momentaufnahme der deklarierten kritischen Pfade vorher, Plugin aufrufen, Momentaufnahme nachher, und einen Prüfdatensatz anhängen.
5. Bei Fehlern richtig reagieren. Wenn das Plugin einer Runde ungleich null beendet wird, den Status (failed/error) aufzeichnen. Wenn auto_rollback aktiviert ist, den Zustand der letzten erfolgreichen Runde in das Arbeitsverzeichnis wiederherstellen, damit nachfolgende Runden sauber starten; diese Wiederherstellung wird selbst geprüft. Den gesamten Sweep bei einer einzelnen ungültigen Kombination nicht abbrechen.
6. Zusammenfassen. Nach dem Sweep schreibt das Skill results_summary.csv, results_summary.md, report_draft.md und run_metadata.json unter dem Ausgabeverzeichnis. Den Benutzer darauf hinweisen.
7. Auf Anfrage wiederherstellen. Um eine vergangene Runde wiederherzustellen, python scripts/run.py rollback --config <cfg> --round <N> ausführen. Standardmäßig wird in ein NEUES Verzeichnis wiederhergestellt; --force nur hinzufügen, wenn der Benutzer ausdrücklich wünscht, dass das aktive Arbeitsverzeichnis überschrieben wird.

Harte Einschränkungen

• Berechnen Sie das Ergebnis niemals selbst. Alle domänenspezifische Mathematik gehört in das Plugin des Benutzers. Das Skill ruft es nur auf und zeichnet das Vertragsergebnis auf.
• Nur deklarierte kritische Pfade erfassen. Es wird niemals eine vollständige Kopie des Arbeitsverzeichnisses erstellt; der Inhalt wird adressiert durch Hash gespeichert, sodass unveränderte Dateien keine zusätzlichen Kosten verursachen.
• Wiederherstellung ist standardmäßig zerstörungsfrei. Ohne --force wird das aktive Arbeitsverzeichnis nie geändert; der wiederhergestellte Zustand landet in einem neuen Verzeichnis. Jede Wiederherstellung (manuell oder automatisch) wird im Prüfprotokoll festgehalten.
• Determinismus liegt in der Verantwortung des Benutzers. Das Skill garantiert, dass die Orchestrierung reproduzierbar ist (gleiche Parameter → gleicher aufgezeichneter Plan, gleiche Hashes). Es kann ein nicht-deterministisches Plugin nicht deterministisch machen; siehe Einschränkungen.

Verwendungsbeispiele

# Den vollständigen Rundenplan ohne Nebenwirkungen anzeigen (immer zuerst ausführen).



python scripts/run.py dryrun --config config.example.yaml







# Den Sweep ausführen.



python scripts/run.py run --config config.example.yaml







# Eine vergangene Runde wiederherstellen (in ein NEUES Verzeichnis, es sei denn --force).



python scripts/run.py rollback --config config.example.yaml --round 7







# Die Zusammenfassungen neu generieren oder das Ergebnis einer Runde überprüfen.



python scripts/run.py summary --config config.example.yaml



python scripts/run.py verify --config config.example.yaml --round 7

Plugin-Vertrag

Der Manager startet genau einen Shell-Befehl pro Runde:

python your_plugin.py --params {PARAMS} --out {OUT}

• {PARAMS} – Pfad zu einer JSON-Datei mit der Parameterkombination dieser Runde.
• {OUT} – Pfad, in den das Plugin zwingend seine Ergebnis-JSON schreiben MUSS.
• Exit-Codes: 0 Erfolg, 1 Behauptung fehlgeschlagen / Prüfung fehlgeschlagen, 2 Fehler oder übersprungen.

Jeder externe Löser (Mathematica, GAP, ein Python-LMM-Skript) wird so umhüllt, dass er diesen Vertrag einhält: Er liest die Parameterdatei und schreibt eine Ergebnisdatei. Das Skill kümmert sich nicht darum, was berechnet wird.

Fehlerbehandlung

• Eine Runde, deren Plugin mit Exit-Code 1 endet, wird als failed markiert; Exit-Code 2 als error. Beide werden im Prüfprotokoll geführt; der Sweep läuft weiter.
• Fehler in der Konfiguration (fehlender Raum, fehlerhaftes YAML, fehlender {OUT}) brechen den Vorgang vor jeglichen Nebenwirkungen ab und geben eine klare Meldung aus (Exit-Code 2).
• Ein rollback auf eine Runde, die nie aufgezeichnet wurde oder keine Nach-Momentaufnahme hat, schlägt mit einer klaren Fehlermeldung fehl, ohne den Zustand zu beschädigen.

Einschränkungen

• Determinismus gilt nur auf Orchestrierungsebene. Der Manager zeichnet Hashes auf und spielt für dieselben Parameter denselben Plan ab, aber er kann nicht erzwingen, dass das Plugin deterministisch ist. Wenn das Plugin auf das Netzwerk zugreift, Zufalls-Seeds verwendet oder die Systemuhr ausliest, können gleiche Eingaben unterschiedliche Ausgaben liefern. Deklarieren Sie solche Nichtdeterminiertheit selbst im Plugin.
• Kritische Pfade müssen im Voraus deklariert werden. Dateien, die nicht in critical_paths aufgeführt sind, werden nie gesnapshotet und können daher nicht wiederhergestellt werden.
• Überprüfung der goldenen Ausgabe ist v0.2. Der aktuelle Prüfer überprüft nur den Plugin-Vertrag (Exit 0 + Ergebnisdatei vorhanden). Ein Vergleich mit einer bekannten erwarteten Ausgabe ist geplant, aber noch nicht implementiert.
• YAML-Konfigurationen benötigen PyYAML. JSON-Konfigurationen funktionieren mit der Standardbibliothek allein.