🔬 AI Research Assistant

Multi-Agent AI System · LangGraph · RAG · MCP · FastAPI · Streamlit

Bootcamp Capstone Project — Built with LangChain, LangGraph, FAISS, MCP Servers, and Live APIs

---

📌 What Is This?

The AI Research Assistant is a production-grade multi-agent AI system that answers complex research questions by intelligently combining information from multiple sources simultaneously:

• 📄 Your own documents (PDFs, TXT, Markdown) via a FAISS vector database
• 📰 Live news articles via NewsAPI
• 📚 Academic books via Open Library API
• 🗂️ Local research notes via Filesystem MCP Server
• 🗄️ Session history via SQLite MCP Server

Three specialized AI agents collaborate inside a LangGraph state machine to plan, retrieve, and synthesize a comprehensive answer — all served through a beautiful Streamlit UI backed by a FastAPI REST API.

---

🎯 Problem & Users

Problem	Researchers and students waste hours manually searching across papers, news, and books to answer a single question
End Users	Students, researchers, analysts, and knowledge workers who need fast, multi-source answers
Solution	An agentic AI that autonomously searches all sources in parallel and synthesizes a cited, structured response

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Streamlit UI  (port 8501)                     │
│   Chat · History · Summary · Document Upload                     │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTP REST
┌──────────────────────────▼──────────────────────────────────────┐
│                   FastAPI Backend  (port 8000)                   │
│   /query · /history · /summary · /add-document · /health        │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                   LangGraph Orchestrator                         │
│                                                                  │
│  check_query → [clarify?]                                        │
│       ↓                                                          │
│  ┌──────────┐    ┌──────────────┐    ┌─────────────────┐        │
│  │ Planner  │───▶│  Retriever   │───▶│  Synthesizer    │        │
│  │  Agent   │    │    Agent     │    │     Agent       │        │
│  └──────────┘    └──────────────┘    └─────────────────┘        │
│  Breaks query    RAG + APIs +        Writes cited answer         │
│  into plan       MCP reads           + saves to MCP             │
│                 + CRAG grading      + RAGAS scoring              │
│                 (web fallback)      (3 metrics)                  │
└──────────────────────────────────────────────────────────────────┘
          │                  │                    │
   ┌──────┴──────┐   ┌───────┴───────┐   ┌───────┴───────┐
   │  FAISS      │   │  NewsAPI      │   │  Open Library │
   │  Vector DB  │   │  (live news)  │   │  API (books)  │
   └─────────────┘   └───────────────┘   └───────────────┘
          │                                      │
   ┌──────┴──────┐                       ┌───────┴───────┐
   │ Filesystem  │                       │  SQLite MCP   │
   │ MCP Server  │                       │  (sessions)   │
   └─────────────┘                       └───────────────┘

---

🤖 The Three Agents

Agent 1 — Planner Agent (agents/planner_agent.py)

Receives the raw user query and uses GPT-4o-mini to produce a structured JSON research plan. Decides which sources to activate, generates focused search terms, and breaks the query into sub-questions.

Agent 2 — Retriever Agent (agents/retriever_agent.py)

Executes the plan in full. Searches the FAISS vector store for relevant document chunks, fetches live news articles, searches academic books, and reads local research notes — all in one pass. Every RAG chunk is graded for relevance by the CRAG Grader before being handed off; see 🩺 Corrective RAG (CRAG) below.

Agent 3 — Synthesizer Agent (agents/synthesizer_agent.py)

Takes every piece of retrieved context and writes a comprehensive, cited, well-structured final answer. Also persists the session to SQLite and appends a note to the filesystem via MCP. The finished answer is then scored by the RAGAS Evaluator; see 📊 RAGAS Quality Evaluation below.

---

🔀 LangGraph Workflow

START
  │
  ▼
check_query ──(too vague?)──▶ clarify ──▶ END
  │
  ▼
planner ──(error?)──▶ error ──▶ END
  │
  ▼
retriever ──(error?)──▶ error ──▶ END
  │
  ▼
synthesizer ──(error?)──▶ error ──▶ END
  │
  ▼
END

