--- title: Emu Rag Assistant emoji: πŸŽ“ colorFrom: blue colorTo: gray sdk: docker pinned: false app_port: 7860 --- # πŸŽ“ EMU RAG Assistant A production-ready **Retrieval-Augmented Generation (RAG)** system designed to provide intelligent, context-aware answers about Eastern Mediterranean University (EMU) regulations, statutes, and academic policies. Built with modern Python async architecture and deployed on HuggingFace Spaces. ## πŸ“‹ Table of Contents - [Overview](#overview) - [Features](#features) - [System Architecture](#system-architecture) - [Tech Stack](#tech-stack) - [API Documentation](#api-documentation) - [Project Structure](#project-structure) - [Getting Started](#getting-started) - [Deployment](#deployment) ## 🎯 Overview The EMU RAG Assistant is an intelligent question-answering system that helps students, faculty, and staff quickly find accurate information from university regulations. By leveraging RAG technology, the system combines the power of large language models with a comprehensive knowledge base of EMU documents, ensuring responses are both accurate and grounded in official university sources. ### Key Capabilities - **Semantic Search**: Advanced vector search through university regulations using embeddings - **Context-Aware Responses**: LLM-powered answers with source citations - **Multi-language Support**: Answers in the same language as the question - **Session Management**: Persistent chat sessions with conversation history - **Dual Authentication**: Microsoft OAuth and local email/password authentication - **Rate Limiting**: Protection against abuse with separate limits for authenticated and anonymous users ## ✨ Features ### πŸ” Intelligent Retrieval - **Vector Search**: Uses Qdrant vector database for semantic similarity search - **Metadata Filtering**: Advanced filtering by document type, article numbers, and sections - **Top-K Retrieval**: Configurable number of relevant document chunks per query ### πŸ’¬ Conversational Interface - **Chat Sessions**: Persistent conversation threads with unique session IDs - **History Management**: Redis caching for fast access, PostgreSQL for persistence - **Context Preservation**: Maintains conversation context across multiple turns ### πŸ” Authentication & Authorization - **Microsoft OAuth**: Single Sign-On (SSO) integration for EMU users - **Local Authentication**: Email/password registration and login - **JWT Tokens**: Secure token-based authentication with configurable expiration - **Token Blacklisting**: Secure logout with Redis-based token invalidation ### πŸ“Š Data Management - **Document Ingestion**: Automated processing of markdown documents - **Chunking Strategy**: Intelligent document segmentation preserving article structure - **Metadata Extraction**: Automatic extraction of article numbers, titles, and sections ## πŸ—οΈ System Architecture ### High-Level Architecture ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ FastAPI App β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”Œβ”€β”€β”€β”€β”΄β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β–Όβ”€β”€β”€β” β”Œβ”€β”€β–Όβ”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β–Όβ”€β”€β”€β”€β” β”‚PostgreSQLβ”‚ β”‚ Redis β”‚ β”‚ Qdrant β”‚ β”‚ LLM β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ Vector β”‚ β”‚ (xAI) β”‚ β”‚ Users β”‚ β”‚ Cache β”‚ β”‚ Store β”‚ β”‚ β”‚ β”‚ Sessions β”‚ β”‚ Rate β”‚ β”‚Embeddingsβ”‚ β”‚ β”‚ β”‚ Messages β”‚ β”‚ Limit β”‚ β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` ### Request Flow 1. **User Query** β†’ FastAPI endpoint receives query with optional session ID 2. **Authentication** β†’ JWT token validation (optional for anonymous users) 3. **Context Retrieval** β†’ Query embedding β†’ Qdrant vector search β†’ Top-K relevant chunks 4. **LLM Generation** β†’ Context + conversation history β†’ LLM β†’ Response generation 5. **Response** β†’ Answer + source citations + session ID 6. **Storage** β†’ Messages cached in Redis, synced to PostgreSQL ### Data Flow ``` Document Ingestion: Markdown Files β†’ Chunking β†’ Embeddings β†’ Qdrant Vector Store Query Processing: User Query β†’ Embedding β†’ Vector Search β†’ Context Retrieval β†’ LLM β†’ Response Session Management: Messages β†’ Redis (Fast Cache) β†’ PostgreSQL (Persistence) ``` ## πŸ› οΈ Tech Stack ### Backend Framework - **FastAPI**: Modern, fast web framework for building APIs - **Uvicorn**: ASGI server for async Python applications - **Pydantic**: Data validation using Python type annotations ### AI/ML Stack - **LlamaIndex**: Framework for LLM applications and data ingestion - **xAI (Grok)**: Large Language Model for response generation - **FastEmbed**: Fast embedding generation for semantic search - **Qdrant**: Vector database for similarity search ### Data Storage - **PostgreSQL**: Primary database for users, sessions, and messages - **Redis**: Caching layer for chat history and rate limiting - **SQLModel**: ORM for SQL databases in Python, designed for simplicity and compatibility ### Authentication - **python-jose**: JWT token encoding/decoding - **passlib**: Password hashing (bcrypt) - **fastapi-sso**: Microsoft OAuth integration ### Infrastructure - **Alembic**: Database migration tool - **Docker**: Containerization for deployment - **HuggingFace Spaces**: Cloud deployment platform ## πŸ“‘ API Documentation ### Base URL ``` https://sarpbilgic-emu-rag.hf.space ``` ### Interactive API Docs - **Swagger UI**: `/docs` - **ReDoc**: `/redoc` ### Main Endpoints #### RAG Endpoints - `POST /api/v1/rag/ask` - Submit a query and get AI-generated response - Query parameters: `query` (required) - Headers: `X-Session-Id` (optional), `Authorization: Bearer ` (optional) - Response: Answer, sources, session ID #### Authentication Endpoints - `POST /api/v1/auth/register` - Register new user (email/password) - `POST /api/v1/auth/login` - Login with email/password - `POST /api/v1/auth/logout` - Logout and invalidate token - `GET /api/v1/auth/microsoft/login` - Initiate Microsoft OAuth flow - `GET /api/v1/auth/microsoft/callback` - OAuth callback handler #### User Endpoints - `GET /api/v1/user/me` - Get current user information (authenticated) #### Session Endpoints - `GET /api/v1/sessions` - List user's chat sessions - `GET /api/v1/sessions/{session_id}/messages` - Get messages for a session ## πŸ“ Project Structure ``` emu-rag/ β”œβ”€β”€ src/ β”‚ β”œβ”€β”€ api/ # FastAPI application β”‚ β”‚ β”œβ”€β”€ routers/ # API route handlers β”‚ β”‚ β”‚ β”œβ”€β”€ rag.py # RAG query endpoint β”‚ β”‚ β”‚ β”œβ”€β”€ auth.py # Local authentication β”‚ β”‚ β”‚ β”œβ”€β”€ auth_microsoft.py # OAuth authentication β”‚ β”‚ β”‚ β”œβ”€β”€ user.py # User management β”‚ β”‚ β”‚ └── sessions.py # Session management β”‚ β”‚ β”œβ”€β”€ services/ # Business logic β”‚ β”‚ β”‚ β”œβ”€β”€ rag_service.py # RAG orchestration β”‚ β”‚ β”‚ β”œβ”€β”€ auth_service.py # Authentication logic β”‚ β”‚ β”‚ └── chat_history_service.py # Chat management β”‚ β”‚ β”œβ”€β”€ models/ # SQLModel database models β”‚ β”‚ β”‚ β”œβ”€β”€ user.py β”‚ β”‚ β”‚ └── chat.py β”‚ β”‚ β”œβ”€β”€ schemas/ # Pydantic request/response models β”‚ β”‚ β”œβ”€β”€ selectors/ # Database query functions β”‚ β”‚ └── dependencies/ # FastAPI dependencies β”‚ β”‚ β”œβ”€β”€ auth.py # Authentication dependencies β”‚ β”‚ β”œβ”€β”€ clients.py # Service client initialization β”‚ β”‚ └── rate_limit.py # Rate limiting β”‚ β”œβ”€β”€ clients/ # External service clients β”‚ β”‚ β”œβ”€β”€ llm.py # LLM client (xAI) β”‚ β”‚ β”œβ”€β”€ embedding_client.py # Embedding generation β”‚ β”‚ β”œβ”€β”€ qdrant.py # Vector database client β”‚ β”‚ β”œβ”€β”€ redis.py # Redis client β”‚ β”‚ └── postgres.py # Database connection β”‚ β”œβ”€β”€ chunkers/ # Document processing β”‚ β”‚ └── ingestion.py # Document ingestion pipeline β”‚ β”œβ”€β”€ scrapers/ # Web scraping utilities β”‚ └── core/ # Core configuration β”‚ └── settings.py # Environment settings β”œβ”€β”€ alembic/ # Database migrations β”œβ”€β”€ emu_rag_data/ # Source documents (markdown) β”œβ”€β”€ requirements-prod.txt # Production dependencies β”œβ”€β”€ requirements-dev.txt # Development dependencies └── Dockerfile # Container configuration ``` ## πŸš€ Getting Started ### Prerequisites - Python 3.11+ - PostgreSQL 14+ - Redis 6+ - Qdrant instance (cloud or local) ### Installation 1. **Clone the repository** ```bash git clone cd emu-rag ``` 2. **Install dependencies** ```bash pip install -r requirements-dev.txt ``` 3. **Configure environment variables** Create a `.env` file: ```env ENV=development DATABASE_URL=postgresql://user:password@localhost/dbname REDIS_URL=redis://localhost:6379 QDRANT_URL=https://your-qdrant-instance QDRANT_API_KEY=your-api-key XAI_API_KEY=your-xai-api-key SECRET_KEY=your-secret-key ALGORITHM=HS256 MICROSOFT_CLIENT_ID=your-client-id MICROSOFT_CLIENT_SECRET=your-client-secret MICROSOFT_TENANT_ID=your-tenant-id API_BASE_URL=http://localhost:8000 ``` 4. **Run database migrations** ```bash alembic upgrade head ``` 5. **Ingest documents** (first time setup) ```bash python -m src.chunkers.ingestion ``` 6. **Start the development server** ```bash uvicorn src.api.main:app --reload --port 8000 ``` ### Development - **API Documentation**: http://localhost:8000/docs - **Health Check**: http://localhost:8000/health ## 🚒 Deployment ### HuggingFace Spaces This project is configured for deployment on HuggingFace Spaces using Docker. The configuration is defined in the YAML frontmatter at the top of this README. ### Environment Variables Set the following secrets in HuggingFace Spaces: - `DATABASE_URL` - `REDIS_URL` - `QDRANT_URL` - `QDRANT_API_KEY` - `XAI_API_KEY` - `SECRET_KEY` - `ALGORITHM` - `MICROSOFT_CLIENT_ID` - `MICROSOFT_CLIENT_SECRET` - `MICROSOFT_TENANT_ID` - `API_BASE_URL` ### Docker Build ```bash docker build -t emu-rag . docker run -p 7860:7860 --env-file .env emu-rag ``` ## πŸ”’ Security Features - **JWT Authentication**: Secure token-based authentication - **Password Hashing**: Bcrypt password hashing - **Rate Limiting**: Per-user and per-IP rate limits - **Token Blacklisting**: Secure logout mechanism - **Input Validation**: Pydantic schema validation - **SQL Injection Protection**: SQLModel ORM protection ## πŸ“ˆ Performance Optimizations - **Redis Caching**: Fast access to chat history - **Async Architecture**: Non-blocking I/O operations - **Connection Pooling**: Efficient database connections - **Vector Indexing**: Optimized similarity search - **Batch Processing**: Efficient document ingestion ## 🀝 Contributing For questions or contributions, please contact the maintainer.