agentic-rag

IETF RFC エコシステムから得た実際のコーパスに対する、引用付き・リビジョン認識型の検索 -- RFC 全文、RFC インデックスの実際の Obsoletes/Obsoleted-by/Updates 置換グラフ、実際のコミュニティ提出 RFC 正誤表、実際の IANA プロトコルパラメータレジストリ -- を HTTPS で取得し（corpus_fetch/）、ragpack を通じて検索可能なベクトルストア（実際のチャンク 321,124 件）に取り込み、consilium スパインでルーティングと引用ゲートを行います。

IETF プロトコル仕様、RFC の著者/ステータス、実際の正誤表の修正、IANA レジストリのエントリについて実際の質問をすると、実際に引用されたチャンクのみ、または正直な棄権で構成された回答が返ります。唯一の例外は廃止に関する質問（「RFC 2616 を置き換えたものは？」）です。RFC 2616 自体のテキストには「現在のリビジョン」が存在しないため（後続の 6 つの文書、RFC 7230-7235 -- IETF 自身の有名な多方向廃止事例 -- によって完全に置き換えられました）、これは SupersessionModule によって回答されます。これは実際の Obsoletes/Obsoleted-by グラフに対する決定論的なグラフ検索であり、検索ではありません。回答経路には LLM は一切使用されません。

クイックスタート

git clone https://github.com/trentmilam/agentic-rag
cd agentic-rag
py -3.12 -m venv .venv
.venv\Scripts\python -m pip install -r requirements.txt
.venv\Scripts\python -m pip install -e .
.venv\Scripts\python scripts\verify.py

これがブートストラップ全体です。編集可能インストールにより、import consilium、import ragpack、import linkgraph、import activerag、import chainrag が解決されます -- pyproject.toml の package-dir が各名前を packages/ にマッピングします。

実際の質問に回答するには、取り込まれたコーパスも必要です。コーパス と 検証 を参照してください。

Related MCP server: DocuMind MCP

1 つのリポジトリ、5 つの統合ツール

agentic-rag は以前、consilium と linkgraph を兄弟リポジトリからインポートし、そのルートを sys.path に挿入していました。また、RAGpack を 3 つ目のリポジトリから編集可能な形で pip インストールする必要がありました。クローンするには、3 つの別々のファイルに固定された 3 つのコミットで 4 つのリポジトリをクローンする必要がありました -- それらはすでに互いに乖離していました。linkgraph もこのリポジトリのデータファイルを読み取っていたため、2 つはリポジトリ境界を越えて相互にインポートしていました。

現在は 1 つのリポジトリです。統合された各ツールは、そのツリー全体を packages/<name>/ の下に保持しているため、自身のルートを基準に解決されるものはすべて引き続き解決され、それぞれが独自のコミット履歴を保持しています（インポートコミットに押しつぶされることはありません）。

これらがリポジトリルートではなく packages/ の下にネストされているのには具体的な理由があります。consilium という名前のトップレベルディレクトリは、暗黙の名前空間パッケージとして consilium パッケージをシャドウします。なぜなら、作業ディレクトリが sys.path 上で編集可能インストールより先に来るからです。インポートは空の名前空間に解決され、consilium.__file__ は None になります。CI はすべてのパッケージがこのリポジトリ内のファイルに解決されることを検証するため、その種のサイレントな誤バインドは、間違ったコピーに対してすべてのテストを通過させる代わりにビルドを失敗させます。

rag-reliability は、このリポジトリの外にある唯一の依存関係です。これは graphrx、headroom、vecstamp、chunkledger、plumbline、legigate を上記の 3 つのツールに提供し、現在はパスで解決されています。これを宣言された依存関係にできるようにパッケージ化することが、未解決のフォローアップです。CI はこれを固定してチェックアウトし、統合テストがスキップされた場合は失敗するため、残っている唯一のパス依存関係が気付かれずに腐ることはありません。

コーパス

合計 321,124 の実際のチャンク。実際の BAAI/bge-base-en-v1.5 モデルで埋め込まれています。rfc_text/rfc_index だけがリビジョンの概念を持つソースタイプです -- そこでの is_current は実際の構造的事実です（リビジョンガード を参照）。推測ではありません。

5 つのモジュール、1 つのルーター

