Project Bourne

Project Bourne は、再現可能な科学・工学ワークロードのためのオープンソースの実行・証明基盤です。

ローカルマシン、GPU、Slurm、PBS にわたって計算実験を計画・実行し、入力、出力、実行コンテキスト、成果物の来歴、テレメトリ、検証、そして結果を再現するために必要な履歴を保持します。

研究者、学部から博士課程までの学生、教員、リサーチエンジニア、計算科学者、科学ソフトウェアの利用者、そしてアカデミア・公的研究・産業界の R&D における科学計算チームを対象に設計されています。

クイックスタート

ヒューマン

ヒューマン向け CLI は本日公開されています:

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

エージェント / MCP

v0.6.0 のエージェントおよび MCP エントリポイントは公開されています:

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

ソースチェックアウトから開発する場合は、代わりに以下を使用します:

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

Related MCP server: heddle

Bourne を選ぶ理由

Bourne は、科学プログラムに変更を加えることなく任意の実行可能ファイルをラップします。ローカルファーストかつフレームワーク非依存です。Python、コンパイル済みソルバー、Julia、MPI プログラム、その他のコマンドはすべて、同じ永続的な実験モデルを使用します。

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

プログラムの stdout と stderr は実行中も表示され続け、実験記録に保存されます。

アーキテクチャ

Bourne Core は、決定的実行、計画、ストレージ、および証明を担います。ヒューマンは CLI または Python サービスを通じて利用でき、エージェントはオプションの MCP アダプタを通じて同じサービスを利用できます:

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

エージェントインターフェースはオプションのアクセス経路であり、Bourne の製品アイデンティティではありません。MCP はポータブル Skill なしでも動作し、Bourne には組み込み LLM は含まれていません。

エージェントおよび MCP 統合

標準のローカル stdio サーバーは bourne mcp です。公式の安定版 MCP Registry アイデンティティは io.github.KozakHou/project-bourne であり、ポータブル Agent Skill は skills/project-bourne にあります。v0.6.0 の npm パッケージと対応する Registry エントリは公開されています。

MCP 互換エージェントは、「このシミュレーションを4つの GPU で実行し、証明を保持する」といった明示的なリクエストを ExecutionRequest v1 に変換し、Bourne に計画を依頼し、決定的な解決結果を表示し、実行意図が確立された後に不変の計画を実行できます。Bourne 自体は制約のない自然言語を解釈せず、別のモデルを呼び出すこともありません。

エージェント経路は意図的に2段階になっています:

agent intent → ExecutionRequest v1 → bourne_plan → inspect → bourne_execute_plan

計画はワークロードを実行したり、インフラストラクチャを暗黙的に探索したりしません。曖昧なターゲットや未知の事実は未解決のまま残ります。MCP アノテーションはホスト UX のヒントであり、Bourne Core は不変の計画、正確な argv、スケジューラジョブの所有権、成果物のセマンティクス、および証明を引き続き強制します。MCP 統合 と エージェントガイダンス を参照してください。

実行リクエスト

実行は、境界が定められたバージョン付き JSON リクエストとして一度記述できるようになりました:

{
  "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}
    ]
  }
}

これを bourne.json として保存し、計画または実行に同じ意図を使用します:

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

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

実行や探索を行わずに最小限のリクエストを作成します:

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

既存のフラグベースのコマンドは引き続きサポートされます。これらは並列実装ではなく、同じ ExecutionRequest → WorkloadSpec → ExecutionPlan パイプラインにコンパイルされます:

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

リクエストファイルの場合、相対的な working_directory はリクエストファイルのディレクトリから解決されます。宣言された成果物は、その科学的作業ディレクトリから解決されます。Bourne は語彙上の作業ディレクトリ値と解決された作業ディレクトリ値の両方を保持し、$HOME の展開、シェル構文の評価、プロジェクトコードのインポート、または解析・計画中の実行は一切行いません。

親参照も同じ意図保持ルールに従います。リクエストは latest、@N、一意のプレフィックス、または完全な ULID を使用できます。Bourne は要求された値を保持しつつ、コンパイルされたワークロードが使用した正規の親 ULID を別途記録します。

サマリーテレメトリはデフォルトで有効であり、すでに取得済みの事実を使用します: ウォールタイム、UTF-8 の stdout/stderr バイト数、既知の成果物の合計バイト数、要求されたリソース、観測された割り当て、およびタイムスタンプがそれを確立する場合のスケジューラキューのタイミングです。"telemetry": {"mode": "off"} はサマリーを無効にします。欠落したメトリクスはゼロではなく、利用不可のままです。

