mini-context-graph

ミニコンテキストグラフスキル

中核となる考え方

標準的な RAG では、クエリのたびに知識をゼロから再発見します。このスキルはそれとは異なります。

1. Wiki レイヤー — LLM が永続的な Markdown ページ（要約、エンティティページ、トピックの統合）を作成し、維持します。相互参照はすでに用意されています。ドキュメントを取り込むたびに Wiki が充実します。
2. グラフレイヤー — エンティティと関係性を一度だけ抽出し、たどって検索できるナレッジグラフとして保存します。BFS によるトラバーサルで、ソースを読み直さずに構造に関するクエリへ回答できます。
3. 生ソースレイヤー — 元のドキュメントをチャンクとともに不変の状態で保存します。来歴リンクによって、すべてのグラフノードとエッジが、その根拠となる正確なテキストに結び付けられます。

LLM が記述し、Python ツールがすべての管理作業を処理します。

---

3 つのレイヤー

レイヤー	場所	LLM が行うこと	Python が行うこと
生ソース	data/documents.json	読み取り（変更はしません）	チャンクとメタデータを保存
Wiki	wiki/ (markdown)	ページを作成・更新	index.md と log.md を管理
グラフ	data/graph.json	エンティティと関係性を抽出	永続化、重複排除、トラバーサル

---

⚡ エージェント向けクイックスタート

このワークフローを実行できる完全なバージョンは scripts/template_agent_workflow.py にあります。コピーして用途に合わせてください。

from scripts.contextgraph import ContextGraphSkill
from scripts.tools import wiki_store

skill = ContextGraphSkill()

# ===== INGEST WITH FULL RAG + WIKI =====
# 1. Read references/ingestion.md and references/ontology.md first
# 2. Extract entities and relations (LLM reasoning step)
entities = [
    {"name": "memory leak",   "type": "issue",  "supporting_text": "memory leaks cause crashes"},
    {"name": "system crash",  "type": "issue",  "supporting_text": "system crashes due to memory leaks"},
]
relations = [
    {"source": "memory leak", "target": "system crash", "type": "causes",
     "confidence": 1.0, "supporting_text": "System crashes due to memory leaks."},
]

result = skill.ingest_with_content(
    doc_id="doc_001",
    title="System Crash Analysis",
    source="/docs/incident_report.pdf",
    raw_content="System crashes due to memory leaks. Memory leaks occur when objects are not released.",
    entities=entities,
    relations=relations,
)
# result = {"doc_id": "doc_001", "chunk_count": 1, "nodes_added": 2, "edges_added": 1}

# 3. Write a wiki summary page for this document
wiki_store.write_page(
    category="summary",
    title="System Crash Analysis Summary",
    content="""---
title: System Crash Analysis
source_document: doc_001
tags: [summary, incident]
---

# System Crash Analysis

**Source:** incident_report.pdf

## Key Claims

- [[memory-leak]] causes [[system-crash]] (confidence: 1.0)

## Entities

- [[memory-leak]] (issue)
- [[system-crash]] (issue)
""",
    summary="Incident report: memory leaks cause system crashes.",
)

# ===== QUERY WITH EVIDENCE =====
result = skill.query_with_evidence("Why does the system crash?")
# Returns: {"query": ..., "subgraph": ..., "supporting_documents": [...], "evidence_chain": ...}

# ===== WIKI SEARCH (read wiki before answering) =====
pages = wiki_store.search_wiki("memory leak")
# Returns: [{slug, category, path, snippet}, ...]

---

操作

取り込み

ユーザーが新しいドキュメントを提供した場合：

1. references/ingestion.md を読みます。エンティティと関係性の抽出ルールが記載されています。
2. references/ontology.md を読みます。タイプの正規化ルールが記載されています。
3. LLM の推論を使ってエンティティと関係性を抽出します。
4. skill.ingest_with_content(...) を呼び出します。生のコンテンツ、チャンク、グラフノード、来歴を保存します。
5. wiki_store.write_page(category="summary", ...) を使ってWiki の要約ページを作成します。
6. エンティティページを更新します — 新規または更新されたエンティティごとに、wiki_store.write_page(category="entity", ...) を使ってページを作成または更新します。
7. ドキュメントが既存の統合トピックに関係する場合は、トピックページを更新します。
8. 通常、1 件のドキュメントを取り込むと 3〜10 件の Wiki ページが更新されます。