agenticrag/bootstrap.py::build_registry は、実際の 5 モジュールの consilium Registry を組み立てます。上記の 4 つの検索モジュール（それぞれ Qdrant から直接ロードされ、デフォルトで current_only=True -- agenticrag/registry_loader.py を参照）に加えて、SupersessionModule（agenticrag/supersession.py）があります。これは ComputeModule で、data/entities/revisions.json -- ライブインデックス内の全 9,794 RFC の実際の Obsoletes/Obsoleted-by グラフ -- を構築時に一度解析し、廃止に関する質問に決定論的でサイクル安全なグラフ走査（訪問ノード数 50 で制限 -- 防御的な上限であり、想定される実際の制限ではありません。実際の IETF 廃止コンポーネントは小さい）で回答します。

build_registry はまた、プロセスの設定済みエンベッダーがストアを取り込んだものと一致しない場合に大きなエラーを出します（verify_embedder_marker が最初に呼び出されます）-- そうでなければコサインスコアは静かに無意味になるためです -- また、モジュールがロードされた後、自分で開いた Qdrant クライアントを閉じます（その後、検索は完全にメモリ内で行われます）。そのため、ローカルモードのストアのロックを呼び出し元のプロセス全体の寿命にわたって保持しません。

errata の trust_tier（0.55。rfc_text/rfc_index/iana_registry の 0.9-0.95 よりかなり低い）は推測ではなく測定されています。取り込まれた実際の正誤表レコード 5,061 件のうち、RFC エディタによって Verified とされているのは わずか 2,400 件（47.4%） です。1,781 件（35.2%）は Held for Document Update、679 件（13.4%）は完全な Rejected、201 件（4.0%）はまだ Reported です。実際に提出された修正の半分未満が RFC エディタによって確認されているため、このモジュールは一次テキストを修正しますが、それ自体が一様に権威あるわけではありません。

MCP サーバー

agenticrag/mcp/server.py は、回答パスを stdio 上の Model Context Protocol サーバーとして公開します（mcp>=1.28.1、FastMCP）。4 つのツール:

• search(query) -- 完全な引用/棄権の回答パス（consilium.compute.answer_v3）。そのまま渡されます（正直な棄権は棄権のまま）。

• get_obsoletion_chain(rfc_id) / get_corrections(rfc_id) / get_related(entity_id) -- linkgraph 兄弟（agenticrag/relationships.py）を介したリレーションシップグラフ。それぞれ、その兄弟が存在しない場合は、文書化された {"ok": false, "fallback": ...} エンベロープを返します。

実行方法: .venv\Scripts\python -m agenticrag.mcp.server（stdio トランスポート -- MCP クライアントが起動し、stdin/stdout でプロトコルを話します）。ツールのロジックはインポートが軽量で、mcp/Qdrant 依存関係がないため、どちらもなしで単体テストできます（agenticrag/mcp/test_server.py）。

検証

クイック検証（高速、コーパス不要 -- 取り込まれたコーパスは不要）:

verify.bat        :: or:  .venv\Scripts\python -m pytest -q

MCP ツールラッパーテストと、スーパーセッショングラフ走査のサイクル安全性スイートを実行します。これは CI がすべてのプッシュで実行するものです（上のバッジを参照）。

フル検証（クイックスタートで取り込まれた 321k チャンクのコーパスが必要）:

.venv\Scripts\python eval\eval_agenticrag.py

すでに取り込まれたコーパスが与えられれば決定論的です。再取り込みは不要です。実際のエンベッダー -- コーパスを取り込んだものとまったく同じ -- を使用するため、配線だけではなく、真の意味論的検索をエンドツーエンドで証明します。このハードウェアでは約 3.3 分かかります（測定済み、フル実行: 196 秒）。一度だけの約 60 秒のレジストリ構築（小さなポイズン隔離セットのためのコーパスの単一スキャン -- 321k ベクトルすべてのロードではありません）、その後、ルーター/回答パスはそれぞれ約 12 秒です。各パスはルーティングと検索をネイティブの Qdrant ベクトル検索として実行します。Qdrant の組み込みローカルモードは正確なブルートフォース（ANN インデックスなし）であるため、検索はフィルタリングされたサブセットをスキャンしますが、ネイティブコードで、トップ k のみを具体化し、古い純 Python のチャンクごとのスキャンより約 16 倍高速です。（サブ秒の検索には Qdrant サーバーモードの HNSW インデックスが必要です。ローカルモードはリポジトリを自己完結型に保ちます -- 実行するサーバーはありません。）チェック内容: ソースタイプごとに 1 つのスコープ内クエリ（適切なモジュール + 少なくとも 1 つの実際の引用）。RFC 2616 の廃止クエリ（後継セットは正確に {7230, 7231, 7232, 7233, 7234, 7235}）。1 つのスコープ外クエリ（正直な棄権）。リビジョンガードの構造的除外（下記）。実際に現在の RFC（791）が current に解決されること。存在しない RFC 番号（99999）がクラッシュではなく not_found に解決されること。

