Why RAGNav?

Chunk-and-embed RAG loses the structure of a document: chunks cut across sections, "see Table 2" never matches Table 2, and the answer comes back without saying where it lives. RAGNav keeps documents as a graph of blocks (headings, paragraphs, captions, messages, clauses) with typed edges, retrieves with BM25 and local embeddings fused by reciprocal rank fusion, and expands hits along that structure so the evidence is coherent and traceable to a page and block id. The common path is pip install plus sentence-transformers: no vector database, no API key, reproducible offline benchmarks.

On SQuAD (500 validation questions, fully offline), hybrid RAGNav reaches R@3 = 0.956, ahead of BM25-only (0.932) and embedding-only (0.906). Reproduce with python benchmarks/squad_benchmark.py.

Features

Typed (py.typed, mypy-clean with disallow_untyped_defs).

Install

pip install ragnav                    # BM25 + structure/graph retrieval (numpy, rank-bm25)
pip install "ragnav[embeddings]"      # + sentence-transformers for hybrid retrieval (recommended)
pip install "ragnav[pdf]"             # + PyMuPDF and requests for PDF ingest

With uv: uv add "ragnav[embeddings]".

Other extras: messy (HTML via beautifulsoup4), reranking (cross-encoder), mistral (Mistral chat / embeddings client), all (everything except mistral), dev. Requires Python 3.10+.

Quickstart

Hybrid retrieval, no API key (pip install "ragnav[embeddings]"; downloads all-MiniLM-L6-v2 once):

from ragnav import RAGNavIndex, RAGNavRetriever
from ragnav.ingest.markdown import ingest_markdown_string

doc, blocks = ingest_markdown_string(
    "Paris is the capital of France.",
    name="demo.md",
)
index = RAGNavIndex.build(
    documents=[doc],
    blocks=blocks,
    use_sentence_transformers=True,
    vector_model="all-MiniLM-L6-v2",
    embed_batch_size=32,
)
retriever = RAGNavRetriever(index=index)
result = retriever.retrieve(
    "What is the capital of France?",
    top_k=5,
    expand_structure=False,
    expand_graph=False,
)
print(result.blocks[0].text)  # Paris is the capital of France.
print(result.confidence)  # ConfidenceLevel.HIGH

BM25-only works with the base install and no model download: pass build_vectors=False to RAGNavIndex.build and use_vectors=False to retrieve. result.blocks lists the best hit first, followed by the parent headings and children added by structure expansion.

Long PDFs and papers

PaperRAG routes the query to likely pages, retrieves inside them, and follows link_to edges to referenced figures, tables, sections, and appendices. The LLM is used to write the answer; embeddings stay local by default. Needs pip install "ragnav[pdf,mistral]", MISTRAL_API_KEY, and network access to download the PDF:

from ragnav.llm.mistral import MistralClient
from ragnav.net import download_pdf
from ragnav.papers import PaperRAG, PaperRAGConfig

llm = MistralClient()
cfg = PaperRAGConfig(max_pages=25, top_pages=4, follow_refs=True)

pdf_bytes = download_pdf("https://arxiv.org/pdf/2507.13334.pdf")
paper = PaperRAG.from_pdf_bytes(pdf_bytes, llm=llm, pdf_name="paper.pdf", cfg=cfg)
print(paper.answer("What experiments were conducted?", cfg=cfg))
# answer_cited: every sentence ends in [[block_id]]
print(paper.answer_cited("What does Figure 1 show?", cfg=cfg))

Or from the shell:

ragnav paper-pdf --pdf-url "https://arxiv.org/pdf/2507.13334.pdf" --query "What is Context Engineering?"

ragnav hybrid-pdf     --pdf-url "https://arxiv.org/pdf/2507.13334.pdf" --query "What is Context Engineering?"
ragnav vectorless-pdf --pdf-url "https://arxiv.org/pdf/2507.13334.pdf" --query "What is Context Engineering?"
ragnav agentic-pdf    --pdf-url "https://arxiv.org/pdf/2507.13334.pdf" --query "Summarize the paper's main contribution."

