A LangGraph-powered retrieval workflow that checks a local knowledge base first, grades the evidence, and falls back to web search when needed.
A hands-on Agentic Retrieval-Augmented Generation (RAG) implementation in a Jupyter notebook. The LangGraph workflow routes a question, searches a locally persisted FAISS knowledge base, evaluates retrieved evidence, and uses Tavily web search when the private knowledge base cannot answer confidently. Groq provides the chat model, while a local Sentence Transformers model creates embeddings.
This repository is a notebook demo, not a production service or a general-purpose document ingestion application. Its sample knowledge base is built from the LangGraph Agentic RAG documentation page.
- What it does
- Workflow
- Technology
- Repository layout
- Requirements
- Setup
- Run the notebook
- Configuration
- Knowledge base and index
- Security and limitations
- Troubleshooting
- Contributing
- License
- Connect with me
- Routes greetings and simple messages to a direct response path.
- Retrieves up to four relevant chunks from the local FAISS index for knowledge questions.
- Grades private knowledge base evidence before generating an answer.
- Searches the web with Tavily only when private evidence is weak.
- Grades web evidence, rewrites a weak query, and retries retrieval once.
- Returns an insufficient-evidence response when neither source supports an answer.
- Labels answers by source path: private knowledge base, web search, direct response, or insufficient evidence.
flowchart TD
A[Question] --> B{Route question}
B -->|Greeting / simple chat| C[Direct answer]
B -->|Knowledge question| D[Retrieve from local FAISS]
D --> E{Grade private evidence}
E -->|Good| F[Generate grounded KB answer]
E -->|Weak| G[Tavily web search]
G --> H{Grade web evidence}
H -->|Good| I[Generate grounded web answer]
H -->|Weak, first attempt| J[Rewrite query]
J --> D
H -->|Weak, retry used| K[Insufficient evidence]
| Component | Role in this project |
|---|---|
| Python and Jupyter | Implementation and interactive execution in Agentic_RAG.ipynb. |
| LangChain | Model, prompt, document loading, and retrieval integrations. |
| LangGraph | Stateful workflow nodes, routing, and retry control. |
| FAISS | Local vector index and similarity retrieval. |
| Hugging Face Sentence Transformers | Local embeddings using sentence-transformers/all-MiniLM-L6-v2. |
| Groq | Chat model through langchain-groq; notebook currently configures openai/gpt-oss-20b. |
| Tavily | Web search fallback through langchain-tavily. |
| Beautiful Soup and lxml | HTML parsing for the sample web document. |
| Pydantic | Structured router and evidence-grading outputs. |
Complete-Agentic-RAG/
|-- Agentic_RAG.ipynb # End-to-end workflow and runnable examples
|-- faiss_industry_agentic_rag_kb/
| |-- index.faiss # Persisted vector index
| |-- index.pkl # Stored document metadata and chunks
|-- assets/
| |-- agentic-rag-banner.svg # README workflow banner
|-- requirements.txt # Python dependencies
|-- LICENSE # Apache License 2.0
|-- README.md
- Python 3.10 or newer (the notebook was developed with Python 3.11).
- Git and a working internet connection for installing packages, loading the sample source page, and using Groq/Tavily.
- A Groq API key for model calls and a Tavily API key for the web-search node.
- Disk space for the local embedding model on first use. The model is downloaded by
sentence-transformersand used locally for embedding.
Clone the repository and enter its directory:
git clone https://github.com/Md-Emon-Hasan/Complete-Agentic-RAG.git
cd Complete-Agentic-RAGCreate and activate a virtual environment (recommended):
# Windows PowerShell
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
# macOS / Linux
python3 -m venv .venv
source .venv/bin/activateInstall the dependencies:
python -m pip install --upgrade pip
python -m pip install -r requirements.txtIf installation of faiss-cpu fails on your platform, check that your Python version and operating system are supported by the FAISS CPU package, then use a compatible Python environment.
Start Jupyter from the repository root:
jupyter notebook Agentic_RAG.ipynbOr, if you use JupyterLab:
jupyter lab Agentic_RAG.ipynbThen:
- Configure the API keys as described in Configuration.
- Select the Python environment where
requirements.txtwas installed as the notebook kernel. - Run the notebook cells in order. The setup cells load a sample LangGraph documentation page, split it into chunks, embed it, and save a FAISS index. The notebook also includes a cell to load the checked-in index.
- Run the example questions, then call
ask_agent("your question")in a new cell.
The notebook's sample document is fetched from https://docs.langchain.com/oss/python/langgraph/agentic-rag when rebuilding the index. Rebuilding therefore requires network access. The checked-in index can be loaded without fetching that page, though model and search calls still require the corresponding API access.
The notebook reads GROQ_API_KEY and TAVILY_API_KEY from the process environment or a .env file. If a key is missing, it prompts for the value at runtime.
Create a .env file in the repository root for local use:
GROQ_API_KEY=your_groq_api_key
TAVILY_API_KEY=your_tavily_api_keyKeep .env private. Never commit API keys or paste them into notebook cells or outputs. You can also set the variables in your shell before starting Jupyter.
The notebook uses the LangGraph Agentic RAG documentation page as its example source. It splits the page into overlapping text chunks, creates normalized embeddings with all-MiniLM-L6-v2, and stores them in faiss_industry_agentic_rag_kb/.
To rebuild the sample index, run the notebook's document loading, splitting, embedding, and index creation cells. To use the saved index, run the embedding initialization cell and then the Load Existing Index cell. The notebook uses allow_dangerous_deserialization=True because LangChain's local FAISS persistence includes a pickle file for document metadata; only load index files you trust.
To experiment with another source, update SOURCE_URL in the notebook and rebuild the index. The current loader fetches a web page; arbitrary PDFs, private files, and production-grade ingestion pipelines are outside this demo's current implementation.
- Retrieved context and questions sent to Groq or Tavily are sent to those providers. Do not use confidential material unless your data-handling requirements allow it.
- The sample notebook uses public LangGraph documentation; it is not configured with a private company corpus.
- The local
index.pklfile is deserialized when loading the saved FAISS index. Treat it as trusted executable serialization and do not load an index from an untrusted source. - Evidence grading and model-generated answers can still be wrong. Verify important claims against the cited source material.
- The notebook uses a specific Groq model identifier. If that model is unavailable for your account, update the
modelvalue in the initialization cell to one currently available to you. - This is an educational prototype. It does not include authentication, access control, a web interface, monitoring, or deployment configuration.
| Issue | What to check |
|---|---|
GROQ_API_KEY or TAVILY_API_KEY is missing |
Set it in the environment or root .env, then restart the notebook kernel. |
| Model call reports an unavailable model | Select a model available to your Groq account and update the notebook's ChatGroq configuration. |
| The sample page cannot be loaded | Check your network access and whether the source URL is reachable. You can use the saved index instead. |
| FAISS index cannot be loaded | Run the embedding initialization first, confirm both index files exist, and only load trusted index files. |
| Notebook imports fail | Activate the environment where you installed requirements.txt and select it as the notebook kernel. |
Issues and pull requests are welcome. For substantial changes, please open an issue first to discuss the proposed update. Keep API keys and private documents out of commits, and describe any setup changes in the README.
This project is distributed under the Apache License 2.0.
- Portfolio: emonlabs-ai.hitechparks.com
- GitHub: Md-Emon-Hasan
- LinkedIn: Md Emon Hasan
- Hugging Face: emonHasan01
- Email: emon.mlengineer@gmail.com
- WhatsApp: +880 1834-363533