docling-graph

Docling Graph

このスキルは、タスクがDocling Graphに特化している場合に使用します。ドキュメントを型付きのPydanticナレッジグラフに変換する、テンプレートをレビューする、抽出コントラクトを選択する、パイプライン構成を調整する、抽出の実行結果を調査・デバッグする、グラフ出力をエクスポートするといったタスクが対象です。

一般的なDoclingドキュメントの解析、ベクトルのみを使うRAG、グラフデータベースの管理、Docling Graphの実行を伴わないオントロジーのみのモデリング、または無関係なPDFツールには使用しないでください。

振り分け

$ARGUMENTS は [mode] [source-or-template-or-question] [options] として解釈します。$ARGUMENTS が空の場合、ドキュメント、プロバイダー、抽出コントラクトを決めつけず、不足している最小限のコンテキストを尋ねてください。

$ARGUMENTS のパターン	モード	提供する内容
plan [documents/domain]	Plan	エンドツーエンドのワークフロー計画、テンプレート戦略、プロバイダー／構成の選択、検証手順
template [domain]	Template	安定したIDとリレーションシップのヒントを含むPydanticグラフテンプレート、またはレビュー所見
`contract [direct	staged	delta] [domain]`
convert [source] [template]	Convert	入力、プロバイダー／モデルのオーバーライド、出力パス、検証を含むCLI／APIの実行手順
api [source] [template]	API	PipelineConfig と明示的なオーバーライドフィールドを使用したPython連携
inspect [output-path]	Inspect	既存または予定している出力ディレクトリのHTML／デバッグ調査手順
export [output]	Export	JSON／CSV／Cypher／NetworkXへのエクスポートと、エクスポート後のチェック
debug [error-or-output]	Debug	ログ、debug/trace_data.json、ステージ成果物、スキーマチェックを使った根本原因の特定手順
batch [folder]	Batch	多数のドキュメント向けのスケーリング計画、マニフェスト、再試行、冪等性、QAサンプリング
自然言語	自動判定	まず分類し、一致するモードを実行
空／不明確	確認	ドキュメントの種類、対象グラフ、実行環境、プロバイダーの制約を尋ねる

自動判定

1. direct、staged、delta、抽出コントラクト、構造化出力、スキーマ強制、sparse checks、gleaning、またはストリーミングに言及している場合 -> Contract。
2. inspect、HTMLレポート、trace_data.json、デバッグ成果物、出力ディレクトリのレビュー、または失敗したグラフマッピングに言及している場合 -> Inspect または Debug。
3. Pydanticモデル、BaseModel、Field、リレーションシップ、エンティティ、または edge() に言及している場合 -> Template。
4. コマンドライン、docling-graph convert、プロバイダー／モデルのフラグ、ソースファイルのパス、または出力ディレクトリに言及している場合 -> Convert。
5. PipelineConfig、run_pipeline、Python連携、provider_override、model_override、またはプログラムからの実行に言及している場合 -> API。
6. グラフのエクスポート、Cypher、Neo4j、NetworkX、CSV、またはグラフJSONに言及している場合 -> Export。
7. フォルダー、多数のPDF、再試行、スループット、マニフェスト、またはQAサンプリングに言及している場合 -> Batch。
8. それ以外の場合は、ワークフローを提示する前に簡潔な確認質問を1つ尋ねてください。

ギャラリー

ユーザーからの依頼	応答パターン
"SEC filings用のテンプレートを作成して"	グラフIDフィールド、リレーションシップフィールド、抽出に関する注記、検証チェックリストを含むPydanticモデルを作成します。
"これは段階的な抽出にするべき？"	スキーマのサイズ、ネスト、カーディナリティ、プロバイダーの制限、デバッグコストを踏まえて、direct、staged、deltaのコントラクトを比較します。
"このPDFをOpenAIで実行して"	プロバイダー／モデルのオーバーライドと出力チェックを含む docling-graph convert コマンドと、同等のAPIの例を提示します。
"この出力フォルダーをレビューして"	inspect、グラフJSON、debug/trace_data.json、ステージ成果物、スキーマ／sparse-checkの結果を順に確認します。
"グラフにリレーションシップがありません"	テンプレートのリレーションシップモデリング、抽出コントラクト、構造化出力のフォールバック、gleaning、グラフマッピングの成果物を調査します。
"Neo4jにエクスポートして"	一意性制約、IDの正規化、リレーションシップ数のチェックを含むエクスポート手順を作成します。

ワークフロー

1. スコープを分類する

すべての回答は、タスクが Docling Graph 固有かどうかを判断することから始めてください。