クエリ

ユーザーから質問された場合：

1. まず Wiki を確認します — wiki_store.search_wiki(query) で関連ページを見つけ、内容を読みます。
2. Wiki に適切な回答がある場合は、Wiki ページから統合します（高速パス）。
3. より深いグラフトラバーサルが必要な場合は、skill.query_with_evidence(query) を呼び出します。
4. supporting_documents の根拠となる引用を添えて回答します。
5. 回答に価値がある場合は、新しい Wiki トピックページとして保存します。

Lint

定期的に Wiki の状態を確認します。

from scripts.tools import wiki_store
issues = wiki_store.lint_wiki()
# Returns: {orphan_pages, missing_pages, broken_wikilinks, isolated_pages}

リンク切れ、孤立したページ、古くなった主張、欠落している相互参照を確認して修正するよう LLM に依頼します。Lint ワークフローの全容については references/lint.md を参照してください。

---

取り込み時の制約

• ❌ テキストに存在しないエンティティを幻覚で作り出さないでください
• ❌ テキスト上の明示的な根拠なしに関係性を追加しないでください
• ❌ 信頼度が 0.6 未満のエッジを追加しないでください
• ✅ 来歴を有効にするため、すべてのエンティティと関係性に supporting_text を指定してください
• ✅ 取り込んだドキュメントごとに Wiki の要約ページを作成してください
• ✅ 新しい情報が加わったら、既存のエンティティページを更新してください
• ✅ 新しいデータが古い主張と矛盾する場合は、Wiki ページでその矛盾を明示してください

---

検索時の制約

• 🔒 トラバーサルの深さは 2 を超えてはなりません（設定：MAX_GRAPH_DEPTH）
• 🔒 信頼度が 0.6 以上のエッジのみを対象とします（設定：MIN_CONFIDENCE）
• 🔒 返すノード数は最大 50 件です（設定：MAX_NODES）
• ❌ グラフに存在しないノードやエッジを捏造しないでください

---

Python API リファレンス全体

メソッド	目的	使用するタイミング
skill.ingest_with_content(doc_id, title, source, raw_content, entities, relations)	完全な RAG 取り込み：生のドキュメント＋グラフ＋出典情報	新しいドキュメントごと
skill.add_node(name, node_type)	単一のエンティティを追加（出典情報なし）	出典ドキュメントなしで手早く追加する場合
skill.add_edge(source_name, target_name, relation, confidence)	単一の関係を追加	出典ドキュメントなしで手早く追加する場合
skill.query(query)	グラフのみから検索 → サブグラフ	構造に関するクエリ
skill.query_with_evidence(query)	グラフ＋出典情報 → サブグラフ＋ソースチャンク	引用が必要なクエリ
wiki_store.write_page(category, title, content, summary)	Wiki ページを書き込み／更新	取り込み後毎回、クエリへの回答後
wiki_store.read_page(category, title)	Wiki ページを読み込む	回答前、相互参照時
wiki_store.search_wiki(query)	Wiki 全体をキーワード検索	グラフ探索前の高速な手段
wiki_store.list_pages(category)	Wiki の全ページを一覧表示	全体像を把握する場合
wiki_store.get_log(last_n)	最近の操作を読み込む	Wiki の履歴を把握する場合
wiki_store.lint_wiki()	ヘルスチェック	定期的なメンテナンス
documents_store.list_documents()	取り込み済みの生ソースをすべて一覧表示	監査／出典情報の確認
documents_store.search_chunks(query)	チャンク単位で検索	特定の根拠を見つける場合

---

設計思想

「Wiki は永続的に蓄積される成果物です。相互参照はすでに存在しています。統合結果には、これまでに読んだすべての内容がすでに反映されています。」— Karpathy

レイヤー	処理内容	担当
LLM による推論	抽出、統合、Wiki ページの執筆	エージェント（.md ガイダンスファイル）
Wiki の永続化	インデックス、ログ、ファイル I/O	wiki_store.py
グラフの永続化	重複排除、インデックス、BFS 探索	graph_store.py、retrieval_engine.py
生ソースの保存	不変のドキュメント＋チャンク＋出典情報	documents_store.py

人間はソースを整理し、質問します。LLM は Wiki を執筆し、グラフを抽出し、引用を付けて回答します。記録管理はすべて Python が担います。