初期の決定的検証チェックは output_exists、output_min_bytes、output_sha256 です。これらは取得済みの宣言された出力 Artifact レコードのみを評価します。検証はプロセスステータスとは別に永続化されます: 実験が completed であっても、検証は failed または unknown になる可能性があります。これらのチェックは成果物の事実を確立するものであり、一般的な科学的妥当性を確立するものではありません。正確な契約と安全限界については、実行リクエスト、テレメトリ、および検証 を参照してください。

計画と実行

Project Bourne v0.4.0 は、v0.3 インベントリの上に永続的な計画レイヤーを追加します:

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 は科学的コマンドを実行せず、探索も行いません。フレームワーク非依存の WorkloadSpec を作成し、その明示的および推論された要件を既存のインベントリと比較し、各候補を説明し、選択が曖昧でない場合にのみ不変の ExecutionPlan を永続化します。必要に応じて明示的なリソースおよび配置制約を使用します:

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

選択した Slurm 計画を実行し、結果の実行試行を検査または待機します:

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

記録されたジョブがまだアクティブな間、bourne execution cancel @1 はその Bourne 管理ジョブのキャンセルを要求します。同じ計画およびライフサイクルモデルが --backend pbs をサポートします。

直接実行は、Bourne の既存のライブ出力、プロセスグループ、成果物、来歴、および実験証明の仕組みを再利用します。Slurm および PBS 計画は、計画とともにステージングされた自己完結型の Bourne ワーカーを使用します。ワーカーはプリフライトを実行し、実際に割り当てられたホストと科学的実験を記録します。アクセス側コントローラーは、その境界付き JSON 結果をトランザクション的にインポートします。計算ノードへの SSH やプリインストールされた bourneprov パッケージは不要ですが、計算割り当ては Python 3 とステージング・作業ディレクトリへの可視性を提供する必要があります。

送信は実験ではなく、スケジューラの完了は科学的成功ではなく、要求されたリソースは割り当てられたリソースではありません。Bourne はこれらを別個の永続的な事実として記録します。キャンセルは、任意のスケジューラジョブ ID ではなく Bourne 実行参照を受け入れ、送信者のアイデンティティをチェックします。正確なモデル、安全境界、および現在の制限については、ワークロード計画とスケジューラ実行 を参照してください。

計算サイトの探索 (v0.3.0)

Bourne は、現在のアイデンティティから見える実行サーフェスの不変のローカルスナップショットを取得できます:

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

探索は、現在のアイデンティティとアクセスターゲット、許可リストに登録されたユーザー関連ストレージパス、直接実行コンテキスト、一般的な PATH 実行可能ファイル、オプションの Conda/virtualenv/container/module コンテキスト、安全なシステム機能、Bourne 履歴、および利用可能な場合の読み取り専用の Slurm/PBS ターゲットクラスサマリーをカバーします。未知の実行可能ファイルは実行されずに汎用的に記録されます。ラップトップ、デスクトップおよび GPU ワークステーション、DGX クラスの個人マシン、共有ラボシステム、スケジューラバックの HPC サイトはすべて有効な計算サイトです。スケジューラのないマシンもそれ自体で完全です。

探索は観察的なものです: 実行可能ファイルがワークロード互換性を検証されたわけではなく、可視のスケジューラパーティションが送信承認の証明ではなく、ストレージの役割ヒントが保持またはバックアップポリシーではありません。インベントリはローカルのままです。プロバイダーは他のユーザーのホームディレクトリを横断せず、共有ストレージをクロールせず、SSH 認証情報やコンテナシークレットを検査せず、任意の環境変数をダンプせず、計算ノードに SSH せず、スケジューラジョブを送信・キャンセルせず、環境を変更しません。正確なトポロジー、証拠、制限、およびセキュリティセマンティクスについては、計算サイトの探索 を参照してください。

証明、成果物、および来歴

Project Bourne v0.2 は、明示的な入力/出力フィンガープリント、最小限の derived_from 関係、安全な実行コンテキスト観測、および成果物トレーシングを追加します。隔離されたディレクトリから決定的な例を実行します:

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

入力は実行前にフィンガープリントされます。出力は実行後にフィンガープリントされ、失敗または中断された実行後に欠落している期待出力も含まれます。SHA-256 読み取りはチャンク単位でストリーミングされます。Bourne は宣言されたファイルをコピーまたはアップロードしません。

