sutra-rag 0.1.0

Sutra-RAG: The Contextual Retriever library bridging raw data with LLM prompts

Sutra-RAG (The Contextual Retriever)

For Indonesian instructions, see README_id.md.

Sutra-RAG is a Retrieval-Augmented Generation (RAG) library designed to bridge raw data with Large Language Model (LLM) prompts. Based on recent scientific journal insights into context orchestration and hallucinations in LLMs, Sutra serves as the "factual grounding" layer, ensuring generative AI remains tied to strict contextual truths.

Key Features

• Vector-Graph Hybrid Search Ready: Built on the foundations of advanced contextual retrieval research, Sutra is designed to easily integrate dense vector similarity search (FAISS, pgvector) alongside structured knowledge graph analysis (e.g., using Mandala-GNN).
• Encoder-Agnostic Interface: Supports swapping of embedding models (SentenceTransformer, BGE, OpenAI) seamlessly through a unified interface.
• Semantic Reranker (Small ML): Implements lightweight cross-encoders to semantically reorder initially retrieved $k$-documents, ensuring cognitive alignment with user profiles as suggested in learning-outcome scientific literature.
• Dynamic Chunking: Intelligently fragments raw literature natively by tracking syntactical boundaries (like sentences), avoiding mid-sentence data starvation that often triggers LLM hallucinations.

Installation

pip install sutra-rag

Quick Start

Check the examples/ directory for full usage.

from sutra import SutraRAG
from sutra.encoder import SentenceTransformerEncoder
from sutra.retriever import FaissRetriever
from sutra.reranker import CrossEncoderReranker

# 1. Initialize Components
encoder = SentenceTransformerEncoder(model_name="all-MiniLM-L6-v2")
retriever = FaissRetriever(encoder=encoder)
reranker = CrossEncoderReranker(model_name="cross-encoder/ms-marco-MiniLM-L-6-v2")

# 2. Setup Pipeline
pipeline = SutraRAG(encoder=encoder, retriever=retriever, reranker=reranker)

# 3. Ingest Data
pipeline.add_document("Sutra-RAG bridges textual facts with semantic truth.")

# 4. Hybrid Context Extraction
results = pipeline.retrieve("What does Sutra-RAG do?", top_k=1)
print(results)

Scientific & Mathematical Foundations

Sutra-RAG operates on a scientifically-backed architecture designed to mathematically constrain LLM hallucination in educational domains. The retrieval performance is improved through a tripartite function mechanism: Dense Retrieval, Structural Graph Filtering, and Semantic Reranking.

1. Initial Dense Retrieval (Bi-Encoder)

The initial retrieval phase captures semantic similarity using a vector space model. Given a query $q$ and a document candidate $d$, they are encoded into $n$-dimensional embeddings $\mathbf{e}_q, \mathbf{e}d \in \mathbb{R}^n$. The similarity is formulated using Cosine Similarity or $L{2}$-Distance:

$$ \text{sim}(q, d) = \frac{\mathbf{e}_q \cdot \mathbf{e}_d}{ |\mathbf{e}_q| |\mathbf{e}_d| } $$

This ensures that the top-$K$ candidates are semantically aligned but does not guarantee contextual correctness in an educational flow.

2. Contextual Graph Validation (Mandala-GNN)

To prevent "conceptual leapfrogging", Sutra interfaces with Mandala-GNN. The relevance of document node $v_d$ within the knowledge graph $\mathcal{G} = (\mathcal{V}, \mathcal{E})$ is calculated computationally. Utilizing continuous Graph Neural Networks (GCN) or centrality metrics (e.g., PageRank), a structural score $S_{graph}(d)$ is derived:

$$ S_{graph}(d) = (1 - \lambda) + \lambda \sum_{u \in \mathcal{N}(v_d)} \frac{S_{graph}(u)}{\deg(u)} $$

Where $\mathcal{N}(v_d)$ represents the prerequisite nodes connected to the target document.

3. Cross-Encoder Reranking

While the bi-encoder enables fast indexing, it lacks deep interaction. We employ a highly articulate Cross-Encoder (Small ML) function $f_{CE}$ that takes the concatenated $[q ; d]$ input. The final mathematical performance orchestrator blends these three aspects into an ultimate Top-$K$ ranking:

$$ \text{FinalScore}(q, d) = \alpha \cdot f_{CE}(q, d) + \beta \cdot \text{sim}(q, d) + \gamma \cdot S_{graph}(d) $$

(where $\alpha, \beta, \gamma$ are tunable coefficients, often favoring $\alpha$ heavily).

By constraining the context retrieved to only the intersection of Semantic Proximity and Graph Relevancy, the LLM's generative prompt mathematically converges to precision, dropping hallucination rates significantly compared to standard naïve RAG approaches.

Scientific References & Theoretical Framework

Approach / Algorithm	Component in Sutra-RAG	Theoretical Goal / Journal Reference
Dense Passage Retrieval (DPR)	FaissRetriever, PgVectorRetriever	Karpukhin et al. (2020) - Dense Passage Retrieval for Open-Domain Question Answering. Proves that dense embedding spaces natively outperform sparse statistical rankers (TF-IDF/BM25) in semantic understanding.
Graph Convolution & Centrality	Mandala-GNN Integration	Kipf & Welling (2017) - Semi-Supervised Classification with Graph Convolutional Networks. Justifies the use of multi-hop prerequisite validation and Laplacian matrices to prevent invalid curriculum leaps.
Cross-Encoder Rescoring	CrossEncoderReranker	Nogueira & Cho (2019) - Passage Re-ranking with BERT. Establishes that full self-attention across [Query ; Document] concatenated inputs drastically improves top-K relevance over Bi-Encoders.
Syntactic Boundary Allocation	DynamicChunker	Gao et al. (2023) - Retrieval-Augmented Generation for Large Language Models: A Survey. Emphasizes that "mid-sentence starvation" causes LLM context fragmentation and directly drives generation hallucinations.