Digital Passport Assessment Workbench

デジタルパスポートモデル評価ワークベンチ

デジタルパスポートのデータモデルを SHACL に基づいて評価し、構成済みソリューションをペアごとに比較し、SHACL のみを使用してユースケースのカバレッジを分析するための Python ツールキットとシンプルな CLI です。

この README は主に、リポジトリと開発のエントリーポイントです。ユーザー向けの概念および使用方法のリファレンスは、公開ドキュメントサイトにあります。リポジトリ内のソースドキュメントは引き続き docs/ から利用できます。

---

このリポジトリの内容

• CLI エントリーポイント dpawb を備えた、公開可能な Python パッケージ
• シンプルな stdio MCP サーバーのエントリーポイント dpawb-mcp
• 構成プロファイル、ユースケース、アラインメント用の契約準拠の入力スキーマ
• 検出コマンドから利用できる組み込みの語彙とテンプレート
• テストと検証にのみ使用する合成ローカルフィクスチャ
• 人間および AI エージェント向けチュートリアル用の、段階的なサンプルツリー

ツールの構成

このツールは主に、シンプルな CLI を備えた、エージェントが利用可能な分析ツールキットとして設計されています。コアとなるコマンドは次のとおりです。

• assess
• coverage
• compare
• prioritize
• recommend-composition
• schema
• vocabulary
• template
• capabilities
• summarize

AI エージェントでの利用

主な統合方法として想定しているのは、AI エージェントがパッケージ API または CLI を通じて分析パイプラインをオーケストレーションすることです。具体的には、次のようになります。

• 決定論的なファイルベースの入力
• エージェントによる解析や連結に適した JSON 出力
• チャット指向のインターフェースではなく、明示的な分析手順

CLI は人間が直接実行する場合にも便利ですが、主な製品形態は、エージェントスキル、ワークフローランナー、またはツールアダプターから呼び出せる分析エンジンです。

このパッケージには、同じ決定論的なコマンドを提供する、シンプルな stdio MCP サーバーも含まれています。

• assess
• coverage
• compare
• prioritize
• recommend-composition
• schema
• vocabulary
• template
• capabilities
• summarize

MCP のインターフェースは意図的にシンプルに保っています。

• コアの Python パッケージとして dpawb を維持する
• dpawb-mcp を通じて同じ操作を公開する
• MCP ランタイムを、ローカルの Python エントリーポイントと GitHub Container Registry イメージの両方で提供する
• GitHub ミラーからレジストリのメタデータを公開する

MCP ランタイムと公開形態については、公開されている MCP サーバーページで説明しています。

公開 Python API については、公開 API リファレンスで説明しています。

MCP へのアクセス

MCP サーバーは次の識別情報で公開されています。

• レジストリ名：io.github.CE-RISE-software/dpawb
• OCI イメージのパターン：ghcr.io/ce-rise-software/dpawb-mcp:<release-version>
• トランスポート：stdio
• 公式レジストリのベース URL：https://registry.modelcontextprotocol.io/

サーバーは、公式 MCP Registry で io.github.CE-RISE-software/dpawb という名前で検出できます。

レジストリの検索ページ：

• https://registry.modelcontextprotocol.io/?q=dpawb

ローカルクライアントの設定例：

{
  "mcpServers": {
    "dpawb": {
      "command": "dpawb-mcp"
    }
  }
}

OCI 向けのレジストリメタデータは server.json で宣言されています。公開ワークフローでは、公開時にリリースバージョンとイメージタグが設定されます。

インストール

python -m venv .venv
. .venv/bin/activate
pip install -e .

公開パッケージ名：

pip install dpawb

インストールされる MCP サーバーのコマンド：

dpawb-mcp

制限された環境で作業している場合、このパッケージは setuptools を使ってビルドするよう設定されているため、編集可能インストールで追加のビルドバックエンドを取得する必要はありません。

ビルド分離または wheel のサポートをローカルで利用できない場合は、次を使用してください。

python -m pip install --no-build-isolation -e .

制約のある環境で、ローカルの Python パッケージングツールにより編集可能インストールがブロックされる場合でも、このリポジトリではリポジトリ標準の実行方法を利用できます。

./scripts/run-local.sh capabilities
./scripts/test-local.sh
make smoke
make test
make validate

最小限のローカル MCP ランタイムコマンド：

python -m dpawb.mcp_server

コマンドの例

dpawb assess --profile fixtures/profiles/synthetic_evolution_latest.yaml
dpawb coverage --profile fixtures/profiles/synthetic_evolution_latest.yaml --use-case fixtures/use_cases/product_identity_lookup.yaml
dpawb compare --left left_assessment.json --right right_assessment.json
dpawb recommend-composition --left left_assessment.json --right right_assessment.json --comparison comparison_result.json
dpawb summarize --result comparison_result.json --format markdown
dpawb capabilities

ローカルリリースの確認

PyPI CI/CD を接続する前に、wheel を利用できる環境でローカルのパッケージングチェックを実行してください。

