Probabilistic retrieval-augmented generation on statistical manifolds with sub-100ms Cloudflare Clef decision routing, Woodbury-accelerated geometric kernels, and universal corpus generation. Every chunk of knowledge is a Gaussian distribution, not a flat vector. Retrieval is information geometry, accelerated to production speed.

Manifold — Gaussian-Clef RAG

개요

검색 증강 생성(RAG)을 위한 Python 라이브러리(3.10+) — AI가 질문에 답하기 전에 문서 모음에서 관련 구절을 검색하는 기술. 차이점: 각 텍스트 청크를 고차원 공간의 단일 지점(표준 접근 방식)으로 표현하는 대신, 각 청크를 가우시안 분포 — 중심(평균 의미)과 퍼짐(불확실성)을 가진 "구름" — 으로 표현합니다. 검색은 두 구름이 얼마나 겹치는지의 문제가 됩니다.

기본 사용에는 API 키가 필요 없이 100% 로컬에서 실행됩니다. 추가 기능을 위한 선택적 클라우드 통합이 있습니다.

핵심 아이디어

각 텍스트 청크는 확률 분포 𝒩(μ, Σ)에 매핑됩니다:

μ (평균) — 의미적 의미. 로컬 SentenceTransformer 또는 Gemini 임베딩에서 가져옴
Σ (공분산) — 방향적 불확실성. 대각선 + 저랭크 분해(기본 랭크 8)로 모델링

검색은 쿼리 분포가 각 문서 분포에 얼마나 많은 확률 질량을 두는지 점수를 매깁니다 — **기대 우도 커널(ELK)**이라는 메트릭.

왜 빠른가

두 고차원 분포를 비교하려면 일반적으로 큰 행렬을 역행렬해야 합니다(O(d³) 연산). 이 프로젝트는 Woodbury 행렬 항등식과 Sylvester 행렬식 정리를 사용하여 이를 O(d·r²)로 줄입니다. 여기서 r=8 — 150ms 연산을 3ms 미만으로 바꿉니다. 다른 최적화와 결합하여 이 프로젝트는 엔드투엔드 검색 100ms 미만을 주장합니다.

주요 구성 요소

구성 요소	기능	주장되는 영향
Woodbury ELK 가속	빠른 커널 평가를 위한 수학적 트릭	150ms → <3ms
Cloudflare Clef 결정 라우팅	Cloudflare의 AI 모델을 사용하여 모호한 쿼리를 감지하고 명확화 질문을 함	1,500ms → <40ms
이중 저장소 수집	각 청크를 두 번 인덱싱: 밀집 벡터 저장소 + SQLite 전체 텍스트 검색(FTS5)	2ms 미만 후보 검색
분류 가지치기	계층적 클러스터링이 재순위화 전에 관련 없는 가지를 건너뜀	후보의 60–80% 가지치기
Clef 4-질문 구절 게이트	관련성, 증거, 모순에 대한 병렬 필터	약 30개 후보 → 상위 5–8개로 가지치기
범용 수집 엔진	원시 텍스트, Markdown, JSON/JSONL, CSV, 파일, 디렉토리 허용	전처리 보일러플레이트 제로
유연한 코퍼스 생성기	지저분한 텍스트(HTML, OCR 스캔, 채팅 기록)를 캐싱과 함께 구조화된 코퍼스로 정리	즉시 깨끗한 코퍼스 생성

사용 방법

from gaussian_rag import GaussianRAG

rag = GaussianRAG.create()
rag.add_texts(["Passage 1", "Passage 2", "Passage 3"])

results = rag.search("your question", top_k=3)
answer = rag.query("your question")  # 선택적 LLM 생성 답변

또한 지원:

수집: add_markdown(), add_records() (JSON/JSONL), add_file(), add_directory(), add_raw_text() (지저분한 텍스트 자동 정리)
영속성: rag.save("path") 및 GaussianRAG.load("path")
CLI: python -m gaussian_rag.main ingest/query, 코퍼스 생성 스크립트(data/generate_corpus.py) 포함
평가: python test_48_laws_e2e.py는 『권력의 48법칙』에서 전체 파이프라인을 검증; pytest는 지연 시간 벤치마크를 포함한 테스트 스위트 실행

선택적 통합

Cloudflare Workers AI — Clef 결정 라우팅 및 구절 게이팅 활성화 (CLOUDFLARE_ACCOUNT_ID 및 CLOUDFLARE_API_TOKEN 설정)
OpenAI / Gemini / Mistral — LLM 답변 생성용 (각 API 키 설정)

구성은 config/config.yaml에 있습니다 (임베딩 백엔드, 차원, 저랭크 크기, 검색 메트릭, 청킹 매개변수).

추가 기능

3D 대시보드: FastAPI 백엔드(포트 8001) + Vite 프론트엔드(포트 5173). 대화형 가우시안 타원체, Server-Sent Events를 통한 실시간 단계별 지연 시간 원격 측정, Clef 결정 추적 표시
문서: docs/에 아키텍처, 설계 결정, 이론, 사용법을 다루는 광범위한 문서

라이선스

GNU Affero General Public License v3.0 (AGPL-3.0).

myneace/Gaussian_Clef_RAG