Project Bourne

Project Bourne ist eine Open-Source-Infrastruktur für Ausführung und Provenienz reproduzierbarer wissenschaftlicher und technischer Workloads.

Es plant und führt Rechenexperimente auf lokalen Maschinen, GPUs, Slurm und PBS aus und bewahrt dabei Eingaben, Ausgaben, Ausführungskontext, Artefakt-Herkunft, Telemetrie, Verifikation und den Verlauf, der zur Reproduktion eines Ergebnisses erforderlich ist.

Es richtet sich an Forschende, Studierende vom Bachelor- bis zum Promotionsniveau, Lehrende, Forschungsingenieur:innen, Computerwissenschaftler:innen, Nutzer:innen wissenschaftlicher Software und Teams für wissenschaftliches Rechnen in Hochschulen, öffentlicher Forschung und industrieller F&E.

Quick Start

Human

Die CLI für Menschen ist ab sofort öffentlich verfügbar:

python -m pip install bourneprov

bourne run python examples/demo.py
bourne list
bourne show @1

# Or execute an ExecutionRequest v1 document:
bourne execute --request bourne.json

Agent / MCP

Die Agent- und MCP-Einstiegspunkte von v0.6.0 sind öffentlich:

python -m pip install "bourneprov[mcp]==0.6.0"
npx -y @project-bourne/mcp@0.6.0

Für die Entwicklung aus einem Quellcode-Checkout stattdessen:

python -m pip install -e ".[mcp]"
bourne mcp

Related MCP server: heddle

Warum Bourne

Bourne kapselt beliebige ausführbare Dateien, ohne dass Änderungen am wissenschaftlichen Programm erforderlich sind. Es ist lokal-first und framework-agnostisch: Python, kompilierte Solver, Julia, MPI-Programme und andere Befehle verwenden dasselbe dauerhafte Experimentmodell.

bourne run bash -c "echo hello"
bourne run ./solver case.yaml
bourne run julia simulation.jl
bourne run mpirun -np 64 ./solver

Programm-stdout und -stderr bleiben während der Ausführung sichtbar und werden im Experimentdatensatz aufbewahrt.

Architektur

Bourne Core ist verantwortlich für deterministische Ausführung, Planung, Speicherung und Provenienz. Menschen können es über die CLI oder Python-Dienste nutzen; Agenten können dieselben Dienste über den optionalen MCP-Adapter nutzen:

             Project Bourne Core
                    │
       ┌────────────┼────────────┐
       │            │            │
      CLI          SDK          MCP
    humans                     agents

Die Agentenschnittstelle ist ein optionaler Zugangspfad, nicht die Produktidentität von Bourne. MCP funktioniert ohne die portable Agent-Skill, und Bourne enthält kein eingebettetes LLM.

Agent- und MCP-Integration

Der kanonische lokale stdio-Server ist bourne mcp. Die stabile offizielle Identität im MCP-Registry ist io.github.KozakHou/project-bourne, und die portable Agent-Skill befindet sich unter skills/project-bourne. Das v0.6.0-npm-Paket und der zugehörige Registry-Eintrag sind öffentlich.

Ein MCP-kompatibler Agent kann eine explizite Anfrage wie „Führen Sie diese Simulation mit vier GPUs aus und bewahren Sie die Provenienz“ in eine ExecutionRequest v1 übersetzen, Bourne um deren Planung bitten, die deterministische Auflösung anzeigen und den unveränderlichen Plan ausführen, sobald die Ausführungsabsicht festgestellt wurde. Bourne selbst interpretiert keine uneingeschränkte natürliche Sprache und ruft kein anderes Modell auf.

Der Agentenpfad ist bewusst zweiphasig:

agent intent → ExecutionRequest v1 → bourne_plan → inspect → bourne_execute_plan

Die Planung führt die Arbeitslast niemals aus und entdeckt auch nicht stillschweigend Infrastruktur. Mehrdeutige Ziele und unbekannte Fakten bleiben unaufgelöst. MCP-Annotationen sind Host-UX-Hinweise; Bourne Core setzt weiterhin unveränderliche Pläne, exakte argv, Scheduler-Job-Eigentümerschaft, Artefakt-Semantik und Provenienz durch. Siehe MCP-Integration und Agent-Leitfaden.

