agentic-rag

Zitierter, revisionsbewusster Abruf über einen echten Korpus aus dem IETF-RFC-Ökosystem – RFC-Volltexte, der echte Obsoletes/Obsoleted-by/Updates-Supersessionsgraph des RFC-Index, echte von der Community eingereichte RFC-Errata und echte IANA-Protokollparameter-Registries – abgerufen über HTTPS (corpus_fetch/) und über ragpack in einen durchsuchbaren Vektor-Store (321.124 echte Chunks) eingespeist, dann über das consilium-Rückgrat geroutet und zitatgeprüft.

Stelle eine echte Frage zu einer IETF-Protokollspezifikation, zur Autorenschaft/Status eines RFC, zu einer echten Errata-Korrektur oder zu einem IANA-Registry-Eintrag, und du erhältst eine Antwort, die vollständig aus echten zitierten Chunks – oder einer ehrlichen Enthaltung besteht. Die eine Ausnahme ist eine Obsoletions-Frage („Was hat RFC 2616 ersetzt?“): Es gibt keine „aktuelle Revision“ des Textes von RFC 2616 selbst, die abgerufen werden könnte (er wurde vollständig durch sechs spätere Dokumente ersetzt, RFC 7230-7235 – der berühmte mehrfache Obsoletions-Fall der IETF selbst), daher wird diese durch SupersessionModule beantwortet, eine deterministische Graphsuche über den echten Obsoletes/Obsoleted-by-Graphen, nicht durch Abruf. Kein LLM im Antwortpfad.

Schnellstart

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

Das ist das gesamte Bootstrap. Die editierbare Installation sorgt dafür, dass import consilium, import ragpack, import linkgraph, import activerag und import chainrag aufgelöst werden – pyproject.toml's package-dir mappt jeden Namen auf packages/.

Um eine echte Frage zu beantworten, wird zusätzlich der eingespeiste Korpus benötigt; siehe Der Korpus und Verifizieren.

Related MCP server: DocuMind MCP

Ein Repository, fünf zusammengeführte Werkzeuge

agentic-rag importierte früher consilium und linkgraph aus Schwester-Repositories, indem es deren Wurzeln auf sys.path einfügte, und benötigte RAGpack als editierbare Installation aus einem dritten. Das Klonen bedeutete, vier Repositories bei drei Commits zu klonen, die in drei separaten Dateien festgepinnt waren – die bereits voneinander abgedriftet waren. linkgraph las auch die Datendatei dieses Repositories, also importierten sich diese beiden gegenseitig über eine Repository-Grenze hinweg.

Sie sind jetzt ein Repository. Jedes zusammengeführte Werkzeug behielt seinen gesamten Baum unter packages/<name>/, sodass alles, was es relativ zu seiner eigenen Wurzel auflöst, weiterhin aufgelöst wird, und jedes behielt seine eigene Commit-Historie, anstatt in einen Import-Commit gequetscht zu werden:

Sie sind unter packages/ verschachtelt und nicht an der Repository-Wurzel, aus einem konkreten Grund: Ein Verzeichnis der obersten Ebene namens consilium überschattet das consilium-Paket als implizites Namespace-Paket, weil das Arbeitsverzeichnis der editierbaren Installation auf sys.path vorausgeht. Importe lösen dann zu einem leeren Namespace auf und consilium.__file__ ist None. CI stellt sicher, dass jedes Paket auf eine Datei innerhalb dieses Repositories aufgelöst wird, sodass diese Klasse von stillen Fehlbindungen den Build fehlschlagen lässt, anstatt jeden Test gegen die falsche Kopie zu bestehen.

rag-reliability ist die eine Abhängigkeit, die noch außerhalb dieses Repositories liegt. Sie liefert graphrx, headroom, vecstamp, chunkledger, plumbline und legigate an drei der obigen Werkzeuge und wird heute über den Pfad aufgelöst; sie zu verpacken, sodass sie eine deklarierte Abhängigkeit sein kann, ist das offene Folgeproblem. CI checkt sie gepinnt aus und schlägt fehl, wenn diese Integrationstests übersprungen werden, sodass die eine verbleibende Pfadabhängigkeit nicht unbemerkt verrotten kann.

