fair-simulation-packager

FAIR Simulation Packager

目標

材料シミュレーションの結果について、別の人やエージェントが、何をどの入力で実行したのか、また出力をどのように解釈すべきかを理解できるよう、最小限の再現性マニフェストを作成します。

要件

• Python 3.10+
• 外部依存関係なし
• Linux、macOS、Windows で動作

収集する入力

入力	説明	例
プロジェクト名	人が読みやすいバンドル名	al-cu-diffusion-study
エンジン	シミュレーションコード	LAMMPS、VASP、MOOSE
入力ファイル	再実行に必要なファイル	in.lammps,data.lmp
出力ファイル	結果の検証に必要なファイル	log.lammps,traj.dump
構造 ID	データベースまたはローカルの識別子	mp-149
単位	フィールドと単位の対応付け	energy=eV,length=angstrom

判断の指針

• 入力ファイル、出力ファイル、コードのバージョン、単位は必ず含めてください。
• ローカルに存在するすべてのファイルについて、ハッシュを含めてください。
• Materials Project、NOMAD、OPTIMADE、CIF、POSCAR、または内部データベースのレコードを使用する場合は、構造識別子を含めてください。
• 不足しているファイルは、黙って除外するのではなく警告として記録してください。

スクリプトの出力

scripts/fair_packager.py --json は、トップレベルに 2 つのキーを持つエンベロープを出力します。

• inputs：解析された CLI 引数をそのまま返します（注：inputs.inputs はファイルごとのレコードではなく、--inputs で渡された生のカンマ区切り文字列です）。
• results：単一のキー manifest を含みます。

results.manifest には、次のフィールドが含まれます。

• project_name、engine、engine_version、structure_id、units
• file_inventory：inputs と outputs を含み、それぞれファイルごとのレコード（path、exists、ファイルが存在する場合は size_bytes と sha256）のリストです。
• missing_files：ディスク上に存在しないパス
• provenance（working_directory、manifest_schema）
• fair_checks：has_inputs、has_outputs、has_units、has_engine_version、has_hashes_for_existing_files（true／false。ファイルが存在せず、チェックが該当しない場合は null）
• recommended_next_steps

フィールドは results.manifest.<field> から解析してください。--out PATH が指定されている場合、PATH に書き込まれるのは manifest オブジェクトのみで、inputs／results のエンベロープは含まれません。

ワークフロー

python3 skills/data-management/fair-simulation-packager/scripts/fair_packager.py \
  --project-name al-cu-diffusion \
  --engine LAMMPS \
  --inputs in.lammps,data.lmp \
  --outputs log.lammps,traj.dump \
  --units energy=eV,length=angstrom,time=ps \
  --structure-id local:alcu-cell-001 \
  --json

ユーザーがマニフェストファイルの書き込みを希望する場合に限り、--out manifest.json を使用してください。

エラー処理

不足しているファイルは missing_files に報告されます（終了コード 0）。無効な入力がある場合は処理が停止し、終了コード 2 が返されます。該当するのは、不正な形式の単位エントリー、制御文字を含むフィールド、4096 文字を超えるフィールド、入力または出力のエントリーが 1000 件を超える場合、またはファイルサイズが 500 MB を超える場合です。通常のファイルパス（絶対パスや .. を含むパスも含む）は受け付けられ、インベントリーに記録されます。このツールはメタデータと SHA-256 ハッシュの計算にのみファイルの内容を読み取ります。

制限事項

このスキルはメタデータマニフェストを作成します。NOMAD、Materials Project、または OPTIMADE プロバイダーへのアップロードは行いません。

検証チェックリスト

• fair_checks.has_hashes_for_existing_files が true であることを確認しました（null または false ではありません）。null は、一覧にあるファイルがディスク上に存在しなかったことを意味します。そのため、マニフェストを信頼する前に、ファイルが実際に存在するディレクトリから再実行してください。
• missing_files を確認し、空であること、または各項目について明確な理由を記録したことを確認しました。欠落しているパスはすべて、入力／出力として指定されたもののハッシュ化されていないことを意味するため、このままではバンドルを再現できません。
• results.manifest.file_inventory 内の sha256 を少なくとも1つ抜き取り確認し、同じファイルに対して独立して実行した sha256sum／Get-FileHash と照合して、記録されたダイジェストがディスク上のバイト列と一致することを確認しました。
• engine_version が実際のバージョン文字列であり、デフォルトの "unknown" ではないことを確認しました。バンドルに正確なコードビルドを記録するため、--engine-version を指定してください。
• units が空でなく、報告されたすべての量（エネルギー、長さ、時間など）に項目があり、後続の利用者が単位系を推測する必要がないことを確認しました。
• Materials Project／NOMAD／OPTIMADE／CIF／POSCAR の構造を使用した場合、structure_id が設定されており、構造の識別情報を復元できることを確認しました。
• --out PATH を使用した場合は、PATH を開き、裸の manifest オブジェクト（inputs／results エンベロープではありません）が格納されていること、および意図しない作業ディレクトリ外のパスに書き込まれていないことを確認しました。

よくある落とし穴と誤った思い込み