eval/prove_revision_guard.py は、同じ構造的証明をスタンドアロンのナレーション付きスクリプトとして提供します。eval/smoke_ingest_real.py は、ゼロコストの HashEmbedder で fetch->ingest->Qdrant の配線を証明します（corpus_fetch.fetch_all が実行されている必要がありますが、GPU/埋め込みモデルは不要です）。

リビジョンガード、証明済み

RFC 2616（HTTP/1.1）は実際の単一の完全な文書です。それには「現在のリビジョン」は存在せず、6 つの異なる文書によって完全に置き換えられました。ここでのガードプロパティは、1 つの「修正値」ではなく、2 つの実際の検証可能な事実です。

1. 構造的除外。 RFC 2616 自体の rfc_text チャンクは Qdrant に存在します（rfc_text モジュールを current_only=False で 2 回目にロードすると、それらが存在することが証明されます）が、すべてのクエリが実際に使用するデフォルトの current_only=True モジュールには存在しません -- なぜなら data/entities/revisions.json["RFC2616"]["obsoleted_by"] が実際に存在し、空ではないからです。データは存在します。構造的にフィルタリングされているのであって、偶然欠落しているわけではありません。

2. 回答への正しいパス。 SupersessionModule は、RFC 2616 に何が起こったかを学ぶための明示的な方法です -- それを指定するクエリは、実際の 6 方向の後継リスト（RFC 7230-7235）を返します。

ルーターのキャリブレーション -- 推測ではなく測定

consilium.router.Router の文書化されたライブラリデフォルト（floor=0.11、anchor_centroid=0.25、anchor_best_chunk=0.25）は、無関係なテキスト間のベースラインコサインがほぼゼロであることを前提としています。これは bag-of-words の HashEmbedder には当てはまりますが、321k チャンクのコーパス上の実際の高密度エンベッダーには必ずしも当てはまりません（同じギャップは、はるかに小さい約 1,100 チャンクのスケールでも現れます）。agenticrag/calibrate.py は、これを推測するのではなく、実際のコーパス + 実際のエンベッダーに対して直接測定します。結果のインスタンスごとの kwargs と、その決定を正当化した実際の数値については、agenticrag/bootstrap.py::ROUTER_KWARGS を参照してください。

.venv\Scripts\python agenticrag\calibrate.py

GPU に関する注意（取り込みのみ）

GPU が重要なのは、正確に 1 つのステップだけです。コーパスの取り込み（ingest/run_ingest.py）で、onnxruntime を介して BAAI/bge-base-en-v1.5 で約 321k チャンクを埋め込みます。クエリ時には（短い）クエリ文字列のみを埋め込むため、ランチャーは GPU セットアップなしで CPU で問題なく実行できます。そのため、ランチャーは GPU 設定に一切触れなくなりました。

想定内で無害な警告: onnxruntime-gpu がインストールされていても、対応する CUDA ランタイム DLL が検索パス上にない場合、警告色の赤い CUDAExecutionProvider / Error loading ... cublasLt64_*.dll ... missing ブロックが表示されます -- どの実行でも、インジェストでもクエリでも、インジェストだけではありません。これは失敗ではありません: onnxruntime は CPU にフォールバックして続行します(クエリの場合、埋め込みは短い文字列1つなので、CPU フォールバックは即座です)。無視するか、以下の DLL をインストールして抑制してください。

