agentic-rag

Recuperación con citas y consciente de revisiones sobre un corpus real extraído del ecosistema de RFC del IETF: el texto completo de las RFC, el grafo real de sustitución Obsoletas/Obsoletas por/Actualizaciones del índice de RFC, erratas reales enviadas por la comunidad y registros reales de parámetros de protocolo de IANA, obtenidos por HTTPS (corpus_fetch/) e ingeridos mediante ragpack en un almacén vectorial consultable (321.124 fragmentos reales), y luego enrutados y controlados por citas a través del eje consilium.

Haz una pregunta real sobre una especificación de protocolo del IETF, la autoría/estado de una RFC, una corrección de errata real o una entrada de registro de IANA, y obtén una respuesta construida enteramente a partir de fragmentos reales citados — o una abstención honesta. La única excepción es una pregunta de obsolescencia ("¿qué reemplazó a la RFC 2616?"): no existe una "revisión actual" del propio texto de la RFC 2616 (fue completamente sustituida por seis documentos posteriores, RFC 7230-7235, el famoso caso de obsolescencia múltiple del propio IETF), por lo que se responde mediante SupersessionModule, una búsqueda determinista en el grafo real de Obsoletas/Obsoletas por, no mediante recuperación. Ningún LLM en la ruta de respuesta.

Inicio rápido

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

Eso es todo el arranque. La instalación editable es lo que hace que import consilium, import ragpack, import linkgraph, import activerag e import chainrag se resuelvan: el package-dir de pyproject.toml asigna cada nombre a packages/.

Responder a una pregunta real además necesita el corpus ingerido; consulta El corpus y Verificar.

Related MCP server: DocuMind MCP

Un repositorio, cinco herramientas fusionadas

agentic-rag solía importar consilium y linkgraph desde repositorios hermanos insertando sus raíces en sys.path, y requería RAGpack instalado editable desde un tercero. Clonarlo significaba clonar cuatro repositorios en tres commits fijados en tres archivos separados, que ya se habían desviado entre sí. linkgraph también leía el archivo de datos de este repositorio, por lo que ambos se importaban mutuamente a través de un límite de repositorio.

Ahora son un solo repositorio. Cada herramienta fusionada mantuvo todo su árbol bajo packages/<nombre>/, de modo que todo lo que resuelve relativo a su propia raíz sigue resolviéndose, y cada una conservó su propio historial de commits en lugar de ser aplastada en un commit de importación:

Están anidados bajo packages/ en lugar de estar en la raíz del repositorio por una razón concreta: un directorio de nivel superior llamado consilium oculta el paquete consilium como un paquete de espacio de nombres implícito, porque el directorio de trabajo precede a la instalación editable en sys.path. Las importaciones entonces se resuelven a un espacio de nombres vacío y consilium.__file__ es None. CI verifica que cada paquete se resuelva a un archivo dentro de este repositorio, de modo que esa clase de vinculación incorrecta silenciosa falle la compilación en lugar de pasar todas las pruebas contra la copia equivocada.

rag-reliability es la única dependencia que sigue fuera de este repositorio. Proporciona graphrx, headroom, vecstamp, chunkledger, plumbline y legigate a tres de las herramientas anteriores, y se resuelve por ruta hoy; empaquetarlo para que pueda ser una dependencia declarada es el seguimiento pendiente. CI lo verifica fijado y falla si esas pruebas de integración se omiten, de modo que la única dependencia de ruta restante no puede pudrirse sin ser notada.

El corpus

321.124 fragmentos reales en total, incrustados con el modelo real BAAI/bge-base-en-v1.5. rfc_text/rfc_index son los únicos tipos de fuente con concepto de revisión: is_current allí es un hecho estructural real (ver la protección de revisión), no adivinado.

Cinco módulos, un enrutador

agenticrag/bootstrap.py::build_registry ensambla un Registry real de consilium con 5 módulos: los 4 módulos de recuperación anteriores (cada uno cargado directamente desde Qdrant, current_only=True por defecto -- ver agenticrag/registry_loader.py), más SupersessionModule (agenticrag/supersession.py), un ComputeModule que analiza data/entities/revisions.json -- el grafo real de Obsoletas/Obsoletas por para las 9.794 RFC del índice en vivo -- una vez en la construcción y responde preguntas de obsolescencia con un recorrido determinista y seguro ante ciclos (acotado a 50 nodos visitados -- un límite defensivo, no un límite real esperado; los componentes reales de obsolescencia del IETF son pequeños).

build_registry también falla de forma ruidosa si el incrustador configurado del proceso no coincide con el que ingirió el almacén (verify_embedder_marker, llamado primero) -- de lo contrario, las puntuaciones de coseno serían silenciosamente sin sentido -- y cierra cualquier cliente Qdrant que haya abierto él mismo una vez que los módulos están cargados (la recuperación es completamente en memoria después), de modo que no mantiene el bloqueo del almacén en modo local durante toda la vida del proceso del llamador.

