ns-graphrag

GraphRAG プロセス

ns-postgres-rag が設計する検索レイヤー上で GraphRAG を構築するための、エンドツーエンドのプロセス知識です。

分析します。パイプラインを定義します。アプリケーションの言語や製品名は使いません。

ストレージ、インデックス、ハイブリッドランキング、再帰的なホップ上限、エビデンス／メンションの DDL、および Retrieval Design Report は ns-postgres-rag が担当します。このスキルが扱うのは、知識の抽出、永続化、クエリ、引用の方法です。

中心ルール

ホップとは、エビデンスの行を持つ保存済みの型付きエッジです。類似性から提案されるのは候補です。共起によってエッジが作成されることはありません。オペレーターのすべての回答は、原文のままのソース箇所を引用するか、回答を拒否します。拒否されたレコードは省略し、「アクセス権がない」と説明してはいけません。

正規ホップ（説明用のみ）：company → contract → invoice → payment。P0 でコーパスのチェーンを導出します。

ns-postgres-rag との分担

質問	担当
ベクター検索、ハイブリッド検索、GraphRAG のどれか？ DDL、HNSW、ホップ CTE、エビデンス／メンションテーブル、返却フィールド	ns-postgres-rag
オントロジー、抽出器の契約、ドキュメントの型付け、回答形式、引用、検索前 ACL、ディスカバリーゲート	このスキル

Gate 2 がリレーショナル GraphRAG でない場合は、停止してください。後で使うためのグラフテーブルを独自に考案してはいけません。

言語の禁止事項

指示、レポート、抽出器の契約では、概念（テキスト単位、保持される ID、論理エッジ、エビデンス、メンション、回答形式）を指定します。プログラミング言語、フレームワーク、UI キット、コンテナランタイム、ベンダーのモデル SKU は指定しないでください。指定するのはモデルの役割のみです：extract、embed、classify、summarize、compose。

SQL／DDL の形式は ns-postgres-rag のスニペットに記載します。

起動（必須）

1. ../../ns-harness/references/session-boot.md — セッション起動（ブロッキング）。
2. ../ns-postgres-rag/SKILL.md のルーティングと Gates 1–2 を読みます。承認済みの Retrieval Design Report がなく、モードが GraphRAG の場合は、まずそのレポートを記入するか、作成を求めてください。
3. コーパスの形式、既存のカダストルキー、権限モデル、質問の類型を調査します。
4. このスキルを続けます。

成功： インベントリを作成し、GraphRAG モードを正当化できています。失敗： オントロジーを定義する前に抽出器のプロンプトを作る、または N≥2 の分割チェーンの必要性がないのにグラフを作成することです。

フロー

起動 → P0 オントロジーを確定 → P1 非構造化データ → テキスト単位 + 品質ゲート → P2 スキーマを固定した抽出 → P3 ID を解決 → P4 論理エッジ + エビデンス + メンションを永続化 → P5 単位とエンティティの説明を埋め込み → P6 回答形式 + グラフ契約 → P7 GraphRAG Process Report → 人による承認 → ns-spec-driven。

任意のディスカバリー（引用付きの仮説。書き戻しなし）は、宣言済みの類型が6つの回答形式の範囲外にある場合に限ります — references/discovery-layer.md。

対話型クエリは取り込みジョブに優先します。取り込みは段階的に実行し、冪等性を保ち、段階ごとに再試行します。

P0 — オントロジーの確定（ブロッキング）

語彙は固定します。抽出器が型を独自に作成することはできません。導出手順（既成のリストではありません）：references/ontology.md。

抽出バッチを実行する前に確定します。

• ホストのレジストリスキーマに合わせたエンティティ型（固定リスト）。
• 宣言された質問のホップチェーンから導出した関係型（固定リスト、方向性のある意味）。
• 任意のクレーム／共変量型（プロンプトの調整が済むまで、既定では無効）。
• 型ごとの保持される ID キー（ID の階層）。メンションのみの型は明示します。
• すべての抽出バッチに付与するオントロジーバージョン ID。

オープンな語彙はグラフを断片化し、ID の統合、トラバーサル、引用の整合性を損ないます。

P1 — 非構造化データ → テキスト単位

バイト列から決定論的に抽出します。各テキスト単位には、document_id、序数、ページ／範囲、文字オフセット、コンテンツハッシュ、テキスト品質帯を保持します。文の途中で区切るより、段落やセクションの境界を優先します。単位をまたぐ関係も抽出できるよう、重複部分を設けます。ファイル全体をまとめた巨大な単位は禁止です。品質が劣化したテキストは、再抽出または失敗キューに回します。インデックスへの登録を黙って行ってはいけません。

詳細：references/unstructured-to-units.md。Upsert の ID：../ns-postgres-rag/references/ingestion-pipeline.md。