つい選びたくなる近道	それが誤りである理由／すべきこと
「終了コードが0だったので、バンドルは完全です。」	終了コード0が意味するのは検証エラーがなかったことだけです。ファイルが欠落していても、終了コード0で missing_files に報告されます。完全性を信頼する前に、missing_files と fair_checks を確認してください。
「has_hashes_for_existing_files は null だけど、true とほぼ同じです。」	null は、一覧にあるファイルがディスク上に存在しなかったことを意味します。何もハッシュ化されていません。正しいディレクトリから再実行し、ファイルが見つかって実際にダイジェスト化されるようにしてください。
「--engine-version は省略しても、エンジン名だけで十分です。」	スクリプトでは engine_version のデフォルトが "unknown" となり、再現性が気付かないうちに損なわれます。必ず具体的なビルド／バージョンを指定してください。
「JSON の inputs.inputs を解析すれば、ファイルごとのレコードを取得できます。」	inputs.inputs は CLI で指定された生のカンマ区切り文字列をそのまま返したものであり、レコードではありません。ファイルごとのデータは results.manifest.file_inventory.inputs/outputs から読み取ってください。
「マニフェストに構造が記録されるので、実行を完全に再現できます。」	このスキルが記録するのは、ファイル、ハッシュ、単位、ID の一覧だけです。コードのコミット、コンテナのダイジェスト、パーサーのバージョンは記録しません。recommended_next_steps に従い、それらは自分で追加してください。
「絶対パスや .. は拒否されるので、インベントリはサンドボックス化されています。」	パスはサンドボックス化されていません。絶対パスや .. を含むパスも指定どおりにインベントリへ記録され、--out は作業ディレクトリ外に書き込むこともできます。指定するパスが意図したものか確認してください。

セキュリティ

入力の検証

• --project-name と --engine は必須であり、空白を除去した後に空であってはなりません。値が空の場合は、終了コード2で停止します。
• --project-name、--engine、指定された場合の --structure-id、および各ファイルパスは、制御文字（ord < 32）と4096文字の最大長について検査されます。いずれかの条件に該当すると、終了コード2で停止します。
• --inputs と --outputs はカンマで分割され、それぞれ最大1000項目に制限されます。項目数がそれを超えると、終了コード2で停止します。
• --units の項目は key=value 形式でなければなりません。キーと値の両方が、許可リスト ^[A-Za-z0-9_.:/@+-]+$ に一致する必要があります。= がない場合や、キー／値が一致しない場合は、終了コード2で停止します。
• 数値入力はないため、有限値／正の数値のチェックは行われません。

ファイルアクセス

• スクリプトは、存在する各入力／出力ファイルを 1 MB 単位で読み込み、size_bytes と SHA-256 ハッシュを計算します。存在しないファイルは記録されますが、読み込まれません。
• 500 MB を超えるファイルがある場合、ハッシュ計算の前に終了コード 2 で停止します。
• --out PATH が指定されない限り、スクリプトはファイルを書き込みません。指定された場合は、そのパスにマニフェスト JSON のみを 1 つ書き込みます。それ以外の場合、すべての出力は標準出力に送られます。
• パスはサンドボックス化されていません。棚卸し対象のファイルと --out のどちらについても、絶対パスや .. を含むパスを指定できます。--out が作業ディレクトリの外を指している場合は、指定どおりその場所にファイルが書き込まれます。

ツールの制限

• Bash を使用して、同梱の scripts/fair_packager.py を実行します。
• Read、Write、Grep、Glob は、ユーザーへの案内時にスキルが作業ディレクトリを調べたり、マニフェスト／メタデータファイルを読み書きしたりできるよう宣言されています。これらはスクリプト自体から呼び出されることはなく、スクリプトはすべてのファイル入出力を直接実行します。

安全対策

• eval、exec、os.system、subprocess の呼び出しはありません。スクリプトはシェルコマンドを実行せず、argparse で引数を解析します。
• 出力は json.dumps を使用して JSON 形式で出力されます（--json が指定されない場合は、短いプレーンテキストの概要が出力されます）。
• DoS 対策の上限により、リソースの使用量が制限されています。上限は、1 ファイルあたり 500 MB、入力／出力リストあたり 1000 件、フィールドあたり 4096 文字です。

参考資料

• 推奨されるマニフェストのフィールドについては、references/fair_manifest.md を参照してください。

バージョン履歴

• 1.2.0: コミット済みの evals/files/ フィクスチャに照らし、スクリプトの正確な --json 出力（ファイルごとの sha256／size_bytes、units、structure_id、engine_version、missing_files、および三値の has_hashes_for_existing_files）を固定することで、評価ケースを明確に区別できるようにしました。
• 1.1.0: 実際の --json エンベロープの形状を文書化しました。ファイルが存在しない場合は null になるよう、has_hashes_for_existing_files を三値にしました。エントリー数（1000）とフィールド長（4096）の上限を追加し、実際のパスの挙動を説明するよう「エラー処理」と「セキュリティ」の記述を修正しました。
• 1.0.0: FAIR シミュレーションのパッケージングスキルの初版。