Der Korpus

321.124 echte Chunks insgesamt, eingebettet mit dem echten BAAI/bge-base-en-v1.5-Modell. rfc_text/rfc_index sind die einzigen Quellentypen mit einem Revisionskonzept – is_current ist dort eine echte strukturelle Tatsache (siehe die Revisionswächter, bewiesen), nicht geraten.

Fünf Module, ein Router

agenticrag/bootstrap.py::build_registry assembliert eine echte 5-Modul-Registry von consilium: die 4 Abrufmodule oben (jedes direkt aus Qdrant geladen, current_only=True standardmäßig – siehe agenticrag/registry_loader.py), plus SupersessionModule (agenticrag/supersession.py), ein ComputeModule, das data/entities/revisions.json parst – den echten Obsoletes/Obsoleted-by-Graphen für alle 9.794 RFCs im Live-Index – einmal bei der Konstruktion und beantwortet Obsoletions-Fragen mit einem deterministischen, zyklussicheren Graph-Walk (begrenzt auf 50 besuchte Knoten – eine defensive Obergrenze, keine erwartete echte Grenze; echte IETF-Obsoletions-Komponenten sind klein).

build_registry schlägt auch laut fehl, wenn der konfigurierte Embedder des Prozesses nicht mit dem übereinstimmt, der den Store eingespeist hat (verify_embedder_marker, zuerst aufgerufen) – sonst wären Kosinus-Scores stillschweigend bedeutungslos – und schließt jeden Qdrant-Client, den es selbst geöffnet hat, sobald die Module geladen sind (Abruf ist danach vollständig im Speicher), sodass es den Lock des lokalen Modus-Stores nicht für die gesamte Prozesslebensdauer des Aufrufers hält.

Der trust_tier von errata (0,55, weit unter den 0,9-0,95 von rfc_text/rfc_index/iana_registry) ist gemessen, nicht geraten: Von 5.061 echten aufgenommenen Errata-Datensätzen sind nur 2.400 (47,4 %) Verified vom RFC-Editor – 1.781 (35,2 %) sind Held for Document Update, 679 (13,4 %) sind direkt Rejected, und 201 (4,0 %) sind noch Reported. Weniger als die Hälfte der echten eingereichten Korrekturen sind vom RFC-Editor bestätigt, daher korrigiert dieses Modul den Primärtext, ohne selbst einheitlich autoritativ zu sein.

MCP-Server

agenticrag/mcp/server.py stellt den Antwortpfad als Model Context Protocol-Server über stdio bereit (mcp>=1.28.1, FastMCP). Vier Werkzeuge:

• search(query) – der vollständige zitierte/Enthaltungs-Antwortpfad (consilium.compute.answer_v3), unverändert durchgereicht (eine ehrliche Enthaltung bleibt eine Enthaltung);

• get_obsoletion_chain(rfc_id) / get_corrections(rfc_id) / get_related(entity_id) – der Beziehungsgraph über das linkgraph-Geschwister (agenticrag/relationships.py); jedes gibt eine dokumentierte {"ok": false, "fallback": ...}-Hülle zurück, wenn dieses Geschwister fehlt.

Starte ihn: .venv\Scripts\python -m agenticrag.mcp.server (stdio-Transport – ein MCP-Client startet ihn und spricht das Protokoll über stdin/stdout). Die Werkzeug-Logik ist importleicht und hat keine mcp/Qdrant-Abhängigkeit, sodass sie ohne beides unit-testbar ist (agenticrag/mcp/test_server.py).

Verifizieren

Schnelle Verifizierung (schnell, korpusfrei – kein eingespeister Korpus nötig):

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

Führt die MCP-Werkzeug-Wrapper-Tests und die Zyklussicherheits-Suite des Supersessions-Graph-Walks aus. Das ist, was CI bei jedem Push ausführt (siehe Badge oben).

Volle Verifizierung (benötigt den eingespeisten 321k-Chunk-Korpus aus dem Schnellstart):

.venv\Scripts\python eval\eval_agenticrag.py