• 対象範囲内：文書から型付きナレッジグラフを抽出すること、Pydantic グラフテンプレート、docling-graph CLI/API の実行、抽出コントラクト、検査／デバッグ用アーティファクト、グラフのエクスポート。
• 対象範囲外：通常の Docling 変換、埋め込みのみのパイプライン、汎用 LLM 抽出、グラフデータベースのチューニング、Docling Graph を実行しないオントロジー設計。

対象範囲外の場合は、その境界を明示し、最も適切なスキルまたはワークフローを提案してください。

2. 必要最小限の入力を収集する

回答内容を左右する不足情報だけを尋ねてください。

• 文書の種類と例：PDF／HTML／DOCX／画像、想定される長さ、スキャン文書かデジタル文書か、表の密度。
• グラフの対象：エンティティ、関係、ID、必須フィールド、下流の利用者。
• テンプレートの状態：なし、Pydantic モデルの草案、既存のパッケージ／モジュール、または動作しないテンプレート。
• 実行環境：CLI、Python API、バッチジョブ、CI、またはノートブック。
• プロバイダーの制約：OpenAI、Mistral、Gemini、Watsonx、ローカルの Ollama／vLLM／LM Studio、プライバシー／コスト／レイテンシの制限。
• 抽出コントラクト：direct、staged、delta、または未定。
• デバッグのコンテキスト：コマンド／API の設定、出力ディレクトリ、ログ、debug/trace_data.json、正確なエラー。

3. 抽出コントラクトを選択する

Docling Graph は、3 種類のコントラクト形式をサポートしています。複雑なワークフローでは、選択を明示してください。

コントラクト	使用する場面	主なリスク	必須のチェック
direct	小規模で安定したスキーマ、限定的なネスト、プロバイダーがスキーマ全体を一度の処理で扱える場合	コンテキストの超過、関係の網羅性不足	スキーマへの適合性、スパースチェックの結果、フィールドの網羅性
staged	明確なセクションまたはネストされたエンティティグループを含む大規模なテンプレート	ステージの境界でステージ間のリンクが欠落する可能性	ステージの出力、ルートのマージ規則、関係の数
delta	複雑で高カーディナリティのグラフ、ソースの順序が不明確な場合、または段階的なエンリッチメント	リゾルバーの品質と安定した ID が正確性を大きく左右する	ID 戦略、リゾルバーの設定、エンティティの重複チェック

プロバイダーがサポートしている場合は、構造化出力とスキーマ強制を優先してください。利用できない、または不安定な場合は、フォールバックパーサー、スパースチェックの設定、追加の検証パスを記録してください。再現率を重視する抽出では gleaning を使用し、長時間の実行で進行状況をリアルタイムに確認したり、キャンセルの状況を把握したりする必要がある場合は、LLM ストリーミングを有効にしてください。

4. モードのプロトコルを適用する

Plan

以下を返してください。

1. 文書とグラフに関する前提。
2. テンプレートの概要と安定した ID の戦略。
3. コントラクトの選択と、direct／staged／delta を選んだ理由。
4. CLI/API の実行環境、プロバイダー／モデルのオーバーライド、構造化出力の方針。
5. 検証パス：テンプレートの lint、ドライラン、検査レポート、グラフの不変条件、エクスポートのチェック。
6. 運用パス：バッチマニフェスト、再試行、冪等な出力、トレース、サンプルレビュー。

Template

Pydantic の BaseModel クラスを使用してください。以下を優先してください。

• 抽出対象のすべてのフィールドに、説明的な Field(..., description=...) メタデータを指定する。
• model_config = ConfigDict(json_schema_extra={"graph_id_fields": [...]}) またはプロジェクトがサポートする同等の方法を使って、安定したグラフ ID を設定する。
• 関係フィールドは、エンティティモデルまたはエンティティモデルのリストとして型付けする。
• 利用できる場合は、edge() などの Docling Graph ヘルパーを使って、関係の意味を明示する。
• 文書レベルのグラフを記述し、トップレベルの関係コレクションを公開するルートモデルを使用する。

以下は避けてください。

• グラフの中核となるエンティティに、型指定のない dict／Any のデータを使用する。
• ソースの根拠がない、または安定した ID がない関係フィールド。
• staged／delta コントラクトを使わずに、モデルのリストを過度に深くネストすること。
• 抽出順、ページ番号、またはモデルが生成したラベルだけに基づく ID。

契約

次の項目を含む推奨表を返してください。

• 選択した契約とフォールバック契約。
• 契約に必要なスキーマ変更。
• 設定するパイプラインのフラグ／設定フィールド。
• 想定されるデバッグ成果物とその確認方法。
• 契約の切り替えを促すべき失敗モード。

単純な抽出には direct、自然に分解できるテンプレートには staged、多数の観測結果をまたいでエンティティ／関係を解決しないと正確性を確保できない場合には delta を使用してください。

変換

CLI コマンドと検証のフォローアップの両方を提示してください。CLI のフラグ名と API のフィールド名を区別してください。

