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 자체의 텍스트에는 "현재 개정판"이 없으므로(여섯 개의 후속 문서, RFC 7230-7235 -- IETF의 유명한 다중 폐기 사례 -- 에 의해 완전히 대체됨), 이 질문은 검색이 아닌 실제 Obsoletes/Obsoleted-by 그래프에 대한 결정적 그래프 조회인 SupersessionModule이 답변합니다. 답변 경로에는 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

하나의 저장소, 다섯 개의 병합된 도구

agentic-rag는 이전에 consilium과 linkgraph를 형제 저장소에서 가져오기 위해 그 루트를 sys.path에 삽입했으며, 세 번째 저장소에서 RAGpack을 편집 가능한 상태로 pip 설치해야 했습니다. 이 저장소를 클론한다는 것은 세 개의 서로 다른 파일에 고정된 세 개의 커밋에서 네 개의 저장소를 클론한다는 뜻이었습니다. -- 이미 서로 어긋나 있었습니다. linkgraph는 또한 이 저장소의 데이터 파일을 읽었기 때문에, 두 도구는 저장소 경계를 넘어 서로를 가져왔습니다.

이제는 하나의 저장소입니다. 병합된 각 도구는 전체 트리를 packages/<name>/ 아래에 유지하므로, 자체 루트를 기준으로 해석하는 모든 것이 여전히 해석되며, 각 도구는 import 커밋으로 스쿼시되지 않고 자체 커밋 기록을 유지했습니다:

이들이 저장소 루트가 아닌 packages/ 아래에 중첩된 데는 구체적인 이유가 있습니다. consilium이라는 최상위 디렉터리는 암시적 네임스페이스 패키지로서 consilium 패키지를 가리게 됩니다. 작업 디렉터리가 sys.path에서 편집 가능한 설치보다 앞서기 때문입니다. 그러면 import가 빈 네임스페이스로 해석되고 consilium.__file__은 None이 됩니다. CI는 모든 패키지가 이 저장소 내부의 파일로 해석되는지 확인하므로, 이러한 조용한 잘못된 바인딩은 잘못된 복사본에 대해 모든 테스트를 통과시키는 대신 빌드를 실패시킵니다.

rag-reliability는 여전히 이 저장소 외부에 있는 유일한 의존성입니다. 위 도구 중 세 개에 graphrx, headroom, vecstamp, chunkledger, plumbline, legigate를 제공하며, 현재는 경로로 해석됩니다. 이를 선언된 의존성으로 만들 수 있도록 패키징하는 것이 남은 후속 작업입니다. CI는 이를 고정된 상태로 체크아웃하고 해당 통합 테스트가 건너뛰면 실패하므로, 남은 경로 의존성은 눈에 띄지 않게 썩을 수 없습니다.

코퍼스

총 321,124개의 실제 청크가 실제 BAAI/bge-base-en-v1.5 모델로 임베딩되었습니다. rfc_text/rfc_index만이 개정 개념이 있는 소스 유형입니다. -- 여기서 is_current는 실제 구조적 사실입니다(개정 가드 참조). 추측이 아닙니다.

다섯 개의 모듈, 하나의 라우터

agenticrag/bootstrap.py::build_registry는 실제 5-모듈 consilium Registry를 조립합니다: 위의 4개 검색 모듈(각각 Qdrant에서 직접 로드되며 기본적으로 current_only=True -- agenticrag/registry_loader.py 참조)과 SupersessionModule(agenticrag/supersession.py)을 포함합니다. SupersessionModule은 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개의 실제 정오표 레코드 중 단 2,400개(47.4%)만이 RFC Editor에 의해 Verified 입니다 -- 1,781개(35.2%)는 Held for Document Update, 679개(13.4%)는 완전히 Rejected, 201개(4.0%)는 여전히 Reported입니다. 실제 제출된 수정 사항 중 절반 미만이 RFC Editor 확인을 받았으므로, 이 모듈은 자체적으로 균일하게 권위적이지 않으면서 기본 텍스트를 수정합니다.

MCP 서버