Ausführungsanfragen

Eine Ausführung kann jetzt einmalig in einer begrenzten, versionierten JSON-Anfrage beschrieben werden:

{
  "kind": "bourne.execution-request",
  "version": 1,
  "command": ["python", "train.py", "--case", "case1"],
  "artifacts": {
    "inputs": ["config.yaml"],
    "outputs": ["result.h5"]
  },
  "resources": {"cpus": 8, "gpus": 1, "walltime": "2h"},
  "execution": {"backend": "direct"},
  "verification": {
    "checks": [
      {"type": "output_exists", "path": "result.h5"},
      {"type": "output_min_bytes", "path": "result.h5", "min_bytes": 1024}
    ]
  }
}

Speichern Sie sie als bourne.json und verwenden Sie dann dieselbe Absicht für Planung oder Ausführung:

bourne request validate bourne.json
bourne request show bourne.json

bourne discover
bourne plan --request bourne.json
bourne execute --request bourne.json

Erstellen Sie eine minimale Anfrage, ohne etwas auszuführen oder zu entdecken:

bourne request init --output bourne.json -- python train.py
bourne request schema > execution-request-v1.schema.json

Bestehende flag-basierte Befehle werden weiterhin unterstützt. Sie werden in dieselbe Pipeline ExecutionRequest → WorkloadSpec → ExecutionPlan kompiliert, statt in eine parallele Implementierung:

bourne execute --backend direct --cpus 2 --output result.txt -- python script.py

Für eine Anfragedatei wird ein relatives working_directory aus dem Verzeichnis der Anfragedatei aufgelöst. Deklarierte Artefakte werden dann aus diesem wissenschaftlichen Arbeitsverzeichnis aufgelöst. Bourne bewahrt sowohl die lexikalischen als auch die aufgelösten Arbeitsverzeichniswerte; es expandiert beim Parsen oder Planen $HOME nicht, wertet Shell-Syntax nicht aus, importiert keinen Projektcode und führt nichts aus.

Elternreferenzen folgen derselben absichtserhaltenden Regel. Eine Anfrage kann latest, @N, ein eindeutiges Präfix oder eine vollständige ULID verwenden. Bourne behält diesen angeforderten Wert bei und zeichnet separat die kanonische Eltern-ULID auf, die von der kompilierten Arbeitslast verwendet wird.

Die zusammenfassende Telemetrie ist standardmäßig aktiviert und verwendet bereits erfasste Fakten: Wanduhrzeit, UTF-8-Bytezahlen von stdout/stderr, bekannte Artefakt-Bytegesamtwerte, angeforderte Ressourcen, beobachtete Zuteilung und Scheduler-Queue-Zeiten, sofern Zeitstempel sie belegen. "telemetry": {"mode": "off"} deaktiviert die Zusammenfassung. Fehlende Metriken bleiben nicht verfügbar, niemals null.

Die anfänglichen deterministischen Verifikationsprüfungen sind output_exists, output_min_bytes und output_sha256. Sie bewerten ausschließlich erfasste deklarierte Artifact-Datensätze von Ausgaben. Die Verifikation wird getrennt vom Prozessstatus gespeichert: Ein Experiment kann completed sein, während die Verifikation failed oder unknown ist. Diese Prüfungen stellen Artefakt-Fakten fest, keine allgemeine wissenschaftliche Gültigkeit. Den genauen Vertrag und die Sicherheitsgrenzen finden Sie unter Ausführungsanfragen, Telemetrie und Verifikation.

Planung und Ausführung

Project Bourne v0.4.0 fügt eine dauerhafte Planungsebene zu v0.3-Inventaren hinzu:

bourne discover

bourne plan --backend direct -- python examples/demo.py
bourne execute --backend direct -- python examples/demo.py

bourne execution list
bourne execution show @1

