🎓 Smart RAG Assistant

Modular Retrieval-Augmented Generation System

English | فارسی

---

🌟 Overview

This project implements a highly advanced, intelligent Question & Answer system based on the Retrieval-Augmented Generation (RAG) architecture. Originally designed to answer students' queries regarding university regulations, the system is fully modular and domain-agnostic.

💡 Bring Your Own Data: You can easily adapt this project for your own needs. Just place your PDF files in the dataset folder, set up your Gemini API key, and the system will automatically process your documents and serve them through a modern FastAPI interface!

✨ Key Features

• Modular Architecture: Clean separation of data extraction, vectorization, retrieval, and generation.
• Hybrid Text Extraction: Uses PyMuPDF for standard text and EasyOCR (with GPU support) for scanned documents/images.
• Persian Language Optimization: Integrated with Hazm for text normalization and cleaning.
• Advanced Semantic Search: Utilizes BAAI/bge-m3 for high-dimensional embeddings and FAISS for lightning-fast vector search.
• Grounded LLM Generation: Powered by Gemini-3.1-flash-lite. The system strictly answers based on the provided context and includes accurate citations (document name, page, article).
• Modern Web API: Built with FastAPI, featuring a web-based Chat UI, Chunk Explorer, and Analytics Dashboard.

🚀 How It Works

1. Data Ingestion: PDFs in the dataset/ directory are scanned and text is extracted.
2. Chunking & Metadata: Text is normalized and chunked (300-500 tokens). Metadata (Title, Page, Article, Date) is attached.
3. Vectorization: Chunks are embedded and stored in a local FAISS Vector DB (vector_store/rag_vector_db.pkl).
4. Retrieval & QA: User questions are embedded, relevant chunks are retrieved, and Gemini generates a contextualized answer via FastAPI.

🛠️ Installation & Usage

1. Prerequisites

Install the required dependencies:

pip install fastapi uvicorn pymupdf easyocr hazm sentence-transformers faiss-cpu google-genai python-dotenv jinja2

2. Setup

Clone the repository and create a .env file in the root directory:

gemini_api_key=YOUR_GEMINI_API_KEY

3. Add Your Data

Place your custom PDF files into the dataset/ directory.

4. Build the Knowledge Base

Run the data processing notebook or script to extract text, chunk it, and build the FAISS index. This will populate the vector_store/ directory.

5. Start the FastAPI Server

uvicorn main:app --host 127.0.0.1 --port 8000 --reload

Visit http://127.0.0.1:8000 to access the chat interface and analytics dashboard!

---

🎓 دستیار هوشمند RAG (پروژه پرسش و پاسخ اسناد)

🌟 معرفی پروژه

این پروژه یک سامانه پرسش و پاسخ هوشمند و پیشرفته مبتنی بر معماری RAG (Retrieval-Augmented Generation) است. اگرچه این سیستم در ابتدا برای پاسخگویی به سوالات دانشجویان بر اساس آیین‌نامه‌های آموزشی دانشگاه توسعه یافته است، اما معماری آن کاملاً ماژولار و عمومی طراحی شده است.

💡 استفاده برای داده‌های شخصی شما: هر شخصی به راحتی می‌تواند از این پروژه استفاده کند! تنها کافیست فایل‌های PDF خود را در پوشه dataset قرار دهید و کلید API جمنای (Gemini) خود را در سیستم تنظیم کنید. پلتفرم به صورت خودکار فایل‌های شما را پردازش کرده و یک دستیار هوشمند اختصاصی با رابط کاربری FastAPI در اختیار شما قرار می‌دهد!

✨ ویژگی‌های کلیدی

• معماری کاملاً ماژولار: قابلیت استفاده در پروژه‌های شخصی و سازمانی مختلف، با جداسازی لایه‌های استخراج، پردازش و بک‌اند.
• استخراج هوشمند و هیبریدی متن: استفاده ترکیبی از PyMuPDF برای متون استاندارد و EasyOCR (با پشتیبانی از GPU) برای اسناد اسکن‌شده و تصویری.
• بهینه‌سازی برای زبان فارسی: پاک‌سازی و نرمال‌سازی متون، اصلاح نیم‌فاصله‌ها و کاراکترهای عربی با استفاده از کتابخانه هضم (Hazm).
• جستجوی معنایی پیشرفته: تولید بردارهای معنایی چندزبانه قدرتمند با BAAI/bge-m3 و ذخیره‌سازی در پایگاه داده برداری FAISS.
• پاسخ‌گویی مستند و دقیق: یکپارچگی با Gemini-3.1-flash-lite جهت تولید پاسخ‌هایی که کاملاً مبتنی بر اسناد شماست (همراه با ارجاع دقیق به نام سند، شماره صفحه و ماده قانونی).
• رابط کاربری و API مدرن: دارای API قدرتمند توسعه‌یافته با FastAPI به همراه صفحات وب مجزا برای چت (Chat)، بررسی تکه‌متن‌ها (Chunks) و داشبورد آماری (Analytics).

🚀 نحوه کارکرد سیستم

۱. دریافت داده‌ها: فایل‌های PDF موجود در پوشه dataset/ به صورت خودکار خوانده شده و متون خام آن‌ها استخراج می‌شود. ۲. پردازش و تکه‌بندی (Chunking): متن‌ها نرمال شده و به بخش‌های ۳۰۰ تا ۵۰۰ توکنی (به همراه متادیتا شامل عنوان، صفحه و تاریخ) تقسیم می‌شوند. ۳. بردارسازی: متن‌ها به بردارهای ۱۰۲۴ بعدی تبدیل شده و در دیتابیس FAISS ذخیره می‌گردند. ۴. بازیابی و تولید پاسخ: پس از ثبت سوال کاربر در سرور FastAPI، مرتبط‌ترین اسناد بر اساس شباهت کسینوسی پیدا شده و جمنای بر اساس آن‌ها یک پاسخ دقیق تولید می‌کند.

🛠️ آموزش نصب و استفاده

۱. نصب نیازمندی‌ها

کتابخانه‌های مورد نیاز را با دستور زیر نصب کنید:

pip install fastapi uvicorn pymupdf easyocr hazm sentence-transformers faiss-cpu google-genai python-dotenv jinja2

۲. تنظیمات اولیه

یک فایل به نام .env در روت (مسیر اصلی) پروژه بسازید و کلید API خود را در آن قرار دهید:

gemini_api_key=YOUR_GEMINI_API_KEY

۳. افزودن داده‌های شخصی

فایل‌های PDF خود (مانند کتاب‌ها، آیین‌نامه‌ها، مقالات و ...) را در پوشه dataset/ کپی کنید.

۴. ساخت پایگاه دانش

فایل پیش‌پردازش (نوتبوک استخراج متن و ساخت دیتابیس FAISS) را اجرا کنید تا متن‌ها بررسی شده و پوشه دیتابیس برداری ایجاد شود.

۵. اجرای سرور

سرور FastAPI را با دستور زیر اجرا کنید:

uvicorn main:app --host 127.0.0.1 --port 8000 --reload

حالا مرورگر خود را باز کرده و به آدرس http://127.0.0.1:8000 مراجعه کنید تا با هوش مصنوعی اختصاصی فایل‌های خود گفتگو کنید!