make release-check

このチェックでは wheel と sdist をビルドし、クリーンな一時環境に wheel をインストールして、インストール済み CLI のスモークチェックを実行します。

構成

このリポジトリには、用途の異なる入力領域が 2 つあります。

• fixtures/ 合成データのみを含む、リポジトリ内のテストデータです。 これらのファイルは、テスト、スモークチェック、CI 検証で使用されます。

• examples/01-source-ingestion/ 手動実行を目的とした、実際のソースの入力例です。 チュートリアルの最初のステップにあたり、CI 検証の対象ではありません。

examples ツリー全体は、入力データモデルではなく分析タスクごとに構成されています。

• examples/01-source-ingestion/ 宣言されたプロファイルを読み込み、評価します。
• examples/02-structural-comparison/ 2 つのプロファイル評価結果を比較します。
• examples/03-reduced-use-case-comparison/ 最初の整合済みユースケース比較を実行します。
• examples/04-extended-use-case-comparison/ より広範な整合済みユースケース比較を実行します。
• examples/05-composition-recommendation/ 評価済みの 2 つのモデルセットから、組み合わせたプロファイルを推奨します。

各例は、人間が手順に沿ってコマンドを実行するチュートリアルとしても、AI エージェントが明示されたファイルを使って決定的な手順を実行するレシピとしても利用できます。

ソース取り込みの例

実際の SHACL ソース向けのプロファイル例は、次の場所にあります。

• examples/01-source-ingestion/profiles/battery_dpp_representation_live.yaml
• examples/01-source-ingestion/profiles/battery_product_identification_live.yaml
• examples/01-source-ingestion/profiles/dp_record_metadata_live.yaml
• examples/01-source-ingestion/profiles/traceability_and_life_cycle_events_live.yaml
• examples/01-source-ingestion/profiles/metadata_focused_composition_live.yaml
• examples/01-source-ingestion/profiles/metadata_and_traceability_live.yaml
• examples/02-structural-comparison/profiles/metadata_slice_left_live.yaml
• examples/02-structural-comparison/profiles/metadata_slice_right_live.yaml

単一の実際のソースを使用する場合は、メタデータ中心の例が主な出発点です。

./scripts/run-local.sh assess --profile examples/01-source-ingestion/profiles/dp_record_metadata_live.yaml

組み合わせたプロファイルを使用する場合は、次を使ってください。

./scripts/run-local.sh assess --profile examples/01-source-ingestion/profiles/metadata_and_traceability_live.yaml

トレーサビリティのみの例も実行できます。

./scripts/run-local.sh assess --profile examples/01-source-ingestion/profiles/traceability_and_life_cycle_events_live.yaml

手動でカバレッジを確認するためのユースケース例は、次の場所にあります。

• examples/01-source-ingestion/use_cases/battery_dpp_representation.yaml
• examples/01-source-ingestion/use_cases/battery_product_identification.yaml
• examples/01-source-ingestion/use_cases/battery_passport_metadata_and_classification.yaml
• examples/01-source-ingestion/use_cases/record_identity_lookup.yaml
• examples/01-source-ingestion/use_cases/provenance_actor_lookup.yaml

例：

./scripts/run-local.sh coverage \
  --profile examples/01-source-ingestion/profiles/dp_record_metadata_live.yaml \
  --use-case examples/01-source-ingestion/use_cases/record_identity_lookup.yaml

比較ドライバーとして中心となる実際のユースケースは、次のとおりです。

• examples/01-source-ingestion/use_cases/battery_dpp_representation.yaml

意図的に対象を絞っています。次の項目が必要です。

• パスポートの識別情報
• バッテリーの識別情報
• パスポートのバージョンまたは改訂
• 担当者 1 名
• バッテリーの種類または分類を示す情報 1 つ

さらに、これらを 1 つのバッテリー DPP 表現の一部として扱うために必要な結合も対象とします。

このユースケースに対応する、最初に使用する構成は次のとおりです。

• examples/01-source-ingestion/profiles/battery_dpp_representation_live.yaml

現在、次の項目を組み合わせています。

• dp_record_metadata
• traceability_and_life_cycle_events

これは、バッテリー DPP の比較作業における、現時点でのより広範なベースラインです。 最初の縮小版実データ検証では、ID に焦点を絞った比較対象を使用します。

• 正式なサンプルフォルダー： examples/03-reduced-use-case-comparison/
• ユースケース： examples/03-reduced-use-case-comparison/use_cases/use_case.yaml
• 左側のプロファイル： examples/03-reduced-use-case-comparison/profiles/left_profile.yaml
• 右側のプロファイル： examples/03-reduced-use-case-comparison/profiles/right_profile.yaml

この縮小版の対象は、次の要素を組み合わせています。

• dp_record_metadata
• product_profile
• traceability_and_life_cycle_events

また、BatteryPass General Product Information モデルに対する、製品識別比較として初めて検証された対象です。

より広範な、2 つ目の検証済み対象も含まれています。