bourne plan führt den wissenschaftlichen Befehl nie aus und führt nie eine Erkundung durch. Es erstellt eine framework-unabhängige WorkloadSpec, vergleicht ihre expliziten und abgeleiteten Anforderungen mit einem vorhandenen Inventar, erläutert jeden Kandidaten und speichert einen unveränderlichen ExecutionPlan nur dann, wenn die Auswahl eindeutig ist. Verwenden Sie bei Bedarf explizite Ressourcen- und Platzierungsbeschränkungen:

bourne plan \
  --backend slurm \
  --target gpu \
  --cpus 16 \
  --gpus 4 \
  --nodes 1 \
  --memory 64G \
  --walltime 2h \
  -- ./solver case.yaml

Führen Sie einen ausgewählten Slurm-Plan aus und prüfen oder warten Sie anschließend auf den resultierenden Ausführungsversuch:

bourne execute --plan @1
bourne execution show @1
bourne execution wait @1

Während ein aufgezeichneter Job noch aktiv ist, fordert bourne execution cancel @1 die Stornierung dieses von Bourne verwalteten Jobs an. Dasselbe Planungs- und Lebenszyklusmodell unterstützt --backend pbs.

Die direkte Ausführung nutzt Bournes bestehende Mechanismen für Live-Ausgabe, Prozessgruppe, Artefakte, Herkunft und Experiment-Provenienz. Slurm- und PBS-Pläne verwenden einen eigenständigen Bourne-Worker, der zusammen mit dem Plan bereitgestellt wird. Der Worker führt einen Preflight durch und zeichnet den tatsächlich zugewiesenen Host und das wissenschaftliche Experiment auf; der Controller auf der Zugriffsseite importiert sein begrenztes JSON-Ergebnis transaktional. Es sind weder SSH auf dem Rechenknoten noch ein vorinstalliertes bourneprov-Paket erforderlich, allerdings muss die Rechenzuteilung Python 3 und die Sichtbarkeit der Staging- und Arbeitsverzeichnisse bereitstellen.

Die Einreichung ist kein Experiment, der Abschluss durch den Scheduler ist kein wissenschaftlicher Erfolg, und angeforderte Ressourcen sind keine zugewiesenen Ressourcen. Bourne zeichnet diese als separate dauerhafte Fakten auf. Die Stornierung akzeptiert eine Bourne-Ausführungsreferenz – keine beliebige Scheduler-Job-ID – und prüft die einreichende Identität. Das genaue Modell, die Sicherheitsgrenze und die aktuellen Einschränkungen finden Sie unter Workload-Planung und Scheduler-Ausführung.

Compute-Standort-Erkundung (v0.3.0)

Bourne kann einen unveränderlichen, lokalen Snapshot der Ausführungsoberfläche erstellen, die für Ihre aktuelle Identität sichtbar ist:

bourne discover
bourne inventory
bourne inventory --find python
bourne inventory --json

Die Erkundung umfasst die aktuelle Identität und das Zugriffsziel, zugelassene benutzerrelevante Speicherpfade, direkte Ausführungskontexte, generische ausführbare Dateien im PATH, optionale Conda-/virtualenv-/Container-/Modul-Kontexte, sichere Systemfähigkeiten, den Bourne-Verlauf und – sofern verfügbar – schreibgeschützte Slurm-/PBS-Zielklassen-Zusammenfassungen. Eine unbekannte ausführbare Datei wird generisch aufgezeichnet, ohne ausgeführt zu werden. Laptops, Desktop- und GPU-Workstations, persönliche Maschinen der DGX-Klasse, gemeinsame Laborsysteme und Scheduler-gestützte HPC-Standorte sind allesamt gültige Computestandorte. Eine Maschine ohne Scheduler ist für sich genommen vollständig.