docling-graph convert SOURCE_PATH \
  --template TEMPLATE_MODULE:RootModel \
  --output-dir OUTPUT_DIR \
  --provider PROVIDER \
  --model MODEL \
  --extraction-contract direct \
  --schema-enforced-llm \
  --structured-sparse-check \
  --llm-streaming \
  --show-llm-config

続いて、ユーザーに次の項目を確認するよう指示してください。

• OUTPUT_DIR/graph.json または設定済みのグラフ成果物。
• デバッグダンプが有効な場合は OUTPUT_DIR/debug/trace_data.json。
• HTML レビューレポートを生成する docling-graph inspect OUTPUT_DIR。
• 関係数、孤立エンティティ、重複 ID、必須フィールドの充足率。

API

明示的な設定と型付きパスを優先してください。

from pathlib import Path

from docling_graph import run_pipeline
from docling_graph.pipeline import PipelineConfig

from templates.sec import FilingGraph

config = PipelineConfig(
    source=Path("filing.pdf"),
    output_dir=Path("out/filing"),
    template=FilingGraph,
    provider_override="openai",
    model_override="gpt-4.1-mini",
    extraction_contract="staged",
    structured_output=True,
    structured_sparse_check=True,
    llm_streaming=True,
    gleaning_enabled=True,
    gleaning_max_passes=2,
    dump_to_disk=True,
    debug=True,
)

context = run_pipeline(config)

上流 API の正確な名前がインストールされているバージョンによって異なる場合は、インストール済みのドキュメント／ヘルプを確認して適宜調整してください。プロバイダー／モデルの上書き、契約の選択、構造化出力ポリシー、gleaning、ストリーミング、デバッグダンプの概念上の区分を維持してください。

確認

出力フォルダーのレビューやデバッグの引き継ぎを準備する際は、inspect を使用してください。

docling-graph inspect OUTPUT_DIR

次の項目を確認してください。

• 抽出ステージ、エラー、モデル呼び出し、グラフマッピングを示す HTML サマリー。
• ステージの入力／出力、フォールバック経路、構造化出力の失敗、疎性チェックの結果を示す debug/trace_data.json。
• ルートエンティティ数、関係数、孤立ノード、重複 ID、必須フィールドの欠落を示すグラフ成果物。
• 意図した設定だけでなく、実際に使用されたプロバイダー／モデルの設定。

エクスポート

エクスポート形式は後続の用途に合わせてください。

• JSON：正規成果物、回帰テスト用フィクスチャ、API への引き継ぎ。
• CSV：アナリストによるレビュー、関係テーブル、インポート準備。
• Cypher/Neo4j：一意性制約を適用したグラフデータベースへの読み込み。
• NetworkX：アルゴリズムによるチェック、連結成分、中心性、到達可能性。

エクスポートを引き継ぐ前に、安定した ID、関係の方向、重複ノード、件数を inspect レポートと照合してください。

デバッグ

次の順序でデバッグしてください。

1. インストール済みの docling-graph のバージョン、Python のバージョン、プロバイダーの認証情報、CLI/API コマンドを確認します。
2. ルートモデル、安定した ID、フィールドの説明、関係タイプ、契約との適合性について、テンプレートを lint します。
3. デバッグダンプを有効にし、少量のソースサンプルを使って再現します。
4. debug/trace_data.json を確認し、構造化出力のフォールバック、疎性チェックの失敗、ステージ／delta リゾルバーの見落とし、グラフマッピングのエラーを調べます。
5. ソースの根拠 → 抽出された JSON → グラフ成果物 → エクスポート成果物の順に比較します。
6. テンプレートのフィールド説明、契約の切り替え、プロバイダー／モデルの上書き、gleaning パス、リゾルバーの設定、エクスポートマッピングのいずれかから、最小限の修正を提案します。

バッチ処理

多数のドキュメントを処理する場合は、次の項目を指定してください。

• ソースパス、テンプレート、契約、プロバイダー／モデル、出力ディレクトリ、再試行状態を含むマニフェスト形式。
• 冪等な出力ディレクトリと再開可能な実行。
• コンプライアンス上すべてのトレースが必要な場合を除き、失敗した場合に限りドキュメントごとのトレースを保持します。
• ドキュメントのクラスと失敗のクラスごとの QA サンプリング。
• 集計チェック：必須フィールドの充足率、関係密度、重複 ID、プロバイダーのコスト、レイテンシ、フォールバック率。

ヘルパースクリプト

このスキルには、任意で使用できるローカルヘルパーが含まれています。

uv run python skills/docling-graph/scripts/check-env.py --provider openai --format json
uv run python skills/docling-graph/scripts/lint-template.py path/to/template.py --root FilingGraph --format json