P2 — スキーマに固定された抽出

テキスト単位ごとに、1 回の構造化パスを実行します。

1. エンティティ：name、type（オントロジー）、description、コンテキスト内の役割、識別子フィールド（型ごと。捏造しないでください）。
2. 関係：source、target、type（オントロジー）、description、ソース範囲、来歴クラス EXPLICIT または INFERRED、confidence（0～1）。
3. 任意のドキュメントレベルのフィールド（タイトル、著者、日付）は ネストされた { value, sources[], reasoning } とします。コンテキストが不十分な場合は、そのフィールドへの回答を拒否してください。
4. ドキュメントクラスと信頼度区分（分類済み／低／未分類。僅差の場合は下位区分にします）。
5. 語彙にない検出結果は、最も近い型に無理に当てはめず、未マッピング候補キューに追加します。

抽出器の指示は、承認済みオントロジーから組み立てられる ビルド成果物です — references/structured-extraction.md、templates/extractor-instruction.template.md。

単位ごとのトリプレット数に上限を設けてください。型をオントロジーと照合し、不正なラベルは削除します。説明はアンカーマッピングと統合に使用されます — トリプレットだけでは構成に必要な情報が不足します。

P3 — ID を解決する

まず決定論的なブロック、次にベクトルによる 候補、その後に確認 — 型ごとの 順序付き ID 解決手順を使用します。人のような型では、正規化した名前を ID として決して使用しません。モデルは 識別子を抽出し、決定論的なレイヤーがそれを 解決します。

未解決のアンカーは、順位付けされた候補を呼び出し元に返します — 暗黙に推測してはいけません。

詳細：references/graph-assembly.md、../ns-postgres-rag/references/entity-resolution.md。

P4 — 論理エッジ、証拠、メンションを永続化する

1. 論理エッジは source + type + target で一意にします。アップサートでは、信頼度が最も高いものを優先します。来歴クラスによって格下げしません。review_status は関係の信頼度マッピングに従います — references/structured-extraction.md § 関係の信頼度 → review_status（レポートで数値を固定します）。競合時は fact への昇格のみを行います。
2. 証拠は立証ごとに追加します：ドキュメント、単位、引用範囲、信頼度。1 つのエッジに複数の証拠を持たせます — 立証ごとに 1 行にはしません。
3. メンション：コンテキスト内の役割を伴う、単位からエンティティへの関連付けです — フィルタリング済みセット、件数、統合の基盤であり、エッジではありません。
4. ファイルと業務レコード：別個のアンカーです。明示的なファイル間参照は保存し、共有エンティティは発見された経路としてのみ扱います。
5. 提案（提案されたレコード／リンク）は事実ではなく、たどることもできません。確認ポリシーはレポートで宣言します。
6. 引用されたマッピングに従って review_status を永続化します。たどる際は fact のみを使用します。DERIVED 経路はクエリ結果であり、エッジとして永続化してはいけません。

詳細：references/graph-assembly.md。

P5 — 埋め込み

すべての行にモデル ID と次元数を付けて埋め込みます。

オブジェクト	用途
テキスト単位	ベクトル／ハイブリッド検索。ローカルな証拠
エンティティの説明	経路とセットのフィルター用アンカーマッピング

既存の語彙インデックスがある場合は、ハイブリッド順位付けに再利用します — 理由なく再構築を提案しないでください。

バージョン管理された再埋め込み：../ns-postgres-rag/references/ingestion-pipeline.md。

P6 — 回答形式とグラフの契約

単一のグローバル／ローカル切り替えではなく、回答形式に応じてルーティングします。

形式	条件
ユニット／ベクトル	1 つのユニット内のトピックで、ホップチェーンがない
パス	名前付きアンカーがある。「A はどのように B に到達するか」など。ホップ数 N≥2
フィルター付き集合	属性述語を持つエンティティ集合と、任意の時間範囲
件数／集計	グループ化または合計。行ごとの来歴
アンカーの統合	レコードを開いたときの、スコープを限定した要約
ドキュメントの相関付け	新規アップロードとレジストリを比較。未登録の言及を含む

スコープ制限（コレクション、インポート元、ドキュメントタイプ）は、認可とともにランキング前に適用します。ランキング後に適用してはなりません。

時間述語は、エッジの期間およびレコード時刻に対する第一級のフィルターです。

トラバーサル：上限付き再帰ウォーク（../ns-postgres-rag/references/multi-hop-traversal.md）。デフォルトの深さ ≤ 5。各ホップでの規律：認可、タイプ／信頼度フィルター、top-N、訪問済みセットを各ステップの内部で適用します。アクセスを拒否されたノードは中継点として使用しません。一括展開：アンカーセットに対し、各ホップで読み取りを 1 回実行します。ノードごとの読み取りは行いません。ホップごとにモデルを呼び出しません。モデルを使うのは抽出と合成のみです。