El trust_tier de errata (0,55, muy por debajo del 0,9-0,95 de rfc_text/rfc_index/iana_registry) se mide, no se adivina: de los 5.061 registros de errata reales ingeridos, solo 2.400 (47,4%) están Verified por el Editor de RFC -- 1.781 (35,2%) están Held for Document Update, 679 (13,4%) están directamente Rejected, y 201 (4,0%) siguen Reported. Menos de la mitad de las correcciones reales enviadas están confirmadas por el Editor de RFC, por lo que este módulo corrige el texto principal sin ser uniformemente autoritativo en sí mismo.

Servidor MCP

agenticrag/mcp/server.py expone la ruta de respuesta como un servidor Model Context Protocol sobre stdio (mcp>=1.28.1, FastMCP). Cuatro herramientas:

• search(query) -- la ruta completa de respuesta con citas/abstención (consilium.compute.answer_v3), pasada verbatim (una abstención honesta sigue siendo una abstención);

• get_obsoletion_chain(rfc_id) / get_corrections(rfc_id) / get_related(entity_id) -- el grafo de relaciones, a través del hermano linkgraph (agenticrag/relationships.py); cada una devuelve un sobre documentado {"ok": false, "fallback": ...} si ese hermano está ausente.

Ejecútalo: .venv\Scripts\python -m agenticrag.mcp.server (transporte stdio -- un cliente MCP lo lanza y habla el protocolo por stdin/stdout). La lógica de la herramienta es ligera en importaciones y no tiene dependencia de mcp/Qdrant, por lo que se prueba unitariamente sin ninguno de ellos (agenticrag/mcp/test_server.py).

Verificar

Verificación rápida (rápida, sin corpus -- no se necesita corpus ingerido):

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

Ejecuta las pruebas del envoltorio de herramientas MCP y la suite de seguridad ante ciclos del recorrido del grafo de supersesión. Esto es lo que CI ejecuta en cada push (ver la insignia arriba).

Verificación completa (necesita el corpus ingerido de 321k fragmentos del Inicio rápido):

.venv\Scripts\python eval\eval_agenticrag.py

Determinista dado el corpus ya ingerido; sin re-ingerir. Usa el incrustador real -- exactamente el que ingirió el corpus -- por lo que demuestra una recuperación semántica genuina de extremo a extremo, no solo el cableado. Tarda ~3,3 min en este hardware (medido, ejecución completa: 196s): una construcción de registro única de ~60s (un solo escaneo del corpus para el pequeño conjunto de cuarentena de veneno -- no una carga de los 321k vectores), luego las pasadas de enrutador/respuesta a ~12s cada una. Cada pasada ejecuta el enrutamiento y la recuperación como búsquedas vectoriales nativas de Qdrant; el modo local integrado de Qdrant es fuerza bruta exacta (sin índice ANN), por lo que una búsqueda aún escanea el subconjunto filtrado -- pero en código nativo, materializando solo los top-k, ~16 veces más rápido que el antiguo escaneo por fragmento en Python puro. (Una búsqueda de sub-segundo requeriría el índice HNSW del modo servidor de Qdrant; el modo local mantiene el repositorio autocontenido -- sin servidor que ejecutar). Comprueba: una consulta dentro del alcance por tipo de fuente (módulo sensato + >=1 cita real); la consulta de obsolescencia de RFC 2616 (el conjunto de sucesores es exactamente {7230, 7231, 7232, 7233, 7234, 7235}); una consulta fuera del alcance (abstención honesta); la exclusión estructural de la protección de revisión (abajo); una RFC genuinamente actual (791) que resuelve current; y un número de RFC ausente (99999) que resuelve not_found, no un fallo.

eval/prove_revision_guard.py es la misma prueba estructural como un script independiente y narrado. eval/smoke_ingest_real.py demuestra el cableado fetch->ingest->Qdrant con el HashEmbedder de costo cero (necesita que corpus_fetch.fetch_all se haya ejecutado, pero no GPU/modelo de incrustación).

La protección de revisión, demostrada

La RFC 2616 (HTTP/1.1) es un documento real, único y completo -- no existe una "revisión actual" de él; fue completamente sustituida por seis documentos diferentes. La propiedad de protección aquí son dos hechos reales y comprobables, no un "valor corregido":

1. Exclusión estructural. Los fragmentos rfc_text de la propia RFC 2616 existen en Qdrant (cargar el módulo rfc_text una segunda vez con current_only=False demuestra que están allí) pero están ausentes del módulo current_only=True por defecto que cada consulta usa realmente -- porque data/entities/revisions.json["RFC2616"]["obsoleted_by"] es real y no vacío. Los datos existen; están filtrados estructuralmente, no faltan accidentalmente.