Every node reads from and writes to a shared ResearchState TypedDict. Conditional edges route based on error flags and query validation results.

---

🛠️ MCP Servers

Server	File	What It Does
Filesystem MCP	mcp_tools/filesystem_mcp.py	Read/write local research notes in data/local/
SQLite MCP	mcp_tools/sqlite_mcp.py	Store every research session, log sources used, enable history search

---

🌐 External APIs

API	File	Purpose	Key Required?
NewsAPI	api_tools/news_api.py	Fetch recent news articles on any topic	✅ Free at newsapi.org
Open Library	api_tools/open_library_api.py	Search academic books by subject	❌ No key needed
Tavily Search	api_tools/tavily_api.py	CRAG web-search fallback when local RAG chunks are irrelevant	✅ Free at tavily.com

---

🩺 Corrective RAG (CRAG)

Plain RAG trusts whatever the vector store returns. CRAG (retrieval/crag_grader.py) adds a relevance-grading step between the FAISS search and the Synthesizer, so bad or off-topic chunks never make it into the final answer.

How it works — after search_vector_store() returns the top-K chunks, the CRAGGrader sends each chunk to an LLM individually with a yes/no relevance prompt, then classifies the batch into one of three quality levels:

Quality	Meaning	What happens
✅ Correct	Every chunk is relevant	All chunks are passed to the Synthesizer as-is
⚠️ Ambiguous	Some chunks relevant, some not	Irrelevant chunks are filtered out; only the relevant ones are kept
❌ Incorrect	No chunks are relevant (or none were retrieved)	Local RAG is abandoned entirely — the Retriever Agent calls Tavily for a live web search instead, and the Synthesizer is told to cite [Web] sources

The grading result is stored as context["retrieval_quality"] and surfaced end-to-end: the FastAPI /query response includes a retrieval_quality field, and the Streamlit UI renders it as a color-coded badge (✅/⚠️/❌) right next to the source tags on every answer.

FAISS search ──▶ CRAG Grader ──▶ correct/ambiguous ──▶ Synthesizer (uses filtered chunks)
                     │
                     └──▶ incorrect ──▶ Tavily web search ──▶ Synthesizer (uses [Web] results)

---

📊 RAGAS Quality Evaluation

After the Synthesizer writes an answer, the RAGAS Evaluator (evaluation/ragas_evaluator.py) automatically scores it against the retrieved context — turning "does this look right?" into a measurable number. Scores are computed once per query and never block the response: if RAGAS itself fails (bad key, library error, etc.) the query still returns normally with an empty ragas_scores dict.

Metric	What it measures
Faithfulness	Whether every claim in the answer is actually supported by the retrieved context — the core hallucination check
Answer Relevancy	Whether the answer actually addresses the question asked, rather than drifting off-topic
Context Precision	Whether the retrieved chunks that mattered were ranked/used well, i.e. how much of the retrieved context was actually useful

Each score is a float between 0.0 and 1.0, rounded to 2 decimals. They're returned in the /query response's ragas_scores field and rendered in the Streamlit UI as color-coded progress bars (🟢 ≥0.7, 🟠 ≥0.4, 🔴 below) inside a "📊 View Quality Scores" expander under each answer.

---

💾 Data Sources

Source	Type	Location
Local .txt / .md / .pdf documents	Local	data/docs/
SQLite research session database	Local	data/local/knowledge.db
NewsAPI live articles	Remote	REST API
Open Library book catalog	Remote	REST API

---

🧠 Memory System

Memory Type	Class	Purpose
Buffer Memory	ChatMessageHistory	Stores exact recent conversation turns
Summary Memory	GPT-4o-mini summarization	Compresses long histories into a running summary

Both are managed by memory/memory_manager.py and injected into every agent prompt.

---

📁 Project Structure