## Routed pages
- doc_id=pdf:2507.13334.pdf page=4 score=0.5423 N=3
- doc_id=pdf:2507.13334.pdf page=14 score=0.5298 N=7
- doc_id=pdf:2507.13334.pdf page=9 score=0.4662 N=4
- doc_id=pdf:2507.13334.pdf page=5 score=0.4597 N=3

Architecture

flowchart LR
    subgraph ingest["ragnav.ingest"]
        direction TB
        MD[markdown]
        PDF[pdf / pdf paper-mode]
        HTML[html]
        EML[email]
        CHAT[chat]
        LEGAL[legal]
    end

    ingest --> G["Blocks + typed Edges<br/>(BlockGraph: parent, next,<br/>link_to, reply_to, ...)"]
    G --> IDX["RAGNavIndex.build<br/>BM25Index + VectorIndex<br/>(sentence-transformers or llm.embed)"]

    subgraph retrieve["RAGNavRetriever.retrieve"]
        direction TB
        S1[BM25 search] --> F[Fusion: RRF or weighted]
        S2[Vector search] --> F
        F --> FL[Filters: doc ids, pages,<br/>metadata, ACL principal]
        FL --> RR[Optional CrossEncoderReranker]
        RR --> C[Confidence HIGH / MEDIUM / LOW]
        C --> XS[expand_structure] --> XG[expand_graph] --> P[content_policy]
    end

    IDX --> retrieve
    P --> RES[RetrievalResult<br/>blocks, confidence, trace]

    RES --> UP["PaperRAG / pipelines / QueryFallback<br/>answer_with_inline_citations"]
    CACHE[(SQLite EmbeddingCache<br/>RetrievalCache)] -.-> IDX
    CACHE -.-> retrieve

retrieve_paper() runs the same retrieval after route_pages_by_semantics picks the top pages, then follows link_to edges. EntityGraphRetriever (GraphRAG) is a separate path over an entity graph built from the same blocks.

Key design decisions:

• Blocks and edges, not chunks. Every ingester emits blocks with anchors (page, line range, URL, timestamp) and typed edges, so provenance and coherence come from the document itself rather than from chunk overlap.
• Rank fusion over score mixing. BM25 and cosine scores live on different scales; RRF combines rank positions and needs no per-corpus weight tuning. With a single contributing list, its own scores are kept so confidence still reflects match strength.
• Deterministic expansion. Structure and graph expansion are rule-based and keep the hits' relevance order (best hit first), so results are reproducible and can be truncated safely.
• Offline by default, LLM optional. Indexing and retrieval need no LLM. Clients implement a two-method LLMClient protocol (chat, embed); MistralClient and FakeLLMClient ship with the package.

Use cases and recipes

Offline recipes (base install only, no API key; run in CI), in examples/offline/:

More examples (most need MISTRAL_API_KEY and / or network) are indexed in examples/README.md: paper-mode PDFs, multi-document routing by semantics / description / metadata, agentic retrieval, entity GraphRAG over a PDF, SQuAD and CUAD retrieval. Notebooks live in cookbook/ (quickstart in Colab).

from ragnav import RAGNavIndex, RAGNavRetriever
from ragnav.cost import CostTracker
from ragnav.ingest.markdown import ingest_markdown_string
from ragnav.llm.fake import FakeLLMClient  # offline stand-in; use MistralClient() or your own
from ragnav.retrieval import QueryFallback

doc, blocks = ingest_markdown_string("# FAQ\n\nRefunds are issued within 30 days.\n", name="faq.md")
retriever = RAGNavRetriever(
    index=RAGNavIndex.build(documents=[doc], blocks=blocks, build_vectors=False)
)
tracker = CostTracker(budget_usd=0.50)  # check_budget() raises BudgetExceededError once spent
llm = FakeLLMClient(cost_tracker=tracker)
out = QueryFallback(retriever, llm).retrieve("money back?", use_vectors=False)
print(out.attempts, out.winning_query, out.final_result.confidence.value)
print(tracker.report().summary())

from ragnav.graphrag import EntityGraphRetriever, build_entity_graph
from ragnav.ingest.markdown import ingest_markdown_string