ヘルパーは参考用です。インストール済みの docling-graph CLI/API を実行し、実際の出力を確認する代わりに使用してはいけません。

参考資料

参考ファイル	読み込むタイミング
references/template-design.md	Pydantic グラフテンプレート、安定した ID、関係フィールド、段階的／差分モデリングを作成またはレビューする場合
references/pipeline-configuration.md	コントラクト、プロバイダー／モデルのオーバーライド、構造化出力、グリーニング、ストリーミング、デバッグダンプを選択する場合
references/cli-api-recipes.md	CLI／API の実行パターン、検査ワークフロー、バッチマニフェストを作成する場合
references/export-graph-management.md	JSON／CSV／Cypher／NetworkX へのエクスポートとグラフ整合性チェックを計画する場合
references/debugging.md	トレース、検査レポート、グラフマッピングの失敗、成果物の引き継ぎをデバッグする場合

標準用語

標準用語です。必ず次の表記を使用してください。

標準用語	意味
direct contract	ソースの根拠からルートグラフスキーマへ、1 回のパスで抽出すること
staged contract	抽出を複数の段階出力に分解し、それらをルートグラフにマージすること
delta contract	観測優先で抽出し、エンティティ／関係を解決してグラフに取り込むこと
structured output	プロバイダーがサポートするスキーマ強制、またはそれに相当する制約付き生成
sparse check	スキーマフィールドの欠落または不足を特定する検証パス
gleaning	エンティティと関係の再現率を高める、回数を制限した追加パス
inspect report	出力ディレクトリから作成される、人が読めるレビュー用の画面
trace data	ソース、抽出、マッピング、グラフ出力をつなぐ debug/trace_data.json などのデバッグ成果物

段階的な情報開示

リクエストで必要な場合にのみ、参考資料を読み込みます。

1. ディスパッチ、スコープ、モードのプロトコルについて、このスキル本文から始めます。
2. 現在のモードに対応する参考ファイルを 1 つ開きます。
3. ローカルチェックの実行を求められた場合、またはスキルのメンテナンス時にのみ、ヘルパースクリプトを開きます。
4. スコープの簡単な振り分けや 1 コマンドで済む回答では、すべての参考資料を読み込まないでください。

拡張方針

Docling Graph の作業を拡張する際は、モデルの複雑さを増す前に運用上の制御を強化します。

規模	方針
小規模	デバッグダンプと検査出力を使い、代表的な文書を 1 つ検証します
中規模	マニフェスト、冪等な出力、再試行、サンプル QA を追加します
大規模	集計メトリクス、トレース保持ポリシー、段階的な昇格を伴うバッチ実行を使用します
100 件以上のファイル	単一文書の不変条件テストスイートに合格した後にのみ、マニフェストのシャード単位で並列化します

1. デバッグダンプと検査出力を使い、代表的な文書を 1 つ検証します。
2. バッチ用に、ソース、テンプレート、コントラクト、プロバイダー／モデル、出力パス、ステータスを含むマニフェストを追加します。
3. 出力を冪等かつ再開可能にします。
4. 失敗したケースと、サンプリングした成功ケースのトレースを保持します。
5. 必須フィールドの網羅率、関係の密度、重複 ID、孤立した関係、フォールバック率、コスト、レイテンシを集計します。
6. サンプリングしたセットでグラフの不変条件に合格した後にのみ、より大きなバッチへ進みます。

検証コントラクト

変更の完了を宣言する前に、このスキルディレクトリから実行します。

python scripts/check.py
python -m py_compile scripts/check-env.py scripts/lint-template.py
pytest -q tests/test_docling_graph_skill.py
git diff --check

完了条件：

1. scripts/check.py が終了コード 0 で終了すること。
2. ヘルパースクリプトがコンパイルされ、対象を絞ったテストに合格すること。
3. git diff --check が終了コード 0 で終了すること。
4. このスキルディレクトリ内に、ポータブル CLI に関する違反が残っていないこと。

スキル定義、公開説明、参考ファイル、または評価の動作を変更した後は、利用可能であれば docs-steward を呼び出します。

重要なルール

1. Docling Graph のスコープは狭く保ち、汎用的な解析やグラフデータベースに関する質問は適切な先へ案内します。
2. CLI フラグと Python API のフィールドを区別します。
3. グラフの品質を主張する前に、ID、必須フィールド、関係、デバッグ／検査の成果物を確認します。
4. 利用可能な場合は構造化出力／スキーマ強制を優先し、フォールバック時の動作も明記します。
5. 複雑なテンプレートでは、direct、staged、delta のいずれを使用するか明示的に選択します。
6. デバッグ時の引き継ぎでは、ソースの根拠へのパスを保持します。
7. コマンド、ログ、例、トレース、生成された設定からシークレットを削除します。