Die Erkundung ist beobachtend: Eine ausführbare Datei wird nicht auf Workload-Kompatibilität verifiziert, eine sichtbare Scheduler-Partition ist kein Beweis für eine Einreichungsberechtigung, und ein Hinweis auf eine Speicherrolle ist keine Aufbewahrungs- oder Sicherungsrichtlinie. Inventare bleiben lokal. Anbieter durchsuchen weder die Home-Verzeichnisse anderer Benutzer noch crawlen sie gemeinsamen Speicher, untersuchen SSH-Anmeldeinformationen oder Container-Geheimnisse, geben beliebige Umgebungsvariablen aus, stellen SSH-Verbindungen zu Rechenknoten her, reichen Scheduler-Jobs ein oder stornieren sie oder verändern Umgebungen. Die genaue Topologie, Beweise, Grenzen und Sicherheitssemantik finden Sie unter Erkundung von Computestandorten.

Provenienz, Artefakte und Herkunft

Project Bourne v0.2 fügt explizite Eingabe-/Ausgabe-Fingerprints, eine minimale derived_from-Beziehung, sichere Beobachtungen des Ausführungskontexts und Artefaktverfolgung hinzu. Führen Sie das deterministische Beispiel aus einem isolierten Verzeichnis aus:

cp -R examples/provenance /tmp/bourne-provenance-demo
cd /tmp/bourne-provenance-demo
export BOURNE_DB="$PWD/bourne.sqlite3"

bourne run \
  --input config_A.json \
  --output result_A.csv \
  -- python demo_simulation.py config_A.json result_A.csv

bourne run \
  --derived-from @1 \
  --input config_B.json \
  --input result_A.csv \
  --output result_B.csv \
  -- python demo_simulation.py config_B.json result_B.csv

bourne show @2
bourne show @1
bourne trace result_B.csv

Für Eingaben werden vor der Ausführung Fingerprints erstellt. Für Ausgaben werden sie danach erstellt, einschließlich erwarteter Ausgaben, die nach einem fehlgeschlagenen oder unterbrochenen Lauf fehlen. SHA-256-Lesevorgänge werden in Blöcken gestreamt; Bourne kopiert oder lädt deklarierte Dateien nicht hoch.

Ein Pfad ist keine Artefaktidentität. Jede Erfassung hat eine stabile ULID, während SHA-256 Inhaltsversionen unterscheidet. Wenn ein historischer Pfad mehrere Versionen identifizieren könnte und der aktuelle Dateiinhalt sie nicht eindeutig unterscheiden kann, listet bourne trace Kandidaten auf und weigert sich zu raten.

Siehe Artefakte, Herkunft und Ausführungskontext für die genaue Erfassungs-, Verfolgungs-, Migrations- und Sicherheitssemantik.

Benutzerfreundliche Experimentreferenzen

Kanonische Experimentidentitäten bleiben 26-Zeichen-ULIDs. Befehle, die ein Experiment akzeptieren, verstehen auch:

01M02GDJEW...   case-insensitive unique ULID prefix
latest          most recent experiment
@1              most recent experiment
@2              second-most-recent experiment
@3              third-most-recent experiment

Zum Beispiel:

bourne show latest
bourne show 01M02GDJEW
bourne compare @2 @1
bourne run --derived-from @1 -- ./solver case_B.yaml

Bourne rät nie, wenn ein Präfix mehrdeutig ist. bourne list zeigt standardmäßig ein 10-Zeichen-Präfix an; bourne list --full-id zeigt kanonische IDs an.

Shell-Vervollständigung

Die Vervollständigungskandidaten umfassen kanonische Experiment-IDs, latest und aktuelle @N-Referenzen. Aktivieren Sie die Vervollständigung für die aktuelle Shell-Sitzung mit:

# Bash
source <(bourne completion bash)

# Zsh
source <(bourne completion zsh)

# Fish
bourne completion fish | source

Die Vervollständigung für bourne show und bourne compare fragt die aktuell konfigurierte Datenbank ab, einschließlich BOURNE_DB.

Was Bourne aufzeichnet

Jedes Experiment zeichnet Folgendes auf:

• Ausführungsstatus (completed, failed oder interrupted), exakter Argumentvektor, Arbeitsverzeichnis, UTC-Zeitstempel, Dauer und Exit-Code;