• 正式なサンプルフォルダー： examples/04-extended-use-case-comparison/
• ユースケース： examples/04-extended-use-case-comparison/use_cases/use_case.yaml
• 左側のプロファイル： examples/04-extended-use-case-comparison/profiles/left_profile.yaml
• 右側のプロファイル： examples/04-extended-use-case-comparison/profiles/right_profile.yaml

この対象では、同じ CE-RISE の組み合わせモデルセットを維持しつつ、パスポートのバージョン／リビジョンとバッテリーの種類／分類を追加しています。

現在、エコシステム間の検証に関する次の 2 つの注記があります。

• examples/03-reduced-use-case-comparison/notes/comparison_note.md
• examples/04-extended-use-case-comparison/notes/comparison_note.md

これらのサンプルの手順を追ったユーザー向けリファレンスは、公開されているサンプルアプリケーションガイドにあります。

手動で比較を実行する場合は、同じ宣言済みスコープラベルを持つ、比較可能なライブペアが含まれています。

• examples/02-structural-comparison/profiles/metadata_slice_left_live.yaml
• examples/02-structural-comparison/profiles/metadata_slice_right_live.yaml
• examples/02-structural-comparison/alignments/metadata_slice_alignment.yaml は、出発点となるアライメントの例です

一般的な流れ：

./scripts/run-local.sh assess --profile examples/02-structural-comparison/profiles/metadata_slice_left_live.yaml --output /tmp/left.json
./scripts/run-local.sh assess --profile examples/02-structural-comparison/profiles/metadata_slice_right_live.yaml --output /tmp/right.json
./scripts/run-local.sh compare --left /tmp/left.json --right /tmp/right.json

アナリストが明示的に作成したアライメントを使用する場合：

./scripts/run-local.sh compare \
  --left /tmp/left.json \
  --right /tmp/right.json \
  --alignment examples/02-structural-comparison/alignments/metadata_slice_alignment.yaml

アライメントファイルを指定すると、比較結果にアライメントを中心とした次の 2 つのビューが含まれるようになりました。

• evaluated_pairs 宣言された各同等性について、ペアごとの完全な存在状況を示します。

• ranked_alignment_observations 宣言されたペアの一方にのみ存在する、または両方に存在しない項目のうち、レビューが必要なギャップを示します。

そのため、アライメントを考慮した比較結果で主に確認すべき項目は次のとおりです。

• alignment_coverage_ratio
• evaluated_pairs
• ranked_alignment_observations

その比較結果を prioritize に渡すと、これらのアライメントギャップも、優先順位付けされた改善目標として直接表示されます。

現在の分析コアは、設計上引き続き保守的ですが、トークンの照合だけにとどまらない分析が可能になりました。

• 矛盾検出では、直接的なカーディナリティの競合と、データ型とオブジェクト参照の競合を対象としています
• 項目のカバレッジでは、SHACL パス、所有者シェイプ、ターゲットクラスのエビデンスを使用します
• 結合のカバレッジは、共有する所有者シェイプ、明示的なシェイプ間オブジェクト参照パス、または、それが意図された分析上の解釈である場合にはレコードレベルの取得コンテキストによって満たすことができます

リポジトリの構成

• src/dpawb/：パッケージ、CLI、分析オペレーション
• src/dpawb/data/：同梱されたスキーマ、語彙、テンプレート
• fixtures/：テスト専用の、リポジトリ内にある合成モデル、プロファイル、ユースケース、アライメント
• examples/01-source-ingestion/：手動実行用のソース取り込みプロファイル、ユースケース、アライメント
• examples/03-reduced-use-case-comparison/：自己完結型の、アライメントされたユースケース比較サンプル
• examples/05-composition-recommendation/：自己完結型の構成推奨サンプル
• scripts/：リポジトリ標準の実行・テスト用ヘルパー
• .github/workflows/validate.yml と .forgejo/workflows/validate.yml：リポジトリ標準の手順による CI 検証

ライセンス

欧州連合公共ライセンス v1.2（EUPL-1.2）に基づいてライセンスされています。

貢献

このリポジトリはCodebergで管理されています。こちらが正式な唯一の情報源です。GitHubリポジトリは、リリースのアーカイブおよびZenodoとの連携に使用する読み取り専用ミラーです。イシューおよびプルリクエストはCodebergで作成してください。

---

欧州連合の助成を受けて実施（助成契約番号：101092281 — CE-RISE）。
表明された見解および意見は著者のみのものであり、必ずしも欧州連合または助成機関（HADEA）の見解を反映するものではありません。
欧州連合および助成機関は、これらについて一切責任を負いません。

© 2026 CE-RISEコンソーシアム。
欧州連合公共ライセンス v1.2（EUPL-1.2）に基づきライセンスされています。
クレジット表記：CE-RISEプロジェクト（助成契約番号：101092281）および記載のとおり、個々の著者／パートナー。

CE-RISEプロジェクトの一環として、NILU（Riccardo Boero — [email protected]）が開発しました。