agenticrag/mcp/server.py는 답변 경로를 stdio를 통한 Model Context Protocol 서버로 노출합니다(mcp>=1.28.1, FastMCP). 네 가지 도구:

• 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을 통해 프로토콜을 말합니다). 도구 로직은 import가 가볍고 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의 임베디드 로컬 모드는 정확한 brute-force(ANN 인덱스 없음)이므로 검색은 여전히 필터링된 하위 집합을 스캔합니다 -- 그러나 네이티브 코드에서 top-k만 구체화하므로 이전 순수 Python 청크별 스캔보다 약 16배 빠릅니다. (1초 미만 검색은 Qdrant 서버 모드의 HNSW 인덱스가 필요합니다. 로컬 모드는 저장소를 자체 포함으로 유지합니다 -- 실행할 서버가 없습니다.) 다음을 확인합니다: 소스 유형당 하나의 범위 내 쿼리(합리적인 모듈 + >=1 실제 인용); RFC 2616 폐기 쿼리(후속 집합은 정확히 {7230, 7231, 7232, 7233, 7234, 7235}); 하나의 범위 외 쿼리(정직한 기권); 개정 가드 구조적 제외(아래); 실제로 현재 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)은 실제로 단일한 전체 문서입니다. -- 이에 대한 "현재 개정판"은 없습니다. 여섯 개의 서로 다른 문서에 의해 완전히 대체되었습니다. 여기서 가드 속성은 하나의 "수정된 값"이 아니라 두 가지 실제적이고 확인 가능한 사실입니다:

1. 구조적 제외. RFC 2616의 자체 rfc_text 청크는 Qdrant에 존재합니다(current_only=False로 rfc_text 모듈을 두 번째 로드하면 존재함이 증명됨) 그러나 모든 쿼리가 실제로 사용하는 기본 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)은 관련 없는 텍스트 사이의 기준 코사인이 거의 0이라고 가정합니다 -- bag-of-words HashEmbedder에는 해당되지만, 321k-청크 코퍼스에 대한 실제 밀집 임베더에는 반드시 해당되지 않습니다(같은 차이는 훨씬 작은 약 1,100-청크 규모에서도 나타납니다). agenticrag/calibrate.py는 이를 가정하지 않고 실제 코퍼스 + 실제 임베더에 대해 직접 측정합니다. 결과적인 인스턴스별 kwargs와 결정을 정당화한 실제 수치는 agenticrag/bootstrap.py::ROUTER_KWARGS를 참조하세요.

.venv\Scripts\python agenticrag\calibrate.py

GPU 참고 사항 (수집 전용)

GPU는 정확히 한 단계에서 중요합니다: 코퍼스 수집(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로 폴백하여 계속 실행됩니다(쿼리의 경우 임베드는 짧은 문자열 하나이므로 CPU 폴백은 즉시 이루어집니다). 무시하거나, 아래 DLL을 설치하여 조용히 처리하세요.

빠른 인제스트를 위해 onnxruntime-gpu의 CUDA 실행 제공자는 DLL 검색 경로에 해당 CUDA 런타임 DLL이 필요합니다. pip install onnxruntime-gpu만으로는 이들을 번들로 포함하지 않으며, DLL이 없으면 onnxruntime은 오류를 발생시키는 대신 CPU로 폴백합니다(측정 결과: ~6 chunks/초 -- 계산 결과: 전체 321,124개 청크 코퍼스에 약 14.9시간). 실제 GPU 실행을 얻으려면(측정 결과: RTX 5090에서 ~650 chunks/초, 즉 전체 코퍼스에 약 8분), 일치하는 CUDA 런타임 휠을 이 저장소의 자체 venv에 설치하세요. 예:

.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와 빠른 증분 경로(콘텐츠 해시가 변경된 원시 파일만 다시 임베드)를 지원합니다. 증분 경로에는 의도적으로 감추지 않은 두 가지 알려진 제한 사항이 있습니다: (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가 게시합니다. 이 프로젝트는 그중 어떤 것도 재배포하지 않습니다. -- 사용자 머신에서 로컬로 가져올 뿐입니다.