• Live- und aufgezeichnetes stdout/stderr;

• Git-Repository-Wurzel, Commit, Branch und Dirty-State, sofern verfügbar;

• Betriebssystem, Architektur, Hostname, CPU und optionale NVIDIA-Runtime-Metadaten;

• angeforderte und aufgelöste Pfade ausführbarer Dateien sowie streng zugelassene virtualenv/Conda-Kontexthinweise;

• explizit deklarierte Eingabe-/Ausgabe-Artefaktversionen und unmittelbare Herkunft.

Die Erfassungskomponenten degradieren kontrolliert. Fehlendes Git, fehlende NVIDIA-Tools, GPUs, Umgebungshinweise oder eine fehlende Auflösung ausführbarer Dateien stoppen die Arbeitslast nicht. Beliebige Umgebungsvariablen werden nicht persistiert, daher werden Anmeldeinformationen und Token standardmäßig nicht erfasst.

Fehlgeschlagene und unterbrochene Befehle werden gespeichert, bevor bourne ihre Prozesssemantik zurückgibt:

bourne run --output expected.csv -- python -c "raise RuntimeError('boom')"
bourne show @1

Auf POSIX-Systemen verwendet Bourne eine eigene Prozessgruppe, sodass Strg+C normalerweise Nachfolgeprozesse beendet, ohne unzusammenhängende Prozesse zu beeinträchtigen.

Erfolgreiche Ausführung ist keine Verifikation, und deterministische Artefaktverifikation ist keine allgemeine wissenschaftliche Gültigkeit. Bourne zeichnet diese Zustände getrennt auf.

Lokale Speicherung und Migration

Der standardmäßige SQLite-Pfad ist:

~/.local/share/bourne/experiments.sqlite3

Verwenden Sie eine projektspezifische Datenbank mit:

export BOURNE_DB=/path/to/experiments.sqlite3

Das Öffnen einer v0.1.1-, v0.2.0-, v0.3.0- oder v0.4.0-Datenbank mit diesem Release-Kandidaten führt deterministische transaktionale Migrationen bis Schema 5 durch. Vorhandene Experimente, Artefakte, Herkunft, Inventare, Workloads, Pläne, Ausführungen, Scheduler-Jobs, Zuteilungen, Ereignisse und Experimentverknüpfungen bleiben lesbar. Die Migration erfindet keine ExecutionRequest-Historie für v0.4-Datensätze. Unbekannte oder neuere Schema-Versionen schlagen explizit fehl; Bourne setzt eine vorhandene Datenbank nie zurück. Jede neue Erkundung erstellt einen separaten unveränderlichen Snapshot.

Lizenz

Project Bourne v0.5.0 und höher werden unter der Apache License 2.0 vertrieben. Veröffentlichungen bis einschließlich v0.4.0 verbleiben unter den MIT-Lizenzbedingungen, unter denen sie veröffentlicht wurden. Details finden Sie im Lizenzverlauf.

Release-Validierung

Die Repository-Version ist 0.6.0. Die Basis-Laufzeitumgebung hat null Drittanbieter-Abhängigkeiten; die MCP-Unterstützung bleibt ein ausdrückliches optionales Extra.

Führen Sie die Tests im Quellbaum mit folgendem Befehl aus:

PYTHONPATH=src python -W error::ResourceWarning -m unittest discover -s tests -v

Nicht im Festplatten-Cache zwischengespeicherte Experiment-Logs, automatische Artefakt-Erkennung, Artefakt-Archivierung, automatische Installation wissenschaftlicher Abhängigkeiten, automatisches Modul-Laden, Container-Orchestrierung, SSH-Ausführung, Remote-Kopieren, Auslastungs-Sampling, Profiling, beliebige Verifikations-Skripte, breite wissenschaftliche Validitäts-Inferenz, gehostetes HTTP-MCP, eingebettete LLMs und Verarbeitung natürlicher Sprache bleiben außerhalb von v0.6.0. Siehe docs/VISION.md für die langfristige Ausrichtung.