Deterministisch bei bereits eingespeistem Korpus; keine erneute Einspeisung. Verwendet den echten Embedder – genau den, der den Korpus eingespeist hat –, sodass dies echte semantische Abfrage Ende-zu-Ende beweist, nicht nur Verdrahtung. Dauert ~3,3 Minuten auf dieser Hardware (gemessen, voller Lauf: 196s): ein einmaliger ~60s-Registry-Aufbau (ein einzelner Scan des Korpus für die kleine Gift-Quarantäne-Menge – kein Laden aller 321k Vektoren), dann die Router/Antwort-Durchläufe bei ~12s pro Stück. Jeder Durchlauf führt Routing und Abruf als native Qdrant-Vektorsuchen aus; Qdrants eingebetteter lokaler Modus ist exakte Brute-Force (kein ANN-Index), sodass eine Suche weiterhin die gefilterte Teilmenge scannt – aber in nativem Code, wobei nur die Top-k materialisiert werden, ~16x schneller als der alte reine Python-Pro-Chunk-Scan. (Subsekundensuche würde den HNSW-Index des Qdrant-Servermodus erfordern; der lokale Modus hält das Repository selbstständig – kein Server zum Ausführen.) Es prüft: eine im Rahmen liegende Abfrage pro Quellentyp (sinnvolles Modul + >=1 echtes Zitat); die RFC-2616-Obsoletions-Abfrage (Nachfolgemenge ist exakt {7230, 7231, 7232, 7233, 7234, 7235}); eine außerhalb des Rahmens liegende Abfrage (ehrliche Enthaltung); die strukturelle Ausschlussprüfung des Revisionswächters (unten); ein wirklich aktuelles RFC (791), das current auflöst; und eine nicht vorhandene RFC-Nummer (99999), die not_found auflöst, kein Absturz.

eval/prove_revision_guard.py ist derselbe strukturelle Beweis als eigenständiges, erzähltes Skript. eval/smoke_ingest_real.py beweist die Fetch->Ingest->Qdrant-Verdrahtung mit dem kostenlosen HashEmbedder (benötigt, dass corpus_fetch.fetch_all ausgeführt wurde, aber keine GPU/Embedding-Modell).

Die Revisionswächter, bewiesen

RFC 2616 (HTTP/1.1) ist ein echtes, einzelnes, ganzes Dokument – es gibt keine „aktuelle Revision“ davon; es wurde vollständig durch sechs verschiedene Dokumente ersetzt. Die Wächter-Eigenschaft hier sind zwei echte, überprüfbare Fakten, nicht ein einzelner „korrigierter Wert“:

1. Struktureller Ausschluss. Die eigenen rfc_text-Chunks von RFC 2616 existieren in Qdrant (das erneute Laden des rfc_text-Moduls mit current_only=False beweist, dass sie da sind), fehlen aber im Standardmodul current_only=True, das jede Abfrage tatsächlich verwendet – weil data/entities/revisions.json["RFC2616"]["obsoleted_by"] echt und nicht leer ist. Die Daten existieren; sie sind strukturell gefiltert, nicht versehentlich fehlend.

2. Der korrekte Weg zur Antwort. SupersessionModule ist der explizite Weg, um zu erfahren, was mit RFC 2616 passiert ist – eine Abfrage, die es benennt, gibt die echte 6-fache Nachfolgeliste zurück (RFC 7230-7235).

Router-Kalibrierung – gemessen, nicht geraten

Die angegebenen Bibliotheksstandards von consilium.router.Router (floor=0.11, anchor_centroid=0.25, anchor_best_chunk=0.25) nehmen eine nahezu Null-Baseline-Kosinus zwischen unzusammenhängenden Texten an – wahr für einen Bag-of-Words-HashEmbedder, nicht unbedingt wahr für einen echten dichten Embedder über einen 321k-Chunk-Korpus (die gleiche Lücke zeigt sich sogar bei einer viel kleineren Skala von ~1.100 Chunks). agenticrag/calibrate.py misst dies direkt gegen den echten Korpus + echten Embedder, anstatt es anzunehmen; siehe agenticrag/bootstrap.py::ROUTER_KWARGS für die resultierenden Pro-Instanz-Kwargs und die echten Zahlen, die die Entscheidung rechtfertigten.

.venv\Scripts\python agenticrag\calibrate.py

