Content
# 🤖 AI Research Assistant: RAG + Multi-Agent System
<div align="center">
**An intelligent document analysis system powered by Retrieval-Augmented Generation (RAG) and a Multi-Agent Architecture**
</div>
---
## 📋 Description
The **AI Research Assistant** is a sophisticated full-stack application that leverages advanced AI techniques to enable intelligent document analysis and question-answering. Users can upload documents (PDF/TXT), and the system processes them through a multi-agent pipeline to provide contextual, accurate answers using Retrieval-Augmented Generation (RAG).
This project demonstrates a real-world implementation of Agentic AI systems combining RAG, MCP, and Multi-Agent architectures.
This system demonstrates enterprise-level architecture patterns including:
- **RAG Pipeline**: Efficient document retrieval using FAISS vector database
- **Multi-Agent Architecture**: Specialized agents for planning, retrieval, and processing tasks
- **MCP-Style Tool Integration**: Modular tool-based agent design pattern
- **Production-Ready Guardrails**: Input validation and safety filtering
- **Comprehensive Observability**: Structured logging across the pipeline
---
## ✨ Features
### Core Capabilities
- 📄 **Document Upload & Processing** - Support for PDF and TXT files with automatic parsing
- 🔍 **Semantic Search** - FAISS-based vector similarity for accurate chunk retrieval
- 🧠 **RAG-Powered QA** - Context-aware answers using LLaMA 3 via Groq API
- 💬 **Conversation History** - Persistent chat sessions with context retention
### Multi-Agent System
- **Planner Agent** - Analyzes queries and orchestrates task execution
- **Retriever Agent** - Fetches most relevant document chunks via semantic search
- **Processor Agent** - Performs domain-specific tasks (summarization, key extraction, topic analysis)
### Advanced Features
- 🛡️ **Guardrails** - Empty input detection, unsafe content filtering
- 📊 **Observability** - Structured logging, query tracking, error diagnostics
- ✅ **Unit Testing** - Comprehensive pytest test suite
- ⚡ **Real-time Processing** - Asynchronous task handling
## 🔗 MCP (Model Context Protocol)
This project follows an MCP-style architecture where:
- Agents communicate through structured context
- Tools (summary, keypoints, topic) act as modular capabilities
- Planner dynamically selects tools based on user intent
This enables flexible and scalable AI workflows.
---
## 🏗️ Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React) │
│ Document Upload & Chat Interface │
└──────────────────────┬──────────────────────────────────────┘
│ HTTP/REST API
▼
┌─────────────────────────────────────────────────────────────┐
│ FastAPI Backend │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ API Layer (FastAPI Routes) │ │
│ │ • Chat endpoints │ │
│ │ • Document upload & management │ │
│ │ • User sessions & history │ │
│ └──────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────────────┐ │
│ │ Multi-Agent Orchestration Layer │ │
│ │ │ │
│ │ ┌────────────────┐ ┌─────────────────┐ │ │
│ │ │ Planner Agent │──▶ Processor Agent │ │ │
│ │ └────────────────┘ └─────────────────┘ │ │
│ │ │ ▲ │ │
│ │ └────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────────────────────────┐ │ │
│ │ │ Retriever Agent │ │ │
│ │ │ (Semantic Search + Chunk Retrieval) │ │ │
│ │ └────────────────────────────────────────┘ │ │
│ └──────────────────────┬──────────────────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────────────┐ │
│ │ RAG & Data Processing Pipeline │ │
│ │ │ │
│ │ • Text Chunking (Sentence Transformers) │ │
│ │ • Embedding Generation │ │
│ │ • FAISS Vector Database (Similarity Search) │ │
│ │ • Context Assembly & Prompt Engineering │ │
│ └──────────────────────┬──────────────────────────────┘ │
│ │ │
│ ┌──────────────────────┴──────────────────────────────┐ │
│ │ LLM Integration (Groq API - LLaMA 3) │ │
│ │ Response Generation │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Infrastructure & Storage │ │
│ │ • MongoDB (Chat history, metadata) │ │
│ │ • FAISS Index (Vector storage) │ │
│ │ • File System (Document storage) │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Data Flow
```
User Query
▼
Guardrails (Input Validation)
▼
Planner Agent (Task Analysis)
▼
Retriever Agent (FAISS Search) ◀──┐
▼ │
Context Assembly ──────────────────┘
▼
LLM Processing (Groq API)
▼
Processor Agent (Post-Processing)
▼
Response to User + History Storage
```
---
## 🛠️ Tech Stack
### Backend
| Component | Technology | Purpose |
|-----------|-----------|---------|
| **Framework** | FastAPI | High-performance REST API |
| **LLM** | LLaMA 3 (via Groq API) | Response generation |
| **Vector DB** | FAISS | Semantic similarity search |
| **Embeddings** | Sentence Transformers | Text embedding generation |
| **Database** | MongoDB | Persistent storage (history, metadata) |
| **Task Queue** | Python asyncio | Asynchronous processing |
| **Testing** | pytest | Unit & integration tests |
| **Logging** | Python logging | Structured observability |
### Frontend
| Component | Technology | Purpose |
|-----------|-----------|---------|
| **Framework** | React 18 | Interactive UI |
| **Styling** | CSS/Tailwind (optional) | UI/UX design |
| **HTTP Client** | Fetch API/axios | Backend communication |
### DevOps & Infrastructure
- **Package Management**: pip/poetry (Python), npm (Node.js)
- **Environment Management**: Python venv
- **Data Pipeline**: Custom chunking & embedding services
---
## 📁 Project Structure
```
ai-research-assistant/
├── README.md # Project documentation
├── pytest.ini # Pytest configuration
├── requirements.txt # Python dependencies
│
├── app/ # Main application package
│ ├── __init__.py
│ ├── config.py # Configuration management
│ ├── main.py # FastAPI app initialization
│ │
│ ├── agents/ # Multi-agent system
│ │ ├── __init__.py
│ │ ├── agent.py # Base agent class
│ │ ├── multi_agent.py # Multi-agent orchestration
│ │ └── tools.py # MCP-style agent tools (summary, keypoints, topic)
│ │
│ ├── api/ # REST API endpoints
│ │ ├── __init__.py
│ │ ├── chat.py # Chat endpoint
│ │ ├── history.py # History management
│ │ ├── upload.py # Document upload
│ │ └── user.py # User management
│ │
│ ├── database/ # Database layer
│ │ ├── __init__.py
│ │ ├── models.py # Pydantic/MongoDB models
│ │ └── mongodb.py # MongoDB connection & queries
│ │
│ ├── services/ # Core business logic
│ │ ├── __init__.py
│ │ ├── chunking.py # Text chunking service
│ │ ├── embedding.py # Embedding generation (Sentence Transformers)
│ │ ├── retrieval.py # FAISS-based retrieval
│ │ ├── guardrails.py # Input validation & safety
│ │ ├── observability.py # Logging & monitoring
│ │ └── ... # Other services
│ │
│ └── utils/ # Utility functions
│
├── rag-frontend/ # React frontend
│ ├── package.json
│ ├── public/
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── pages/ # Pages
│ │ └── App.js
│ └── README.md
│
├── data/ # Data storage
│ ├── uploads/ # User-uploaded files
│ ├── vector_store/ # FAISS indices
│ ├── string/ # String embeddings cache
│ └── test/ # Test data
│
├── mongodb_data/ # MongoDB local storage
│
└── tests/ # Test suite
├── __init__.py
├── test_chat.py
└── ... # Additional tests
```
---
## 🚀 Installation & Setup
### Prerequisites
- Python 3.10+
- Node.js 16+
- MongoDB (local or cloud)
- Groq API Key
### Backend Setup
#### 1. Clone Repository & Create Virtual Environment
```bash
cd ai-research-assistant
python -m venv venv
# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate
```
#### 2. Install Python Dependencies
```bash
pip install -r requirements.txt
```
#### 3. Configure Environment Variables
Create a `.env` file in the project root:
```env
GROQ_API_KEY=your_groq_api_key
MONGODB_URI=mongodb://localhost:27017/ai_research_assistant
FAISS_INDEX_PATH=data/vector_store/
CHUNK_SIZE=512
CHUNK_OVERLAP=50
MODEL_NAME=llama-3.1-8b-instant
```
#### 4. Start MongoDB (if using local instance)
```bash
# Ensure MongoDB is running
mongod
```
#### 5. Initialize FAISS Index & Embeddings
```bash
python app/services/embedding.py --initialize
```
#### 6. Run FastAPI Backend
```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
### Frontend Setup
#### 1. Navigate to Frontend Directory
```bash
cd rag-frontend
```
#### 2. Install Dependencies
```bash
npm install
```
#### 3. Configure API Endpoint
Update `.env` or `src/config.js`:
```javascript
REACT_APP_API_URL=http://localhost:8000/api
```
#### 4. Start Development Server
```bash
npm start
```
The application will be available at `http://localhost:3000`
---
## 💡 How It Works
### Step-by-Step Query Processing Flow
```
1. USER UPLOADS DOCUMENT
│
├─ PDF/TXT parsing
├─ Text extraction
└─ Metadata storage in MongoDB
2. TEXT PREPROCESSING
│
├─ Chunking (512 tokens, 50 overlap)
├─ Sentence Transformer embeddings
└─ FAISS index storage
3. USER ASKS QUESTION
│
├─ Input validation (guardrails)
├─ Safety check (content filtering)
└─ Emit to multi-agent system
4. PLANNER AGENT
│
└─ Analyzes query intent
└─ Routes to Retriever Agent
5. RETRIEVER AGENT
│
├─ Embeds user query
├─ FAISS similarity search (top-k chunks)
└─ Returns context
6. PROCESSOR AGENT
│
├─ Assembles prompt with context
├─ Applies summarization/extraction if needed
└─ Prepares for LLM
7. LLM INFERENCE
│
├─ Groq API call (LLaMA 3)
├─ RAG-augmented generation
└─ Response streaming
8. RESPONSE & HISTORY
│
├─ Return answer to user
├─ Store conversation in MongoDB
└─ Log observability metrics
```
---
## 📊 Example Queries and Outputs
### Example 1: Document Summarization
**Document**: Research paper on "Machine Learning in Healthcare"
**User Query**: `Summarize the key findings from this paper`
**Agent Flow**:
- Planner → Detects summarization task
- Retriever → Fetches all relevant sections
- Processor → Applies summary tool
- LLM → Generates concise summary
**Output**:
```
The paper identifies 5 key breakthroughs in ML for healthcare:
1. Improved diagnostic accuracy (95.3% vs 87% baseline)
2. Reduced computational requirements
3. Enhanced interpretability for clinical use
...
```
### Example 2: Topic Extraction
**User Query**: `What are the main topics covered in these documents?`
**Output**:
```
Topics identified across your documents:
- Machine Learning Algorithms (23%)
- Clinical Applications (18%)
- Data Privacy & Ethics (15%)
- Performance Benchmarks (12%)
- Future Directions (32%)
```
### Example 3: Complex Reasoning
**User Query**: `Based on the documents, what would be the impact if privacy regulations changed?`
**Agent Flow**:
- Planner → Complex reasoning task
- Retriever → Multi-chunk retrieval
- Processor → Context assembly
- LLM → Generates analysis
---
## 🛡️ Guardrails & Safety
### Input Validation
```python
✓ Empty input detection
✓ Maximum input length enforcement
✓ Special character filtering
✓ SQL injection prevention
✓ XSS attack prevention
```
### Content Safety
- Unsafe content detection using heuristic filters
- Query intent validation
- Response appropriateness checking
### Implementation
See `app/services/guardrails.py` for implementation details.
---
## 📊 Observability & Logging
### Structured Logging
The system implements comprehensive logging across all pipeline stages:
```python
# Query logging
logger.info("Query received", extra={
"user_id": user_id,
"query_length": len(query),
"timestamp": datetime.utcnow()
})
# Retrieval logging
logger.info("FAISS retrieval completed", extra={
"chunks_retrieved": k,
"similarity_scores": scores,
"retrieval_time_ms": elapsed_time
})
# LLM logging
logger.info("LLM inference completed", extra={
"model": "llama-3.1-8b-instant",
"tokens_generated": output_tokens,
"latency_ms": inference_time
})
```
### Metrics Tracked
- Query volume & distribution
- Retrieval latency & accuracy
- LLM response quality
- Error rates & types
- User engagement patterns
See `app/services/observability.py` for full implementation.
---
## 🎯 Key Concepts Implemented
- ✔ Retrieval-Augmented Generation (RAG)
- ✔ Multi-Agent System
- ✔ MCP (Model Context Protocol)
- ✔ Agentic AI Framework
- ✔ Guardrails (input validation & safety)
- ✔ Observability (logging & monitoring)
- ✔ Unit Testing (pytest)
## 🎥 Demo Flow
### 1️⃣ Home Page
- User lands on homepage
- Navigation: Login, Signup, Dashboard
### 2️⃣ Login & Signup
- New users register
- Existing users login
- User ID stored for personalization
### 3️⃣ Document Upload
- Upload PDF/TXT
- Text extraction → chunking → embeddings → FAISS storage
### 4️⃣ Ask Question
- User enters query
- Examples:
- "Summarize the document"
- "Give key points"
- "What is the topic?"
### 5️⃣ Answer Generation (RAG + Agents + MCP)
User Query
↓
Planner Agent
↓
Retriever Agent (RAG)
↓
Processor Agent
↓
LLM (Groq - LLaMA 3)
- Context-aware response generated
### 6️⃣ Chat History
- Stored in database
- User can view past chats
## ✅ Testing
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=app tests/
# Run specific test file
pytest tests/test_chat.py -v
```
### Test Coverage
- Unit tests for agents, services, and utilities
- Integration tests for RAG pipeline
- API endpoint tests
- Database operation tests
### Configuration
See `pytest.ini` for pytest configuration.
---
## 🚀 Live Capabilities
- Real-time document Q&A
- Intelligent summarization
- Context-aware reasoning
- Multi-agent decision making
## 🚀 Future Improvements
- [ ] **Multi-Language Support** - Support for documents in multiple languages
- [ ] **Advanced Caching** - LLM response caching for common queries
- [ ] **Fine-Tuning Pipeline** - Custom model fine-tuning on domain data
- [ ] **Real-Time Collaboration** - WebSocket support for collaborative document analysis
- [ ] **Mobile App** - Native mobile application
---
## 👤 Author
**Hafzafarzana**
AI & Data Science Student
For questions or contributions, please open an issue or submit a pull request.
---
## 📄 License
This project is licensed under the **MIT License** - see the LICENSE file for details.
---
<div align="center">
**Built with ❤️ using FastAPI, React, and advanced AI techniques**
[⭐ Star this repository if you find it useful!](https://github.com)
</div>
---
## 📸 Screenshots / Implementation
### Home Page
<p align="center">
<img src="implementation_img/home_page.png" width="800"/>
</p>
### Login Page
<p align="center">
<img src="implementation_img/login_page.png" width="800"/>
</p>
### Signup Page
<p align="center">
<img src="implementation_img/signup_page.png" width="800"/>
</p>
### Dashboard Page
<p align="center">
<img src="implementation_img/dashboard_page.png" width="800"/>
</p>
### Chat Interface
<p align="center">
<img src="implementation_img/chat_page.png" width="800"/>
</p>
### History Page
<p align="center">
<img src="implementation_img/history_page.png" width="800"/>
</p>
### System Architecture
<p align="center">
<img src="implementation_img/architecture_diagram.png" width="800"/>
</p>
### Implementation View
<p align="center">
<img src="implementation_img/implementation.png" width="800"/>
</p>