高速なインジェストのためには、onnxruntime-gpu の CUDA 実行プロバイダーが DLL 検索パス上に CUDA ランタイム DLL を必要とします。pip install onnxruntime-gpu だけでは それらをバンドルしません。それらがない場合、onnxruntime はエラーを発生させるのではなく CPU にフォールバックします(測定値: ~6 chunks/秒 -- 計算値: 全 321,124 チャンクのコーパスで約 14.9 時間)。実際の GPU 実行を得るには(測定値: RTX 5090 で ~650 chunks/秒、つまり全コーパスで約 8 分)、このリポジトリの独自の venv に一致する CUDA ランタイム wheel をインストールしてください。例:

.venv\Scripts\python -m pip install nvidia-cublas-cu13 nvidia-cudnn-cu13

(-cuNN サフィックスを onnxruntime-gpu ビルドの CUDA メジャーバージョンに合わせてください)。または、CUDA 対応の PyTorch インストールの torch/lib ディレクトリを、インジェスト実行前に PATH に追加してください。どちらの方法でも、これは 一度きりのインジェストの任意の高速化 であり、デモの実行やクエリの提供には決して必要ありません。

インジェストの再実行(既知の制限)

ingest/run_ingest.py は、ゼロからの --recreate 再構築と、高速なインクリメンタルパス(コンテンツハッシュが変更された生ファイルのみを再埋め込み)をサポートしています。インクリメンタルパスには、意図的に隠蔽されていない2つの既知の制限があります:(1) 「変更された」を各生ファイルのバイトハッシュのみで判定するため、後の rfc-index.txt の更新で RFC が新たに廃止された場合、そのテキストファイル自体が変更されていなくても、その is_current フラグが古くなる可能性があります。(2) より少ないチャンクに再インジェストされたドキュメントの孤立した Qdrant ポイントを削除しません。一貫性が保証されたストアが必要な場合は、ingest/run_ingest.py --recreate(完全再構築)を実行してください。インクリメンタルパスで両方の制限を解消することは今後の課題です。

レイアウト

agenticrag/
  embed_config.py     shared Settings (model/qdrant path) + embedder-consistency guard
  registry_loader.py  loads a consilium Module's chunks straight from Qdrant (current_only guard)
  bootstrap.py        build_registry(embedder, client=None) -> Registry; the 5 Descriptors; ROUTER_KWARGS
  supersession.py     SupersessionModule -- real Obsoletes/Obsoleted-by graph walk, cycle-safe
  relationships.py    thin bridge into linkgraph (get_related / _obsoletion_chain / _corrections)
  calibrate.py        real router-score measurement script
  mcp/
    server.py         FastMCP server: search + the 3 relationship tools (stdio)
    test_server.py    fixture-only tests for the tool logic (no mcp package, no Qdrant)
corpus_fetch/         real HTTPS fetch of RFC full text / rfc-index.txt / errata / IANA registries
ingest/
  connectors/         per-source-type extract() -> ExtractedDoc (+ the revisions-index builder)
  run_ingest.py       raw files -> chunk -> embed -> Qdrant, real is_current currency check
eval/
  smoke_ingest_real.py               corpus_fetch -> ingest -> Qdrant wiring smoke (HashEmbedder)
  eval_agenticrag.py                 production eval (full verify; needs the ingested corpus)
  prove_revision_guard.py            standalone, narrated revision-guard proof
  test_supersession_cycle_safety.py  cycle-safety unit tests (synthetic graph; corpus-free)
tests/                unit tests for connectors / registry_loader / bootstrap (corpus-free)
packages/             the five merged tools, each keeping its own tree and history
  consilium/          routing / citation-gating spine (+ its 5 eval suites)
  ragpack/            ingest / chunk / embed / Qdrant store (src-layout)
  linkgraph/          cross-document relationship graph
  activerag/          evidence-thinness detection and bounded hunt-and-retry
  chainrag/           the blockchain-docs vertical
app.py                gr.ChatInterface chat UI
run_demo.py           scripted 3-question narrated transcript

ライセンス

コード: MIT (c) 2026 Trent Milam.

コーパスはこのリポジトリには 含まれていません(data/ は gitignore されています)。ビルド時に rfc-editor.org と iana.org から取得されます。IETF RFC/正誤表テキストは IETF Trust Legal Provisions の対象です(取得時には各ドキュメントの著作権/Trust 通知がそのまま保持されます)。IANA レジストリデータは IANA によって公開されています。このプロジェクトはそれらのいずれも再配布しません -- あなたのマシン上でローカルに取得するだけです。