GPU-Hinweis (nur Ingest)

GPU ist für genau einen Schritt wichtig: den Korpus-Ingest (ingest/run_ingest.py), der ~321k Chunks mit BAAI/bge-base-en-v1.5 über onnxruntime einbettet. Zur Abfragezeit bettest du nur die (kurze) Abfragezeichenfolge ein, daher laufen die Launcher problemlos auf CPU ohne GPU-Einrichtung – weshalb sie keine GPU-Konfiguration mehr berühren.

Erwartete und harmlose Warnung: Wenn onnxruntime-gpu installiert ist, aber die passenden CUDA-Runtime-DLLs nicht im Suchpfad liegen, erscheint ein alarmierender roter Block CUDAExecutionProvider / Error loading ... cublasLt64_*.dll ... missing – bei jedem Lauf, Ingest oder Abfrage, nicht nur beim Ingest. Es ist kein Fehler: onnxruntime fällt auf CPU zurück und fährt fort (bei einer Abfrage ist das Embed ein kurzer String, daher ist der CPU-Fallback sofort). Ignorieren Sie es oder installieren Sie die unten genannten DLLs, um es zu unterdrücken.

Für einen schnellen Ingest benötigt der CUDA-Execution-Provider von onnxruntime-gpu diese CUDA-Runtime-DLLs im DLL-Suchpfad. pip install onnxruntime-gpu allein bündelt sie nicht, und ohne sie fällt onnxruntime auf CPU zurück (gemessen: ~6 Chunks/Sek. – berechnet: ≈14,9 Stunden für den vollständigen 321.124-Chunk-Korpus), anstatt einen Fehler zu werfen. Um echte GPU-Ausführung zu erhalten (gemessen: ~650 Chunks/Sek. auf einer RTX 5090, d. h. ≈8 Minuten für den vollständigen Korpus), installieren Sie die passenden CUDA-Runtime-Wheels in die eigene venv dieses Repos, z. B.:

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

(Passen Sie das Suffix -cuNN an die CUDA-Hauptversion Ihres onnxruntime-gpu-Builds an) oder fügen Sie das torch/lib-Verzeichnis einer beliebigen CUDA-fähigen PyTorch-Installation vor dem Ausführen des Ingest zu PATH hinzu. In jedem Fall ist dies eine optionale Beschleunigung des einmaligen Ingest, die nie erforderlich ist, um die Demo auszuführen oder Abfragen zu bedienen.

Erneute Ingest-Läufe (bekannte Einschränkung)

ingest/run_ingest.py unterstützt einen --recreate-Neuaufbau von Grund auf und einen schnellen inkrementellen Pfad (der nur Rohdateien neu einbettet, deren Inhalts-Hash sich geändert hat). Der inkrementelle Pfad hat zwei bekannte Einschränkungen, die bewusst nicht übertüncht werden: (1) Er bewertet „geändert“ ausschließlich anhand des Byte-Hashs jeder Rohdatei. Wenn also ein RFC in einer späteren rfc-index.txt-Aktualisierung neu als veraltet markiert wird, ohne dass sich seine eigene Textdatei ändert, kann sein is_current-Flag veralten; und (2) er löscht keine verwaisten Qdrant-Punkte für ein Dokument, das bei erneutem Ingest in weniger Chunks aufgeteilt wird. Für einen garantiert konsistenten Speicher führen Sie ingest/run_ingest.py --recreate aus (ein vollständiger Neuaufbau). Beide Einschränkungen im inkrementellen Pfad zu schließen, ist zukünftige Arbeit.

Layout

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

Lizenz

Code: MIT (c) 2026 Trent Milam.

Der Korpus ist nicht in diesem Repo enthalten (data/ ist gitignored); er wird zur Build-Zeit von rfc-editor.org und iana.org abgerufen. IETF-RFC-/Errata-Texte unterliegen den IETF Trust Legal Provisions (der Abruf bewahrt die eigenen Urheberrechts-/Trust-Hinweise jedes Dokuments unversehrt); IANA-Registrierungsdaten werden von IANA veröffentlicht. Dieses Projekt redistribuiert nichts davon – es ruft es lokal auf Ihrem Rechner ab.