research-assistant/
│
├── main.py                    ← CLI entry point
│
├── api/
│   └── server.py              ← FastAPI REST backend
│
├── ui/
│   └── app.py                 ← Streamlit frontend
│
├── agents/
│   ├── planner_agent.py       ← Agent 1: Query planning
│   ├── retriever_agent.py     ← Agent 2: Multi-source retrieval
│   └── synthesizer_agent.py   ← Agent 3: Answer synthesis
│
├── graph/
│   ├── state.py               ← LangGraph ResearchState TypedDict
│   └── workflow.py            ← State graph with nodes & edges
│
├── memory/
│   └── memory_manager.py      ← Buffer + Summary memory
│
├── retrieval/
│   ├── document_loader.py     ← Loads .txt / .md / .pdf files
│   ├── chunker.py             ← RecursiveCharacterTextSplitter
│   ├── vector_store.py        ← FAISS build / load / search
│   └── crag_grader.py         ← CRAG: grades chunk relevance
│
├── evaluation/
│   └── ragas_evaluator.py     ← RAGAS: scores answer quality
│
├── mcp_tools/
│   ├── filesystem_mcp.py      ← MCP #1: Local file operations
│   └── sqlite_mcp.py          ← MCP #2: Session database
│
├── api_tools/
│   ├── news_api.py            ← NewsAPI client
│   ├── open_library_api.py    ← Open Library client
│   └── tavily_api.py          ← Tavily client (CRAG web fallback)
│
├── config/
│   └── settings.py            ← Env loading & typed constants
│
├── data/
│   ├── docs/                  ← Your documents for RAG
│   ├── local/                 ← Auto-generated notes & SQLite DB
│   └── vector_store/          ← FAISS index (auto-generated)
│
├── utils/
│   └── helpers.py             ← Rich terminal formatting
│
├── requirements.txt
├── .env.example
└── .gitignore

---

✅ Bootcamp Requirements Checklist

Requirement	Implementation	File
ChatOpenAI	GPT-4o-mini for all agents	agents/*.py
PromptTemplate	LCEL prompt chains	agents/*.py
LLM Chain	prompt | llm | parser	agents/*.py
Buffer Memory	ChatMessageHistory	memory/memory_manager.py
Summary Memory	GPT summarization loop	memory/memory_manager.py
Embeddings	OpenAIEmbeddings	retrieval/vector_store.py
Chunking	RecursiveCharacterTextSplitter	retrieval/chunker.py
Vector DB	FAISS	retrieval/vector_store.py
Agent 1	Planner Agent	agents/planner_agent.py
Agent 2	Retriever Agent	agents/retriever_agent.py
Agent 3	Synthesizer Agent	agents/synthesizer_agent.py
LangGraph	StateGraph + conditional edges	graph/workflow.py
MCP Server #1	Filesystem MCP	mcp_tools/filesystem_mcp.py
MCP Server #2	SQLite MCP	mcp_tools/sqlite_mcp.py
External API #1	NewsAPI	api_tools/news_api.py
External API #2	Open Library	api_tools/open_library_api.py
External API #3	Tavily Search (CRAG fallback)	api_tools/tavily_api.py
Local Data Source	TXT docs + SQLite	data/
Remote Data Source	NewsAPI + Open Library + Tavily	api_tools/
FastAPI	REST backend	api/server.py
Streamlit UI	Full chat interface	ui/app.py
Corrective RAG (CRAG)	Relevance grading + web fallback	retrieval/crag_grader.py
RAGAS Evaluation	Faithfulness / relevancy / precision scoring	evaluation/ragas_evaluator.py

---

🚀 Quick Start

# 1. Clone
git clone https://github.com/YOUR_USERNAME/ai-research-assistant.git
cd ai-research-assistant

# 2. Virtual environment
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 3. Install
pip install -r requirements.txt

# 4. Configure
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# 5a. Run CLI only
python main.py

# 5b. Run full UI (two terminals)
uvicorn api.server:app --reload --port 8000   # Terminal 1
streamlit run ui/app.py                        # Terminal 2
# Open http://localhost:8501

---

🖥️ UI Features

Tab	Feature
💬 Chat	Bubble chat UI, source tags per answer, Planner Agent plan viewer
📜 History	All past sessions from SQLite, searchable, re-ask button
📋 Summary	Live AI summary + recent turns side by side
📁 Upload	Drag & drop docs into the knowledge base, auto-rebuilds FAISS
💡 Sidebar	Quick example queries, session stats, API status indicator

---

📄 License

MIT License — free to use, modify, and distribute.