2. La ruta correcta a la respuesta. SupersessionModule es la forma explícita de saber qué le pasó a la RFC 2616 -- una consulta que la nombre devuelve la lista real de 6 sucesores (RFC 7230-7235).

Calibración del enrutador -- medida, no adivinada

Los valores predeterminados declarados de la biblioteca de consilium.router.Router (floor=0.11, anchor_centroid=0.25, anchor_best_chunk=0.25) asumen un coseno de línea base casi cero entre texto no relacionado -- cierto para un HashEmbedder de bolsa de palabras, no necesariamente cierto para un incrustador denso real sobre un corpus de 321k fragmentos (la misma brecha aparece incluso a una escala mucho menor de ~1.100 fragmentos). agenticrag/calibrate.py mide esto directamente contra el corpus real + incrustador real en lugar de asumirlo; ver agenticrag/bootstrap.py::ROUTER_KWARGS para los kwargs por instancia resultantes y los números reales que justificaron la decisión.

.venv\Scripts\python agenticrag\calibrate.py

Nota sobre GPU (solo ingesta)

La GPU importa para exactamente un paso: la ingesta del corpus (ingest/run_ingest.py), que incrusta ~321k fragmentos con BAAI/bge-base-en-v1.5 mediante onnxruntime. En tiempo de consulta solo incrustas la cadena de consulta (corta), por lo que los lanzadores funcionan bien en CPU sin configuración de GPU -- por eso ya no tocan ninguna configuración de GPU.

Advertencia esperada e inofensiva: si onnxruntime-gpu está instalado pero sus DLL de runtime CUDA correspondientes no están en la ruta de búsqueda, verás un bloque rojo alarmante de CUDAExecutionProvider / Error loading ... cublasLt64_*.dll ... missing — en cualquier ejecución, ya sea de ingesta o de consulta, no solo en la ingesta. No es un fallo: onnxruntime recurre a la CPU y continúa (para una consulta, el embed es una sola cadena corta, por lo que la alternativa de CPU es instantánea). Ignóralo, o instala las DLL que se indican abajo para silenciarlo.

Para una ingesta rápida, el proveedor de ejecución CUDA de onnxruntime-gpu necesita esas DLL de runtime CUDA en la ruta de búsqueda de DLL. pip install onnxruntime-gpu por sí solo no las incluye, y sin ellas onnxruntime recurre a la CPU (medido: ~6 chunks/seg — calculado: ≈14.9 horas para el corpus completo de 321,124 chunks) en lugar de generar un error. Para obtener una ejecución real con GPU (medido: ~650 chunks/seg en una RTX 5090, es decir, ≈8 minutos para el corpus completo), instala las ruedas de runtime CUDA correspondientes en el venv propio de este repositorio, por ejemplo:

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

(empareja el sufijo -cuNN con la versión mayor de CUDA de tu compilación de onnxruntime-gpu), o pon el directorio torch/lib de cualquier instalación de PyTorch con CUDA habilitado en PATH antes de ejecutar la ingesta. De cualquier manera, esto es una aceleración opcional de la ingesta única, nunca requerido para ejecutar la demo o servir consultas.

Re-ejecuciones de ingesta (limitación conocida)

ingest/run_ingest.py admite una reconstrucción desde cero con --recreate y una ruta incremental rápida (solo re-embed los archivos crudos cuyo hash de contenido haya cambiado). La ruta incremental tiene dos limitaciones conocidas, deliberadamente no disimuladas: (1) considera "cambiado" únicamente según el hash de bytes de cada archivo crudo, por lo que si un RFC queda obsoleto en una actualización posterior de rfc-index.txt sin que su propio archivo de texto cambie, su indicador is_current puede quedar desactualizado; y (2) no elimina los puntos Qdrant huérfanos de un documento que se re-ingesta con menos chunks. Para un almacén con consistencia garantizada, ejecuta ingest/run_ingest.py --recreate (una reconstrucción completa). Cerrar ambas limitaciones en la ruta incremental es trabajo futuro.

Diseño

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

Licencia

Código: MIT (c) 2026 Trent Milam.

El corpus no está incluido en este repositorio (data/ está en gitignore); se obtiene en tiempo de compilación desde rfc-editor.org e iana.org. El texto de los RFC/erratas de IETF está sujeto a las Disposiciones Legales del IETF Trust (la descarga preserva intacto el aviso de copyright/Trust de cada documento); los datos de los registros de IANA son publicados por IANA. Este proyecto no redistribuye nada de eso — lo descarga, localmente, en tu máquina.