Hybrid RAG Assistant

A production-grade Retrieval-Augmented Generation (RAG) assistant for students and engineers studying technical textbooks, syllabi, and research papers.

Features

• Hybrid Search: Combines Dense Vector Embeddings (pgvector) with Sparse Full-Text Search (tsvector) via Reciprocal Rank Fusion (RRF)
• PDF Citation Highlighting: Click any citation to jump directly to the referenced page in the embedded PDF viewer
• Streaming Responses: Real-time LLM output with Server-Sent Events (SSE)
• Math Support: LaTeX rendering via KaTeX for technical documents
• Multi-Provider: Supports OpenAI and Anthropic LLMs

Tech Stack

• Frontend: Next.js 14, TypeScript, Tailwind CSS, shadcn/ui, react-pdf
• Backend: FastAPI, SQLAlchemy Async, Pydantic v2, PyMuPDF
• Database: PostgreSQL 16 + pgvector extension
• AI: OpenAI/Anthropic LLMs, text-embedding-3-small

Quick Start

Prerequisites

• Docker & Docker Compose
• OpenAI API key

1. Clone and Configure

git clone <repo-url>
cd rag-assistant

Create a .env file in the project root:

OPENAI_API_KEY=sk-your-openai-key

2. Run with Docker Compose

docker-compose up --build

This starts:

• PostgreSQL with pgvector on port 5432
• FastAPI backend on port 8000
• Next.js frontend on port 3000

3. Access the App

• Frontend: http://localhost:3000
• API Docs: http://localhost:8000/docs

Manual Setup (Development)

Backend

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Start PostgreSQL with pgvector
docker run -d --name pgvector -e POSTGRES_PASSWORD=postgres -p 5432:5432 ankane/pgvector:latest

# Configure environment
cp .env.example .env
# Edit .env with your OPENAI_API_KEY

# Run server
uvicorn app.main:app --reload

Frontend

cd frontend
npm install
npm run dev

Usage

1. Register/Login at http://localhost:3000/login
2. Upload PDFs on the Documents page
3. Chat with your documents - ask questions, request summaries, or explore topics
4. Click citations to jump to referenced pages in the PDF viewer

Architecture

User Query
    |
    v
[Embedding] ---> [Dense Search (pgvector HNSW)] ---+
    |                                              |
    v                                              v
[tsvector Query] ---> [Sparse Search (Full-Text)]  +---> [RRF Fusion] ---> [Top-K Chunks]
                                                          |
                                                          v
                                              [LLM Prompt with Context]
                                                          |
                                                          v
                                              [Streaming Response + Citations]

Database Schema

• users - Authentication
• documents - PDF metadata
• document_chunks - Text chunks with embeddings and tsvector
• chat_sessions - Conversation threads
• chat_messages - Messages with citation tracking

API Endpoints

Endpoint	Method	Description
/api/v1/auth/register	POST	Create account
/api/v1/auth/login	POST	Get access token
/api/v1/documents/upload	POST	Upload PDF
/api/v1/documents/	GET	List documents
/api/v1/chat/completions	POST	Chat with streaming
/api/v1/search/	POST	Hybrid search

License

MIT