Agentic RAG for Dummies
Build a modular, memory-aware, human-in-the-loop Agentic RAG with LangGraph in minutes.
- Source repo
- GiovanniPasq/agentic-rag-for-dummies
- Stars
- ★ 4.3k
- Last updated
- 1d ago
- License
- MIT
- Primary language
- Jupyter Notebook
- FA score
- 51/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer wanting to quickly grasp Agentic RAG concepts through a step-by-step Jupyter notebook.
- Not a fit if
- Teams wanting a zero-config, ready-to-run RAG app
- Users on weak hardware that cannot run 8B+ local models
- Production teams needing documented Docker deployment
- Source review
- 51/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
This repository demonstrates how to build a fully-featured Agentic RAG (Retrieval-Augmented Generation) system using LangGraph. It includes hierarchical indexing (parent-child chunking), conversation memory, query rewriting and clarification, multi-agent parallel retrieval, context compression, and self-correction. The system uses hybrid search with Qdrant and supports multiple LLM providers, defaulting to local Ollama but with examples for OpenAI, Anthropic, and Google. The project offers both an interactive Jupyter notebook for learning and a modular Python project with a Gradio chat interface. It also includes RAGAS-based evaluation and Langfuse observability.
The repository provides a complete Agentic RAG pipeline. It processes user queries, summarizes conversation history, rewrites ambiguous queries, and asks for clarification when needed. Complex queries are decomposed into sub-questions that are executed in parallel by multiple agent subgraphs. Each agent uses 'search_child_chunks' and 'retrieve_parent_chunks' tools to retrieve relevant documents, compresses context to stay within token limits, and retries if results are insufficient. Finally, all answers are aggregated into a coherent response. The entire workflow is orchestrated via LangGraph state graphs and exposed through a Gradio UI.
- A developer wanting to quickly grasp Agentic RAG concepts through a step-by-step Jupyter notebook.
- A team building a production RAG system that needs a modular, customizable architecture.
- An organization with many PDF documents needing accurate answers with context preservation and hybrid search.
- A cost-conscious user preferring local LLMs (Ollama) but wanting flexibility to switch to cloud providers.
- A researcher evaluating retrieval quality using RAGAS metrics built into the repository.
How do you install or deploy this agent?
- Clone the repo: git clone https://github.com/GiovanniPasq/agentic-rag-for-dummies
- Install dependencies: pip install -r requirements.txt (or uv pip install -r requirements.txt)
- Optionally install Ollama and pull a model: ollama pull granite4.1:8b
- Place PDF files in the 'docs/' directory (sample PDFs are linked).
How do you use this agent?
Option 1 (Quickstart): Open notebooks/agentic_rag.ipynb in Google Colab or Jupyter, run all cells, and add PDFs to docs/.
Option 2 (Full Project): Run python project/app.py to launch the Gradio interface, then open the local URL (e.g., http://127.0.0.1:7860) in your browser.
Note: The default LLM is Ollama; for cloud providers, replace the LLM initialization code with the provided examples.
What are this agent's strengths and limitations?
- Offers two pathways: a learning notebook and a modular production-ready project.
- Highly modular: LLM provider, embeddings, chunking, and workflow are independently configurable.
- Advanced features: multi-agent parallelism, query clarification, context compression, and self-correction.
- Hybrid retrieval (dense+sparse) with local-first Ollama support for privacy and cost savings.
- Requires Python 3.11+ and several dependencies (Qdrant, LangGraph), which may be overkill for simple use.
- Default local model performance depends on hardware; docs recommend 8B+ models for reliable tool calling.
- No fully documented Docker deployment in this README; must refer to project README for details.
- Evaluation and observability require additional setup and may add complexity.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Agentic RAG for Dummies This agent | 51 · Major gaps | Library / SDKFree + model costs | ★ 4.3k | 1d ago | Jupyter Notebook | — |
| RAGLight | 63 · Some gaps | CLIFree + model costs | ★ 673 | 2d ago | Python | OpenAI API |
| Generative AI with LangChain | 52 · Major gaps | Library / SDKFree + model costs | ★ 1.4k | 2mo ago | Jupyter Notebook | OpenAI API · Claude API |
| Dynamiq Agent Orchestration | 61 · Some gaps | Library / SDKFree + model costs | ★ 1.1k | 2d ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README describes human-in-the-loop query clarification, but no concrete user confirmation mechanism; data flow transparency is limited, only mentioning Langfuse observability; sensitive data handling is not specified; dependencies are pinned but no security audit; external effects include local file writes and vector DB operations, but permissions are not clarified; no rollback mechanism; source attribution only via metadata 'source' field, lacking full provenance. Deductions: lack of least privilege principle, user confirmation only as feature description, insufficient data flow transparency, sensitive data handling not addressed, dependency security not audited, external effects permissions unclear, no rollback, incomplete source attribution.
Evidence shows: internal logic is consistent, e.g., parent/child chunk size validation; dependencies are pinned but availability not verified; error handling provides partial return messages (e.g., RETRIEVAL_ERROR). Deductions: dependency availability not verified, failure messages coverage incomplete.
Evidence shows: README clearly targets learners and developers, offering two usage paths; capability boundaries are described via feature table; trigger precision is reflected in query rewriting and clarification mechanisms; environment fit supports multiple LLM providers and local/cloud deployment. Deductions: capability boundaries not detailed enough, environment fit not covering all possible scenarios.
Evidence shows: README structure is clear, including installation and usage; naming is stable, e.g., CHILD_COLLECTION; examples and troubleshooting provided; MIT license explicit; but version history and changelog missing, maintenance responsibility not stated. Deductions: no versioning info, maintenance responsibility not stated.
Evidence shows: output usability demonstrated via examples and demo; marginal value in modular architecture and multiple features; cost-benefit via local Ollama option lowers barrier. Deductions: no performance benchmarks or cost analysis.
Evidence shows: README claims partially supported by code, but no independent verification; cross-source corroboration limited, relying on single repo; facts and inferences not clearly separated. Deductions: lack of independent verification and fact/inference separation.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Dependencies are pinned but no security audit; consider vulnerability scanning before use.
- Sensitive data handling is not specified; additional assessment needed if processing personal data.
- No rollback mechanism; indexing operations may overwrite existing data; recommend backups.
- External effects (file writes, vector DB operations) permissions are not clarified; restrict in deployment environment.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
New Features: 1. Quickstart Scripts & Modern uv Setup • Added start.sh (Linux/macOS) and start.bat (Windows) for one-click environment setup and launch. • Added pyproject.toml support enabling direct execution with uv run project/app.py. • Automatic fallback to standard Python venv with built-in checks for .env setup and local Ollama availability. Bug Fixes: 1. Dotted PDF Filename Preservation • Fixed an issue where filenames containing multiple dots (e.g., guide.v1.pdf and guide.v2.pdf) mapped to the same output name due to pathlib.Path.stem suffix handling. …View on GitHub ↗ -
Release notes excerpt
New Features: 1. Compact Chat Memory • Added rolling conversation summary with the last two user/assistant exchanges. • Older raw messages are removed to prevent context growth. • Conversation memory is configurable through MAIN_HISTORY_MESSAGES_TO_KEEP. 2. Execution Logging • Added optional terminal logs for graph steps, routing decisions, tool calls, and outputs. • Added colored and truncated state previews for easier debugging. • Logging can be enabled from the project configuration. 3. Updated Model Defaults • Switched the default main LLM to granite4.1:8b. …View on GitHub ↗ -
Release notes excerpt
New Features: 1. RAGAS Evaluation • Added dedicated evaluation.ipynb notebook to evaluate retrieval and answer quality with RAGAS metrics. • Evaluation outputs can be saved and reused without rerunning the RAG pipeline. • Added support for a separate local judge model through Ollama's OpenAI-compatible API. 2. Updated Retrieval Defaults • Switched the default embedding model to Qwen/Qwen3-Embedding-0.6B. • Updated retrieval defaults to threshold 0.4 and k=7. Bug Fixes: 1. Project Cleanup • Cleaned dependencies, generated files, and notebook outputs. …View on GitHub ↗