回答の合成には、取得したユニット／パス／エビデンスのみを使用します。エビデンスが不足している場合は回答を拒否します。主張する事実にはすべて引用を付けます。

正規グラフクエリ（英語のワイヤ名）：

query_knowledge_graph
{ anchor_ids[], anchor_type, edge_types[], max_depth (≤ 5), period?, scope?, limit?, include_evidence? }
→ { nodes[], edges[], paths[], candidates[]?, telemetry }

テレメトリエンベロープ：実行したホップ数、調査件数と返却件数、打ち切り理由、各ステージのレイテンシ、キャッシュヒット。

禁止事項：自由形式の SQL/Cypher 風ツール、深さに上限のない探索、pending_review を事実として扱うこと、アクセスを拒否されたノードを中継点として扱うこと、ホップごとのモデル呼び出し。

オペレーター向けの可視化では、グラフ全体ではなくクエリパスを表示します。

詳細：references/query-modes.md、references/access-and-citation.md。

役割の分解

実装では、ID リゾルバー、トラバーサル実行器、エンティティ／エッジ／エビデンス／メンションの各リポジトリ、認可サービス、キャッシュ、テレメトリを分離する必要があります。詳細：references/graph-assembly.md。クラス／モジュールの構成は ns-spec-driven に従います。

P7 — GraphRAG プロセスレポート

templates/graphrag-process-report.md をコピーします。すべてのセクションに記入します。ns-spec-driven に進む前に、人間の承認を得ます。

リファレンスマップ

リファレンス	読むタイミング
references/ontology.md	P0、導出、未マッピングキュー
references/unstructured-to-units.md	P1、品質ゲート、オフセット
references/structured-extraction.md	P2、抽出器の契約
templates/extractor-instruction.template.md	P2、ビルド成果物の形式
references/graph-assembly.md	P3～P4、エビデンス、メンション
references/discovery-layer.md	オプトインの分析のみ
references/query-modes.md	P6、6 つの形式
references/access-and-citation.md	ACL、信頼できない入力、キャッシュ
references/process-eval.md	ゴールデンセット、メトリクス
references/anti-patterns.md	レポート完了とする前
../ns-postgres-rag/references/*	スキーマ、解決、ホップ、スケール

ns-spec-driven への引き継ぎ

Retrieval Design Report および GraphRAG Process Report の人間による承認後：

## GraphRAG implementation planning
- Retrieval report: path (approved)
- Process report: path (approved)
- Ontology: entity types / relation types / version id
- Extract stages: units → extract → resolve → persist (edge+evidence+mention) → embed
- Answer shapes: unit | path | filtered set | count | synthesis | document correlation
- Discovery: off | on (archetype + gate)
- Graph query: query_knowledge_graph; max_depth cap; telemetry envelope
- Eval: evidence precision, path accuracy, set completeness, citation faithfulness, refuse-when-empty
- Out of scope for this skill: application source code

停止条件

条件	アクション
モードが GraphRAG ではない	ns-postgres-rag を継続し、抽出器のグラフは使用しない
類似性または共起を保存するエッジとして提案している	拒否する
オントロジーが確定していない	P2 をブロックする
自由形式のグラフクエリ言語	拒否する
競合するベクトルストアをデフォルトとして提案している	ns-postgres-rag のストアを継続する
人間が今すぐアプリコードを求めている	まずレポートを作成し、その後 ns-spec-driven のみを実行する

禁止事項

• アプリケーション言語、フレームワーク、ベンダー、モデル SKU
• 共起や埋め込み距離を edge として扱うこと
• 検出アーキタイプを宣言せずに、モジュラリティによるグループ化をパイプラインの段階にすること
• アテステーションごとにエッジ行を作成すること（論理エッジとエビデンスの追記を使用してください）
• 人物に類する型の存続する識別子として正規化名を使用すること
• 派生した探索パスをエッジとして永続化すること
• パスの探索だけで、フィルタリングされた集合や件数に関する質問に回答すること
• 検出結果を事実として提示したり、エッジとして書き戻したりすること
• ランキング後にスコープを制限すること
• 拒否されたノードを中間ブリッジとして使用すること
• グラフのホップごとにモデルを呼び出すこと
• バッチ展開中にノードごとに読み取ること
• 品質バンドなしで劣化したテキストをインデックス化すること
• 確認ポリシーを宣言せずに、提案されたレコードをコミットすること
• 認可コンテキストまたはグラフバージョンを含まないキャッシュキー
• ドキュメント全体を生成処理に渡すこと
• 事実を述べる際に引用を付けずに回答すること
• 認可の失敗を呼び出し元に明かすこと