RAG-Tutorials Shows Why Good Retrieval Is a Systems Problem

A modular tour through ingestion, FAISS, agentic retrieval, and vectorless document navigation that shows how RAG matures beyond naive chunk search.

8 min read • View on GitHub • More from krishnaik06

A wide black-ink editorial scene on white background. On one side, a document is split into many small chunks that feed a dense lattice of search paths. On the other, a retrieval agent stands at a fork between vector search, tree navigation, and direct answering. It explains that RAG is really a choice of retrieval strategy, not a single pipeline. — The repo’s big idea is not that retrieval exists. It is that different questions deserve different retrieval moves.

Key Takeaways

This repo treats RAG as a sequence of retrieval decisions, not a fixed embed-and-search recipe.
Its modular core matters because ingestion, embedding, storage, and search are separated cleanly enough to swap strategies without rewriting the whole stack.
The agentic notebook changes the default question from “how do we retrieve?” to “should we retrieve at all?”
The vectorless PageIndex material pushes the strongest point in the repo: structure can beat similarity when the document has real hierarchy.

The Chunk Is Not the Whole Story

Most RAG tutorials stop at the obvious loop: split text, embed it, search nearest chunks, generate an answer. RAG-Tutorials keeps going, and that is why it is useful. The repo is really about a harder question: what if retrieval is not one mechanism, but a set of choices?

That framing matters because real documents are not bags of semantically similar fragments. They have sections, headings, footnotes, and context that a closest-vector match can miss. This repo keeps returning to that gap.

What This Repo Teaches That Most RAG Tutorials Skip

Layer	Standard tutorial	RAG-Tutorials
Ingestion	One document type, one happy path	A loader that scans PDFs, TXT, CSV, XLSX, DOCX, and JSON
Retrieval trigger	Always retrieve	Sometimes retrieve, if the question needs it
Storage	Vectors only	Vectors plus metadata you can map back to text
Document shape	Flat chunks	Flat chunks, then hierarchical navigation
Teaching goal	Show the API	Show the system decisions behind the API

The repo reads like a staged curriculum, but the lesson is not “here are more notebooks.” The lesson is that mature RAG work expands outward from embeddings into orchestration, evaluation, and document structure.

The Modular Core: Ingest, Embed, Store, Search

The `src/` directory separates the boring parts of RAG on purpose. That separation is what makes the later experiments possible.

The core code path is straightforward in the best way. `data_loader.py` gathers heterogeneous files, `embedding.py` turns text into vectors, `vectorstore.py` persists and retrieves them, and `search.py` closes the loop. That modularity is the repo’s quiet strength.

It also makes the repository feel less like a demo and more like a lab bench. Each notebook can swap in a different retrieval idea without tearing apart the base pipeline.

A close-up black-ink engraving of a mechanical cabinet with many numbered drawers. One hand pulls out a drawer containing a vector index, while another hand matches the drawer number to a paper slip of metadata and text. It explains why practical vector search needs both math and human-readable context. — FAISS is only half the store. The other half is the metadata that tells you what the number means.

Why the FAISS Wrapper Is More Interesting Than It Looks

The interesting part is not that the repo uses FAISS. It is that it treats vectors and metadata as a pair. The index gives you a nearest neighbor; the metadata gives you the actual passage you can trust, display, and trace.

That hybrid pattern is the hidden plumbing in most practical vector systems. The repo makes it visible, which is exactly what a tutorial should do.

When the Model Decides Whether to Retrieve

The agentic notebook shifts the question from search quality to retrieval necessity. Instead of forcing every prompt through a database, the system first asks whether external context would help at all.

That is a small change with large consequences. It can cut latency, reduce wasted calls, and avoid pretending that every user question belongs in the vector store.

Mode	Trigger	Strength	Failure mode
Always-retrieve RAG	Every question	Simple and predictable	Wastes time on questions that need no retrieval
Agentic RAG	A retrieval decision first	Selective and cheaper	Depends on the quality of the decision step
Direct answer	No retrieval	Fast for general knowledge	Can miss domain-specific context

This is where the repo stops being a pipeline demo and starts looking like system design. The system is no longer just retrieving. It is deciding when retrieval is worth doing.

Vectorless RAG Changes the Question

The PageIndex material is the most interesting pivot in the repository. It suggests that some questions are better answered by navigating structure than by chasing semantic proximity across chunks.

That changes the mental model. Similarity search is still useful, but it is no longer the only way to find truth inside a document. If the document has a real hierarchy, the hierarchy can become the retrieval surface.

Question type	Flat vector search	Tree-based navigation
Find a related paragraph	Strong fit	Overkill
Locate a section inside a report	Can miss structure	Strong fit
Answer from a broad concept	Strong fit	Depends on document layout
Preserve author intent	Weak when chunks are isolated	Better when sections stay intact

This is the repo’s conceptual payoff. It teaches that retrieval is not always a nearest-neighbor problem. Sometimes it is a navigation problem.

Evaluation Is the Real Product

The LangSmith notebook matters because it closes the loop. If RAG is a system, then answer quality and retrieval quality are not side quests. They are the actual product.

That mindset separates educational code from serious engineering. The repository does not stop at building a path from question to answer. It asks whether the path worked.

Measure retrieval, not just output text.
Inspect failures as system failures, not prompt failures.
Treat evaluation as part of the architecture, not a postscript.