Skip to main content
Glama
rupali-chauksey

IntelliDocs AI

README.md
# IntelliDocs AI โ€” Enterprise RAG + MCP Assistant

<div align="center">

[![Python 3.9+](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)
[![Stars](https://img.shields.io/github/stars/rupali-chauksey/intellidocs-ai-enterprise-rag-mcp?style=social)](https://github.com/rupali-chauksey/intellidocs-ai-enterprise-rag-mcp)

**One assistant, multiple knowledge sources, intelligent routing.**

[๐ŸŽฅ Demo Video](#-demo-video) โ€ข [๐Ÿ“– Features](#-key-features) โ€ข [โšก Quick Start](#-quick-start) โ€ข [๐Ÿ› ๏ธ Setup](#-installation-setup) โ€ข [๐Ÿ”ฎ Roadmap](#-future-improvements)

</div>

---

## ๐ŸŽฏ Overview

IntelliDocs AI is a **production-ready enterprise AI assistant** that combines:

- **Retrieval-Augmented Generation (RAG)** โ€” Answer questions from uploaded enterprise documents
- **Model Context Protocol (MCP)** โ€” Access structured company databases with intelligent tool selection
- **Web Search** โ€” Fetch current external information
- **LangGraph Workflow** โ€” Orchestrate complex multi-source queries with conversation memory

Perfect for organizations needing a **unified AI interface** that connects documents, databases, and real-time information.

---

## ๐ŸŽฅ Demo Video

https://github.com/user-attachments/assets/74e28186-4539-4337-a1e2-9add03b54a40

---

## ๐Ÿ“ธ Live Demo Screenshot


<img width="1912" height="1017" alt="IntelliDocs AI Demo" src="https://github.com/user-attachments/assets/72da7124-efb1-49c5-8038-b838e7b21962" />

<img width="1908" height="824" alt="ChatGPT Image Sep 8, 2026, 11_58_46 AM" src="https://github.com/user-attachments/assets/f4766053-1e90-4e1b-9fde-57ecd670225a" />


---

## โšก Quick Start (5 Minutes)

### Prerequisites
- **Python 3.9+**
- **GROQ API Key** 
- **Git** (for cloning)

### Installation & Running

```bash
# 1๏ธโƒฃ Clone the repository
git clone https://github.com/rupali-chauksey/intellidocs-ai-enterprise-rag-mcp.git
cd intellidocs-ai-enterprise-rag-mcp

# 2๏ธโƒฃ Create virtual environment
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

# 3๏ธโƒฃ Install dependencies
pip install -r requirements.txt

# 4๏ธโƒฃ Setup environment variables
cp .env.example .env
# Edit .env and add your GROQ_API_KEY

# 5๏ธโƒฃ Initialize database
python setup_db.py

# 6๏ธโƒฃ Run the application
python -m uvicorn app.main:app --reload --port 8002

# 7๏ธโƒฃ Open browser
# Navigate to http://localhost:8002
```

**Done! ๐ŸŽ‰** Your IntelliDocs AI instance is now running.

---

## ๐Ÿ”ง Installation & Setup

### System Requirements

| Requirement | Version |
|------------|---------|
| Python | 3.9 or higher |
| pip | Latest |
| Node.js (optional) | 16+ (for frontend dev) |
| Git | 2.0+ |
| RAM | Minimum 2GB, Recommended 4GB+ |
| Disk Space | ~500MB for dependencies |

### Detailed Setup Steps

#### Step 1: Clone Repository
```bash
git clone https://github.com/rupali-chauksey/intellidocs-ai-enterprise-rag-mcp.git
cd intellidocs-ai-enterprise-rag-mcp
```

#### Step 2: Virtual Environment Setup
```bash
# Create virtual environment
python -m venv venv

# Activate it
# On Windows:
venv\Scripts\activate

# On macOS/Linux:
source venv/bin/activate

# You should see (venv) in your terminal
```

#### Step 3: Install Dependencies
```bash
pip install --upgrade pip
pip install -r requirements.txt
```

#### Step 4: Environment Configuration
```bash
# Copy template
cp .env.example .env

# Edit .env file and add your keys:
# GROQ_API_KEY=your_api_key_here
# CHROMA_DB_PATH=./chroma_db
# DATABASE_PATH=./company.db
```

**โš ๏ธ Important:** Never commit `.env` file to Git!

#### Step 5: Database Setup
```bash
# Create and populate SQLite database
python setup_db.py

# Verify database
sqlite3 company.db ".tables"
```

#### Step 6: Run the Application
```bash
# Development mode (with auto-reload)
python -m uvicorn app.main:app --reload --port 8002

# Production mode
python -m uvicorn app.main:app --port 8002 --workers 4
```

#### Step 7: Access the Application
```
๐Ÿ“ฑ Open your browser: http://localhost:8002
```

---

## โœจ Key Features

### ๐Ÿ“š 1. Retrieval-Augmented Generation (RAG)

Answer questions from uploaded enterprise documents with source awareness.

**Supported Formats:** 
- ๐Ÿ“„ PDF
- ๐Ÿ“ TXT
- ๐Ÿ“– Markdown
- ๐Ÿ“‹ DOCX

**RAG Pipeline:**
```
Document Upload 
    โ†“
Text Extraction & Preprocessing
    โ†“
Smart Chunking (Overlap Detection)
    โ†“
Embedding Generation (Sentence Transformers)
    โ†“
ChromaDB Vector Storage
    โ†“
User Query Processing
    โ†“
Semantic Similarity Search
    โ†“
Relevance Threshold Filtering
    โ†“
LLM Answer Generation
    โ†“
Source-Aware Response
```

**RAG Capabilities:**
- โœ… Document upload & automatic indexing
- โœ… Incremental ChromaDB indexing
- โœ… Document re-upload with replacement
- โœ… Duplicate vector prevention
- โœ… Document status & chunk count tracking
- โœ… Safe document deletion with vector cleanup
- โœ… Configurable relevance threshold filtering
- โœ… Source-aware answer generation
- โœ… Web fallback when context is unavailable

### ๐Ÿ”Œ 2. Model Context Protocol (MCP)

A real MCP server exposes company database functionality as intelligent tools. The system dynamically discovers available tools and selects the best one for each query.

**Available MCP Tools:**
| Tool | Purpose |
|------|---------|
| `get_department_stats` | Department statistics & metrics |
| `query_employees` | Employee records & information |
| `get_top_products` | Product revenue rankings |
| `get_sales_performance` | Sales team performance data |
| `get_company_overview` | Company-wide metrics |
| `run_custom_query` | Safe SELECT queries |

**Smart Tool Selection:**
- ๐ŸŽฏ Analyzes query intent
- ๐Ÿ” Validates argument types
- ๐Ÿ›ก๏ธ Prevents SQL injection
- ๐Ÿ“Š Returns structured data

### ๐Ÿ—„๏ธ 3. Company Database

A production-ready SQLite database covering:

**Employees Module:**
- Employee ID, name, email, department
- Salary, hire date, job title
- Performance metrics

**Products Module:**
- Product ID, name, category
- Price, revenue, stock
- Performance metrics

**Sales Module:**
- Salesperson details
- Revenue data, commissions
- Transaction records

**Recreate Database Anytime:**
```bash
python setup_db.py
```

### ๐Ÿง  4. Intelligent Query Routing

The system identifies query type and routes to the optimal source using deterministic patterns.

| Query Type | Route | Example |
|---|---|---|
| Document Question | RAG | "What is the AI course content?" |
| Database Query | MCP | "Who is the highest paid employee?" |
| Current Information | Web | "What is latest tech news?" |
| Hybrid Query | RAG + MCP | "What is our policy AND who leads sales?" |

**Routing Decision Tree:**
```
                    User Query
                        โ†“
                Pattern Matcher
                        โ†“
        โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
        โ–ผ               โ–ผ            โ–ผ
      RAG Only    Database Only    Web Only
        โ”œ               โ”œ             โ”‚
        โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                        โ–ผ
            Check for Hybrid Patterns
                        โ†“
            Route to Appropriate Handler
```

### ๐Ÿ”— 5. Hybrid RAG + MCP Processing

Answer complex questions requiring multiple sources simultaneously.

**Example Query:** 
> "What is our sales incentive policy, and who are our top 3 salespeople?"

**Processing Flow:**
```
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚   User Query (Hybrid Pattern)   โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
             โ†“
    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
    โ†“                 โ†“
 RAG Retrieval   MCP Database
   (Policy)      (Sales Data)
    โ”‚                 โ”‚
    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
             โ†“
    Response Synthesis
    (LLM Combination)
             โ†“
    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
    โ”‚  Final Answer     โ”‚
    โ”‚ (Policy + Data)   โ”‚
    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

**Benefits:**
- Combines unstructured knowledge with structured data
- Single coherent response
- Reduces user query count
- More complete answers

### ๐ŸŒ 6. Web Search Fallback

Fetch current external information when needed.

**Used For:**
- Current events & news
- Real-time data (weather, exchange rates)
- External reference information
- Fallback when RAG has no relevant context

**Example Queries:**
- "Who is the current PM of India?"
- "What is latest AI news?"
- "Current USD to INR rate?"

### ๐Ÿ’ฌ 7. Conversation Memory

Maintain context across multiple turns for natural conversation flow.

**Example Conversation:**
```
User:  "Who are the top 3 salespeople?"
AI:    "Returns: Alice ($500K), Bob ($450K), Carol ($400K)"

User:  "What are their salaries?"
AI:    [Uses previous context, identifies 'their' = top 3 salespeople]
       "Returns their individual salaries from database"

User:  "What department are they in?"
AI:    [Maintains full conversation context]
       "Returns department info from database"
```

**Memory Features:**
- โœ… Context window management
- โœ… Follow-up question resolution
- โœ… Pronoun disambiguation
- โœ… Multi-turn understanding

### ๐Ÿ“„ 8. Document Management

Complete document lifecycle with status tracking.

**Operations:**
- โœ… **Upload** โ€” Add new documents to knowledge base
- โœ… **Index** โ€” Automatic chunking & embedding
- โœ… **Search** โ€” Semantic similarity search
- โœ… **Re-upload** โ€” Replace old document versions
- โœ… **Delete** โ€” Remove with vector cleanup
- โœ… **Status Check** โ€” View indexing status & chunk count

**Document Status Values:**
| Status | Meaning |
|--------|---------|
| `pending` | Upload received, waiting to index |
| `indexing` | Currently being processed |
| `indexed` | Ready for queries |
| `error` | Failed indexing, check logs |

### ๐ŸŽฏ 9. Relevance Filtering

Never blindly trust retrieval results. Configurable threshold prevents weak context.

**Relevance Checking:**
```
Query Input
    โ†“
Vector Similarity Search
    โ†“
Retrieved Chunks Scored
    โ†“
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ Relevance Threshold?  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
    โ–ผ                โ–ผ
  PASS            FAIL
    โ”‚                โ”‚
Use RAG        Fallback to
Context        Web Search
```

**Configuration in `.env`:**
```
RELEVANCE_THRESHOLD=0.7
```

### ๐Ÿงฉ 10. LangGraph Workflow Orchestration

Sophisticated state machine for complex multi-source queries.

**Workflow Diagram:**
```
                      START
                        โ”‚
                  Classify Query
       โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
       โ–ผ                 โ–ผ                 โ–ผ
      RAG            Database              Web
       โ”‚                 โ”‚                 โ”‚
  Retrieve           MCP Agent         Web Search
       โ”‚                 โ”‚                 โ”‚
Relevance Grade    Database Tool          โ”‚
       โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                    โ–ผ
            Response Synthesis
            (Combine Results)
                    โ–ผ
              Final Answer
                    โ”‚
                    โ–ผ
            Stream to User
```

**Hybrid Query Processing:**
```
Input: RAG + Database Question
  โ”‚
  โ”œโ”€โ†’ [Parallel] RAG Retrieval
  โ”‚   โ”‚โ†’ Vector Search
  โ”‚   โ””โ†’ Relevance Filter
  โ”‚
  โ”œโ”€โ†’ [Parallel] MCP Database
  โ”‚   โ”‚โ†’ Tool Selection
  โ”‚   โ””โ†’ Database Query
  โ”‚
  โ””โ”€โ†’ [Merge] Response Synthesis
      โ”‚โ†’ Combine contexts
      โ””โ†’ LLM generates unified answer
```

---

## ๐Ÿ—๏ธ System Architecture

```
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚          User Interface (Browser)       โ”‚
โ”‚        (HTML/CSS/JavaScript)            โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                   โ”‚ HTTP/WebSocket
         โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
         โ”‚  FastAPI Backend   โ”‚
         โ”‚  (Uvicorn Server)  โ”‚
         โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                   โ”‚
         โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
         โ”‚   LangGraph Router (Agent)   โ”‚
         โ”‚   โ€ข Query Classification     โ”‚
         โ”‚   โ€ข Tool Selection           โ”‚
         โ”‚   โ€ข Response Synthesis       โ”‚
         โ””โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
           โ”‚                    โ”‚
    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”      โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”
    โ”‚   RAG      โ”‚      โ”‚  MCP/DB     โ”‚
    โ”‚  Pipeline  โ”‚      โ”‚  Agent      โ”‚
    โ”‚            โ”‚      โ”‚             โ”‚
    โ”‚ ChromaDB โ—„โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ–บโ”‚ MCP Server  โ”‚
    โ”‚ (Vectors)  โ”‚      โ”‚ SQLite DB   โ”‚
    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜      โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
           โ”‚                    โ”‚
           โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                    โ”‚
            โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
            โ”‚  Web Search     โ”‚
            โ”‚  (Fallback)     โ”‚
            โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                    โ”‚
            โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
            โ”‚ Response Synthesis   โ”‚
            โ”‚ (LLM Combination)    โ”‚
            โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                    โ”‚
            โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
            โ”‚  Final Response      โ”‚
            โ”‚  (with Sources)      โ”‚
            โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

---

## ๐Ÿงฑ Technology Stack

| Component | Technology | Purpose |
|---|---|---|
| **Language** | Python 3.9+ | Core application |
| **Backend Framework** | FastAPI | REST APIs & WebSocket |
| **Workflow Orchestration** | LangGraph | Multi-source routing |
| **Vector Database** | ChromaDB | Semantic search |
| **Structured Data** | SQLite | Company database |
| **LLM** | Groq (LLaMA) | Fast inference |
| **Embeddings** | Sentence Transformers | Local embeddings |
| **Protocol** | MCP | Database tool integration |
| **Frontend** | HTML/CSS/JavaScript | User interface |
| **Server** | Uvicorn | ASGI application server |
| **Containerization** | Docker & Docker Compose | Production deployment |

---

## ๐Ÿ“ Project Structure

```
IntelliDocs_AI_Enterprise_RAG_MCP/
โ”‚
โ”œโ”€โ”€ ๐Ÿ“‚ app/
โ”‚   โ”œโ”€โ”€ __init__.py
โ”‚   โ”œโ”€โ”€ config.py              # Configuration & settings
โ”‚   โ”œโ”€โ”€ db_tools.py            # Database tool definitions
โ”‚   โ”œโ”€โ”€ graph.py               # LangGraph workflow
โ”‚   โ”œโ”€โ”€ ingestion.py           # Document ingestion pipeline
โ”‚   โ”œโ”€โ”€ main.py                # FastAPI application
โ”‚   โ”œโ”€โ”€ mcp_agent.py           # MCP agent logic
โ”‚   โ”œโ”€โ”€ mcp_server.py          # MCP server implementation
โ”‚   โ”œโ”€โ”€ tools.py               # Tool definitions
โ”‚   โ”‚
โ”‚   โ”œโ”€โ”€ ๐Ÿ“‚ routes/
โ”‚   โ”‚   โ”œโ”€โ”€ documents.py       # Document management endpoints
โ”‚   โ”‚   โ””โ”€โ”€ upload.py          # Upload handling endpoints
โ”‚   โ”‚
โ”‚   โ”œโ”€โ”€ ๐Ÿ“‚ services/
โ”‚   โ”‚   โ”œโ”€โ”€ chunker.py         # Text chunking logic
โ”‚   โ”‚   โ”œโ”€โ”€ document_loader.py # Format-specific loaders
โ”‚   โ”‚   โ”œโ”€โ”€ embedding.py       # Embedding generation
โ”‚   โ”‚   โ”œโ”€โ”€ uploader.py        # File upload service
โ”‚   โ”‚   โ””โ”€โ”€ vector_store.py    # ChromaDB operations
โ”‚   โ”‚
โ”‚   โ”œโ”€โ”€ ๐Ÿ“‚ static/
โ”‚   โ”‚   โ”œโ”€โ”€ index.html         # Main UI
โ”‚   โ”‚   โ””โ”€โ”€ ๐Ÿ“‚ assets/
โ”‚   โ”‚       โ”œโ”€โ”€ style.css      # Styling
โ”‚   โ”‚       โ””โ”€โ”€ script.js      # Frontend logic
โ”‚   โ”‚
โ”‚   โ””โ”€โ”€ ๐Ÿ“‚ uploads/            # Uploaded documents
โ”‚
โ”œโ”€โ”€ ๐Ÿ“‚ data/
โ”‚   โ””โ”€โ”€ company_policy.txt     # Sample company docs
โ”‚
โ”œโ”€โ”€ ๐Ÿ“‚ tests/
โ”‚   โ””โ”€โ”€ test_basic.py          # Unit tests
โ”‚
โ”œโ”€โ”€ ๐Ÿ“‚ Assets/
โ”‚   โ”œโ”€โ”€ test_1.png
โ”‚   โ””โ”€โ”€ test_2.png
โ”‚
โ”œโ”€โ”€ ๐Ÿ“‚ docs/
โ”‚   โ”œโ”€โ”€ API.md                 # API documentation
โ”‚   โ”œโ”€โ”€ ARCHITECTURE.md        # Detailed architecture
โ”‚   โ””โ”€โ”€ TROUBLESHOOTING.md     # Common issues
โ”‚
โ”œโ”€โ”€ setup_db.py                # Database initialization
โ”œโ”€โ”€ requirements.txt           # Python dependencies
โ”œโ”€โ”€ .env.example               # Environment template
โ”œโ”€โ”€ .gitignore                 # Git ignore rules
โ”œโ”€โ”€ Dockerfile                 # Docker image
โ”œโ”€โ”€ docker-compose.yml         # Docker Compose config
โ”œโ”€โ”€ README.md                  # This file
โ””โ”€โ”€ LICENSE                    # MIT License
```

---

## ๐Ÿ› ๏ธ Configuration

### Environment Variables

Create `.env` file from `.env.example`:

```bash
cp .env.example .env
```

**Required Variables:**
```env
# LLM Configuration
GROQ_API_KEY=your_groq_api_key_here
MODEL_NAME=mixtral-8x7b-32768

# Database Configuration
DATABASE_PATH=./company.db
CHROMA_DB_PATH=./chroma_db

# Server Configuration
API_PORT=8000
API_HOST=0.0.0.0

# RAG Configuration
CHUNK_SIZE=500
CHUNK_OVERLAP=50
RELEVANCE_THRESHOLD=0.7

# MCP Configuration
MCP_ENABLED=true
MCP_PORT=5678
```

**โš ๏ธ Security:** Never commit `.env` to version control!

---

## ๐Ÿ“Š Usage Examples

### Example 1: RAG Query
```
User: "What is the pricing of the AI course?"

System Flow:
1. Classify as RAG query
2. Search documents
3. Find relevant sections
4. Generate answer with sources

Response: "The AI course costs $299..."
```

### Example 2: Database Query
```
User: "Who is the top salesperson this quarter?"

System Flow:
1. Classify as Database query
2. Select MCP tool: get_sales_performance
3. Execute database query
4. Synthesize response

Response: "Alice Johnson leads with $500K revenue..."
```

### Example 3: Hybrid Query
```
User: "What is our sales incentive policy and who qualifies?"

System Flow:
1. Classify as Hybrid (RAG + Database)
2. [Parallel] RAG retrieval โ†’ Policy documents
3. [Parallel] MCP query โ†’ Top performers
4. Synthesize both contexts
5. Generate unified answer

Response: "Our policy offers 5-15% bonus... Top qualifiers: Alice ($500K), Bob ($450K)..."
```

### Example 4: Web Fallback
```
User: "What is the current USD to INR exchange rate?"

System Flow:
1. Not found in documents or database
2. Trigger web search
3. Fetch current rate
4. Return real-time data

Response: "1 USD = 83.45 INR (as of today)"
```

---

## ๐Ÿ” Security Best Practices

### Never Commit to Git

```gitignore
.env                    # API keys & secrets
venv/                   # Virtual environment
chroma_db/              # Vector database
company.db              # Company data
__pycache__/            # Python cache
.pytest_cache/          # Test cache
.vscode/                # IDE settings
*.pyc                   # Compiled Python
.DS_Store               # macOS files
```

### Secrets Management

โœ… **Do:**
- Store API keys in `.env` locally
- Use environment variables in production
- Rotate keys regularly
- Use separate keys for dev/prod

โŒ **Don't:**
- Commit `.env` to Git
- Hardcode API keys
- Share API keys in chat/email
- Use same key for multiple environments

### If Secret is Accidentally Committed

```bash
# 1. Revoke the compromised key immediately
# 2. Create a new key
# 3. Remove from Git history
git rm --cached .env
git commit --amend --no-edit
git push
```

---

## ๐Ÿš€ Deployment

### Docker Deployment (Recommended)

```bash
# Build and run with Docker Compose
docker compose up --build

# Run in background
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down
```

### Manual Deployment

```bash
# Production setup
python -m uvicorn app.main:app --host 0.0.0.0 --port 8002 --workers 4

# With logging
python -m uvicorn app.main:app --host 0.0.0.0 --port 8002 --workers 4 --log-level info
```

### Cloud Deployment (Coming Soon)
- AWS EC2/ECS
- Google Cloud Run
- Azure Container Instances
- Heroku

---

## ๐Ÿงช Testing

### Run Unit Tests

```bash
# Install test dependencies
pip install pytest pytest-asyncio

# Run all tests
pytest

# Run specific test
pytest tests/test_basic.py

# With coverage
pytest --cov=app tests/
```

### Manual Testing Checklist

- [ ] Document upload
- [ ] Document search
- [ ] Database queries
- [ ] Web search fallback
- [ ] Hybrid queries
- [ ] Conversation memory
- [ ] Error handling

---

## ๐Ÿ› Troubleshooting

### Issue: Module Import Error

**Error:** `ModuleNotFoundError: No module named 'app'`

**Solution:**
```bash
source venv/bin/activate  # Activate virtual environment
pip install -r requirements.txt  # Reinstall dependencies
python -m uvicorn app.main:app --reload --port 8002  # Run with correct import path
```

---

### Issue: GROQ API Key Error

**Error:** `GROQ_API_KEY not found or invalid`

**Solution:**
```bash
# Check .env file exists
cat .env

# Update .env with correct key
GROQ_API_KEY=sk_xxxxxxxxxxxxxxxxxxxx

# Restart application
```

---

### Issue: Document Not Searchable

**Error:** Document uploaded but not returning in searches

**Solution:**
```bash
# Check document status
curl http://localhost:8000/api/documents/status

# If status is "error", check logs:
# Look for chunking or embedding errors

# Re-upload document
# Or recreate ChromaDB:
rm -rf chroma_db/
# Restart application
```

---

### Issue: Port Already in Use

**Error:** `Address already in use: ('127.0.0.1', 8002)`

**Solution:**
```bash
# Option 1: Use different port
python -m uvicorn app.main:app --port 8003

# Option 2: Kill process using port (Linux/macOS)
lsof -ti:8002 | xargs kill -9

# Option 3: Find and kill process (Windows)
netstat -ano | findstr :8002
taskkill /PID <PID> /F
```

---

### Issue: Upload Files Interfering with Auto-Reload

**Error:** File size mismatch or incomplete uploads during `--reload`

**Solution:**
```bash
# Don't use --reload when testing uploads
python -m uvicorn app.main:app --port 8002

# Or use production mode:
python -m uvicorn app.main:app --port 8002 --workers 4
```

---

## ๐Ÿฉบ Diagnostics & Monitoring

### Health Check Endpoint

```bash
curl http://localhost:8002/api/health
```

**Response:**
```json
{
  "status": "healthy",
  "components": {
    "api": "โœ“ Running",
    "database": "โœ“ Connected",
    "vector_store": "โœ“ Initialized",
    "mcp_server": "โœ“ Running"
  }
}
```

### Document Diagnostics

```bash
# Get all documents status
curl http://localhost:8002/api/documents/status

# Get specific document details
curl http://localhost:8002/api/documents/<doc_id>
```

### Logs

```bash
# View application logs
tail -f app.log

# Check for errors
grep "ERROR" app.log

# Monitor MCP server
grep "MCP" app.log
```

---

## ๐Ÿ› ๏ธ Development Guide

### Setting Up Development Environment

```bash
# Install dev dependencies
pip install -r requirements-dev.txt

# Run with debug mode
export PYTHONUNBUFFERED=1
python -m uvicorn app.main:app --reload --port 8002 --log-level debug

# Format code
black app/

# Lint
flake8 app/

# Type check
mypy app/
```

### API Documentation

Auto-generated documentation available at:
- Swagger UI: `http://localhost:8002/docs`
- ReDoc: `http://localhost:8002/redoc`

---

## ๐Ÿงฉ MCP Tools Reference

### Tool: `get_department_stats`

**Description:** Get department statistics and metrics

**Query Examples:**
- "Give me statistics for the Engineering department"
- "How many employees in Sales?"
- "Department performance metrics"

---

### Tool: `query_employees`

**Description:** Search and filter employees

**Query Examples:**
- "List all employees in Marketing"
- "Who earns above $100K?"
- "Show me employees hired in 2023"

---

### Tool: `get_top_products`

**Description:** Ranking products by revenue

**Query Examples:**
- "What are our top 5 products by revenue?"
- "Which product has highest revenue?"

---

### Tool: `get_sales_performance`

**Description:** Sales team performance data

**Query Examples:**
- "Who is the top salesperson?"
- "Sales rankings this quarter"
- "Revenue by salesperson"

---

### Tool: `get_company_overview`

**Description:** Company-wide metrics

**Query Examples:**
- "Company overview"
- "Total revenue and employees"
- "Company statistics"

---

### Tool: `run_custom_query`

**Description:** Safe SELECT queries (restricted)

**Allowed Operations:**
- โœ… SELECT statements
- โœ… WHERE clauses
- โœ… JOIN operations
- โŒ INSERT, UPDATE, DELETE
- โŒ DROP, ALTER

---

## ๐ŸŽฏ Performance Optimization

### Query Optimization

```
Time Complexity:
- Vector Search: O(n) โ†’ ~100ms for 1M vectors
- Database Query: O(log n) โ†’ ~10ms with indexes
- LLM Inference: ~2-3 seconds
- Total Response: ~3-4 seconds
```

### Caching Strategy

- Recently retrieved documents cached in memory
- Embedding results cached in ChromaDB
- MCP tool results cached for 5 minutes

### Scaling Recommendations

- **Small deployments:** Single FastAPI instance
- **Medium deployments:** Load balancer + 2-3 instances
- **Large deployments:** Kubernetes + autoscaling + CDN

---

## ๐Ÿ”ฎ Future Improvements

**๐Ÿ” Security & Access**
- ๐Ÿ”’ User authentication & authorization
- ๐Ÿ‘ฅ Multi-user workspaces with role-based access
- ๐Ÿ”‘ Enterprise SSO (SAML, OAuth2)
- ๐Ÿข Organization-level management
- ๐Ÿ—‚๏ธ Document-level & field-level access control

**๐Ÿ›ก๏ธ Safety & Reliability**
- ๐Ÿงญ Hallucination detection & response confidence scoring
- ๐Ÿšฆ Fallback mechanism when RAG/MCP/Web search all fail
- โฑ๏ธ Rate limiting & API throttling
- โšก Caching layer for repeated queries

**๐Ÿ“œ Data Governance**
- ๐Ÿ“ Audit logs for queries & responses
- ๐Ÿ” PII / sensitive data masking in responses
- ๐Ÿ—‘๏ธ Data retention & deletion policies (GDPR-style compliance)

**โš™๏ธ Infrastructure**
- โ˜๏ธ Cloud deployment templates
- ๐Ÿ—„๏ธ PostgreSQL & MongoDB support
- ๐Ÿ“ฆ Vector DB options (Pinecone, Weaviate, Milvus)
- ๐ŸŒ Distributed deployment architecture

**๐Ÿ“ˆ Performance & Product**
- โšก Streaming responses with Server-Sent Events
- ๐Ÿ“Š Advanced analytics & observability
- ๐Ÿ” Enhanced citation & source tracking
- ๐Ÿ“‰ Production monitoring & alerting
- ๐ŸŽจ Advanced UI customization
- ๐Ÿงช Comprehensive test coverage
- ๐Ÿค– Multi-agent collaboration
- ๐Ÿ’ฌ User feedback loop (thumbs up/down on answers)

*Contributions welcome for any of the above.*

---

## ๐ŸŽ“ What This Project Demonstrates

This is a **production-grade implementation** of modern AI systems covering:

| Area | Technologies |
|------|--------------|
| **LLM Applications** | Groq, Claude integration |
| **RAG Systems** | ChromaDB, Sentence Transformers |
| **Vector Databases** | Semantic search, embeddings |
| **Agentic Workflows** | Tool calling, agent patterns |
| **Orchestration** | LangGraph state machine |
| **Protocols** | Model Context Protocol (MCP) |
| **Database Integration** | SQLite, custom SQL tools |
| **Web Integration** | Web search APIs |
| **Backend Development** | FastAPI, REST APIs |
| **Document Processing** | PDF/DOCX/TXT parsing |
| **DevOps** | Docker, Docker Compose |
| **Testing** | pytest, integration tests |

---

## ๐Ÿ“„ Final Note

IntelliDocs AI brings together the best of modern AI technologies to create a practical, production-ready system for enterprise knowledge management.

```
              INTELLIDOCS AI

       โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
       โ”‚          โ”‚          โ”‚          โ”‚
     RAG         MCP        WEB      MEMORY
       โ”‚          โ”‚          โ”‚          โ”‚
       โ–ผ          โ–ผ          โ–ผ          โ–ผ
   Documents   Database   Internet   Context
       โ”‚          โ”‚          โ”‚          โ”‚
       โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                    โ”‚
                    โ–ผ
             LangGraph Router
                    โ”‚
                    โ–ผ
             Intelligent Answer
```

**Enterprise Knowledge + Business Data + Web Intelligence = IntelliDocs AI**

Maintenance

ActivityMaintained
ResponsivenessUnresponsive