doc, blocks = ingest_markdown_string(
    "# Results\n\nBERT was evaluated on SQuAD and GLUE.\n\n"
    "# Datasets\n\nSQuAD is a reading comprehension dataset built from Wikipedia.\n",
    name="paper.md",
)
eg = build_entity_graph(blocks)
egr = EntityGraphRetriever(graph=eg, blocks_by_id={b.block_id: b for b in blocks})

out = egr.retrieve("Which dataset was BERT evaluated on?")
for b in out["blocks"][:3]:
    print(b.block_id, b.text)

from openai import OpenAI

from ragnav.llm.base import LLMClient


class OpenAIClient(LLMClient):
    def __init__(self):
        self.client = OpenAI()

    def chat(self, *, messages, model=None, temperature=0.0):
        r = self.client.chat.completions.create(
            model=model or "gpt-4o-mini",
            messages=messages,
            temperature=temperature,
        )
        return r.choices[0].message.content or ""

    def embed(self, *, inputs, model=None):
        r = self.client.embeddings.create(
            model=model or "text-embedding-3-small",
            input=list(inputs),
        )
        return [d.embedding for d in r.data]

Configuration

API overview

Benchmarks

Reproduce with python benchmarks/squad_benchmark.py and python benchmarks/cuad_benchmark.py after pip install "ragnav[embeddings]" datasets. No API key needed. Results are written to benchmarks/results/.

Retrieval accuracy (SQuAD)

500 questions over 447 unique passages from the rajpurkar/squad validation set (CC BY-SA 4.0), seed 42, all-MiniLM-L6-v2. On this easy pool the default MS MARCO MiniLM cross-encoder trails RRF alone; use a domain-tuned reranker or skip reranking.

python3 -m benchmarks.scorecard

Research and references

RAGNav implements these published methods:

• BM25 lexical retrieval (via rank-bm25): S. Robertson and H. Zaragoza, "The Probabilistic Relevance Framework: BM25 and Beyond," Foundations and Trends in Information Retrieval, 3(4), 2009.
• Reciprocal Rank Fusion with k = 60 in _rrf_fuse: G. V. Cormack, C. L. A. Clarke, and S. Büttcher, "Reciprocal Rank Fusion outperforms Condorcet and individual rank learning methods," SIGIR 2009.
• Sentence embeddings via sentence-transformers (all-MiniLM-L6-v2 by default): N. Reimers and I. Gurevych, "Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks," EMNLP-IJCNLP 2019.
• Cross-encoder reranking (CrossEncoderReranker, MS MARCO MiniLM by default): R. Nogueira and K. Cho, "Passage Re-ranking with BERT," arXiv:1901.04085, 2019.

Benchmark datasets: SQuAD (P. Rajpurkar et al., EMNLP 2016) and CUAD (D. Hendrycks et al., NeurIPS 2021 Datasets and Benchmarks).

RAGNav is an independent project and is not affiliated with PyMuPDF, Mistral, or the dataset authors. If you notice missing or incorrect attribution, please open an issue.

When to use it

• Good fit: long PDFs and structured documents where where the answer lives matters (papers, manuals, reports, contracts), mixed sources (markdown, chat, email, HTML), offline or air-gapped retrieval, and teams that want reproducible retrieval metrics.
• Less suited: very large corpora that need an external vector database and approximate nearest-neighbour search (RAGNav keeps indexes in process memory), or pipelines that already depend on a full orchestration framework.

Roadmap

• Clause-level legal retrieval (current CUAD S@3 is 0.071).
• A reproducible, documented protocol for finance-PDF benchmarks.
• Persisted on-disk indexes for faster restarts.
• More built-in LLM clients behind the same LLMClient protocol.

Contributing, security, citation, license

• Issues and pull requests are welcome; see CONTRIBUTING.md and the Code of Conduct. CI runs ruff check, ruff format --check, mypy ragnav, and pytest --cov on Python 3.10-3.13.
• Report vulnerabilities privately as described in SECURITY.md.
• If you use RAGNav in research, please cite it via CITATION.cff (GitHub's "Cite this repository" button reads it).
• Release history: CHANGELOG.md.
• MIT License, see LICENSE.