🦜🔗 Advanced Adaptive RAG

A self-correcting, self-reflective RAG agent — built on the 🦜🔗 LangChain & 🦜🕸️ LangGraph ecosystem.

Route → Retrieve → Grade → Generate → Self-Reflect

---

Note

Powered end-to-end by the 🦜 LangChain stack: LangChain for composable LCEL chains, LangGraph for the stateful agent graph, and LangSmith for full-trace observability.

---

✨ Overview

This project implements an Adaptive RAG pipeline that goes far beyond naive "retrieve-then-answer" systems. It combines three powerful research ideas into a single, robust LangGraph state machine:

Technique	What it does
🧭 Adaptive RAG	Routes each question to the right source — the local vector store or live web search.
🛡️ Corrective RAG (CRAG)	Grades every retrieved document for relevance and falls back to web search when knowledge is missing.
🪞 Self-RAG	Reflects on its own answer to detect hallucinations and verify the question is actually addressed — retrying when it isn't.

The result is an agent that knows what it knows, fetches what it doesn't, and never confidently makes things up.

---

🗺️ How It Works

The agent is modeled as a graph of decision nodes. Each question flows through routing, grading, generation, and self-reflection loops until a grounded and useful answer is produced.

_{The conceptual flow: route → retrieve → grade → (web search) → generate → self-reflect.}

📈 Compiled LangGraph diagram (auto-generated from the code)

The flow, step by step

1. 🧭 Route Question — An LLM router classifies the question. Topics about agents, prompt engineering, or adversarial attacks go to the vector store; everything else goes to web search.
2. 📚 Retrieve — Pulls the most semantically relevant chunks from the ChromaDB vector store.
3. 🔍 Grade Documents — Each retrieved document is scored yes/no for relevance. Irrelevant docs are dropped, and a web_search flag is raised if anything is missing.
4. 🌐 Web Search (conditional) — If knowledge gaps are detected, Tavily fetches fresh results from the web and appends them to the context.
5. ✍️ Generate — Gemini produces an answer grounded in the collected context.
6. 🪞 Self-Reflection — The answer is double-checked:
   • Hallucination grader → Is the answer grounded in the documents? If no, regenerate.
   • Answer grader → Does the answer actually resolve the question? If no, fall back to web search.
   • If both pass → ✅ return the answer.

---

🛠️ Tech Stack

Built on the 🦜 LangChain ecosystem, with best-in-class models and infrastructure around it.

	Component	Role
🦜🕸️	LangGraph	Orchestration — the stateful, cyclic agent graph
🦜🔗	LangChain	Composable LCEL chains (routing, grading, generation)
🦜🛠️	LangSmith	Full-trace observability & debugging
✨	Google Gemini 2.5 Flash	LLM, via langchain-google-genai
🔢	gemini-embedding-001	Document & query embeddings
🗄️	ChromaDB	Locally-persisted vector store
🌐	Tavily	Real-time web search fallback
⚡	uv · pytest · black · isort	Tooling, testing & formatting

---

📂 Project Structure

langgraph-course/
├── main.py                         # 🚀 Entry point — invokes the compiled graph
├── ingestion.py                    # 📥 Loads & chunks docs, builds the Chroma retriever
├── graph/
│   ├── graph.py                    # 🧩 The LangGraph state machine (nodes + edges)
│   ├── state.py                    # 📦 GraphState (TypedDict) shared across nodes
│   ├── consts.py                   # 🔖 Node name constants
│   ├── nodes/                      # ⚙️  Graph nodes
│   │   ├── retrieve.py             #     └ fetch documents from the vector store
│   │   ├── grade_documents.py      #     └ score document relevance (CRAG)
│   │   ├── generate.py             #     └ produce the grounded answer
│   │   └── web_search.py           #     └ Tavily fallback search
│   └── chains/                     # 🔗 Reusable LCEL chains
│       ├── router.py               #     └ route question → vectorstore | websearch
│       ├── generation.py           #     └ RAG answer-generation chain
│       ├── retrieval_grader.py     #     └ "is this doc relevant?"
│       ├── hallucination_grader.py #     └ "is the answer grounded?"
│       ├── answer_grader.py        #     └ "does the answer resolve the question?"
│       └── tests/
│           └── test_chains.py      # ✅ Unit tests for every chain
└── pyproject.toml                  # 📜 Dependencies & project metadata

---

🚀 Getting Started

1. Prerequisites

• Python 3.11+
• uv (recommended) — pip install uv
• API keys for Google Gemini and Tavily (and optionally LangSmith)

2. Clone & Install

git clone https://github.com/Mohamedkhattab02/Agentic-RAG-with-LangGraph
cd langgraph-course

# Install dependencies into a virtual environment with uv
uv sync

Prefer pip? Run pip install -e . inside a virtual environment instead.

3. Configure Environment Variables

Create a .env file in the project root:

# --- Required ---
GOOGLE_API_KEY=your_google_gemini_api_key
TAVILY_API_KEY=your_tavily_api_key

# --- Optional: LangSmith tracing & observability ---
LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_PROJECT=advanced-rag

# --- Make local imports resolve ---
PYTHONPATH=.

🔑 Get your keys: Google AI Studio · Tavily · LangSmith

4. Ingest the Knowledge Base

The vector store is built from a set of Lilian Weng's essays on agents, prompt engineering, and adversarial attacks.

Open ingestion.py and uncomment the Chroma.from_documents(...) block, then run it once to populate ./.chroma:

uv run python ingestion.py

After the first run, re-comment that block so subsequent runs simply load the persisted store.

5. Run the Agent

uv run python main.py

You'll see the agent reason through the graph live in your terminal:

---ROUTE QUESTION---
---ROUTE QUESTION TO RAG---
---RETRIEVE---
---CHECK DOCUMENT RELEVANCE TO QUESTION---
---GRADE: DOCUMENT RELEVANT---
---ASSESS GRADED DOCUMENTS---
---DECISION: GENERATE---
---GENERATE---
---CHECK HALLUCINATIONS---
---DECISION: GENERATION IS GROUNDED IN DOCUMENTS---
---GRADE GENERATION vs QUESTION---
---DECISION: GENERATION ADDRESSES QUESTION---

---

💻 Usage Example

Customize the question in main.py:

from dotenv import load_dotenv
from graph.graph import app

load_dotenv()

if __name__ == "__main__":
    result = app.invoke(input={"question": "What is agent memory?"})
    print(result["generation"])

---

✅ Testing

Every chain is covered by unit tests — routing, relevance grading, generation, and hallucination detection:

uv run pytest -s -v

⚠️ Tests make live LLM calls, so a valid GOOGLE_API_KEY and a populated vector store are required.

---

🧩 Key Design Patterns

• Binary grading with structured output — Each grader uses Pydantic models + with_structured_output() for reliable, parseable decisions.
• Conditional edges — The graph branches dynamically based on grader verdicts, enabling true self-correction loops.
• Separation of concerns — Pure chains (logic) are decoupled from nodes (state I/O), keeping the graph readable and testable.

---

📜 License

Released under the MIT License — free to use, modify, and learn from.

---

_{Built with 🦜🔗 LangChain · 🦜🕸️ LangGraph · ✨ Google Gemini}

⭐ If this project helped you, consider giving it a star!