パスは成果物のアイデンティティではありません。各キャプチャには安定した ULID があり、SHA-256 はコンテンツバージョンを区別します。履歴上のパスが複数のバージョンを特定でき、現在のファイルコンテンツがそれらを曖昧さなく区別できない場合、bourne trace は候補をリストし、推測を拒否します。

正確なキャプチャ、トレース、移行、およびセキュリティセマンティクスについては、成果物、来歴、および実行コンテキスト を参照してください。

ヒューマンフレンドリーな実験参照

正規の実験アイデンティティは26文字の ULID のままです。実験を受け付けるコマンドは以下も理解します:

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

例えば:

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

Bourne はプレフィックスが曖昧な場合に推測することはありません。bourne list はデフォルトで10文字のプレフィックスを表示し、bourne list --full-id は正規の ID を表示します。

シェル補完

補完候補には、正規の実験 ID、latest、および最近の @N 参照が含まれます。現在のシェルセッションで補完を有効にするには:

# Bash
source <(bourne completion bash)

# Zsh
source <(bourne completion zsh)

# Fish
bourne completion fish | source

bourne show および bourne compare の補完は、現在設定されているデータベース (BOURNE_DB を含む) をクエリします。

Bourne が記録するもの

すべての実験は以下を記録します:

• 実行ステータス (completed、failed、または interrupted)、正確な引数ベクトル、作業ディレクトリ、UTC タイムスタンプ、所要時間、および終了コード;

• ライブおよびキャプチャされた stdout/stderr;

• 利用可能な場合の Git リポジトリルート、コミット、ブランチ、およびダーティ状態;

• オペレーティングシステム、アーキテクチャ、ホスト名、CPU、およびオプションの NVIDIA ランタイムメタデータ;

• 要求および解決された実行可能ファイルパスと、厳密に許可リストに登録された virtualenv/Conda コンテキストヒント;

• 明示的に宣言された入力/出力成果物バージョンと直接の来歴。

コレクターはグレースフルに劣化します。Git、NVIDIA ツール、GPU、環境ヒント、または実行可能ファイルの解決が欠落しても、ワークロードは停止しません。任意の環境変数は永続化されないため、認証情報とトークンはデフォルトではキャプチャされません。

失敗および中断されたコマンドは、bourne がそのプロセスセマンティクスを返す前に保存されます:

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

POSIX システムでは、Bourne は専用のプロセスグループを使用するため、Ctrl+C は通常、無関係なプロセスを対象とせずに子孫プロセスを終了します。

実行の成功は検証ではなく、決定的な成果物検証は一般的な科学的妥当性ではありません。Bourne はこれらの状態を別々に記録します。

ローカルストレージと移行

デフォルトの SQLite パスは:

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

プロジェクト固有のデータベースを使用するには:

export BOURNE_DB=/path/to/experiments.sqlite3

このリリース候補で v0.1.1、v0.2.0、v0.3.0、または v0.4.0 データベースを開くと、スキーマ5までの決定的なトランザクション移行が実行されます。既存の実験、成果物、来歴、インベントリ、ワークロード、計画、実行、スケジューラジョブ、割り当て、イベント、および実験リンクは読み取り可能なままです。移行は v0.4 レコードに対して ExecutionRequest 履歴を発明しません。未知または新しいスキーマバージョンは明示的に失敗します。Bourne は既存のデータベースをリセットすることはありません。新しい探索のたびに、別個の不変スナップショットが作成されます。

ライセンス

Project Bourne v0.5.0 以降は Apache License 2.0 の下で配布されます。v0.4.0 までのリリースは、リリース時の MIT ライセンス条件の下に留まります。詳細についてはライセンス履歴を参照してください。

リリース検証

リポジトリバージョンは 0.6.0 です。ベースランタイムにはサードパーティの依存関係がゼロです。MCP サポートは明示的なオプションの追加機能のままです。

ソースツリーテストを実行するには:

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

stdout と stderr は、最終的な永続化の前に依然としてメモリ内に蓄積されます。ディスクスプールされた実験ログ、自動アーティファクト検出、アーティファクトのアーカイブ、自動的な科学依存関係のインストール、自動モジュール読み込み、コンテナオーケストレーション、SSH 実行、リモートコピー、利用状況サンプリング、プロファイリング、任意の検証スクリプト、広範な科学的妥当性の推論、ホスト型 HTTP MCP、組み込み LLM、自然言語解析は、v0.6.0 の範囲外です。長期的な方向性については docs/VISION.md を参照してください。