IntelliRAG

v0.1.0 — Enterprise Retrieval Augmented Generation (RAG) assistant with a ChatGPT-like UX.

Upload documents, retrieve with Voyage embeddings + hybrid BM25/dense search (MMR + optional Voyage rerank), and get Claude-powered streaming answers with citations over FAISS.

Release tag: v0.1.0 · Phase 7 complete (Docker, testing, documentation).

Keywords: python · typescript · fastapi · react · vite · rag · retrieval-augmented-generation · langchain · anthropic · claude · voyageai · embeddings · faiss · vector-search · semantic-search · llm · generative-ai · machine-learning · sse · docker

---

Architecture

┌─────────────────────┐         ┌──────────────────────────────────────────┐
│  React Frontend     │  HTTP   │  FastAPI Backend                         │
│  Vite + MUI + RQ    │◄───────►│  API → Services → Repositories → DB      │
│  Nginx (Docker)     │  /api   │           ↘ Hybrid RAG / FAISS / Claude  │
└─────────────────────┘  SSE    └──────────────────────────────────────────┘

Design principles

Principle	How it is applied
Clean Architecture	API, services, repositories, and infrastructure are separated
SOLID	Interfaces for embeddings/vector store; single-responsibility modules
DI	dependency-injector composition root + FastAPI Depends
Swappable infra	EMBEDDING_PROVIDER, DATABASE_URL, and VECTOR_STORE_PROVIDER swap backends without rewriting domain logic
Config as code	All secrets/settings via .env → Settings (pydantic-settings)

Request flow (chat)

User message
  → JWT auth
  → Conversation memory
  → Scope to owned indexed documents
  → Query rewrite (short follow-ups)
  → Voyage query embedding + BM25
  → RRF fusion → MMR → optional Voyage rerank
  → Prompt builder + citations
  → Claude streaming (SSE)
  → Persist assistant message

Old vs new retrieval design: docs/rag-pipeline-comparison.md

---

Folder structure

IntelliRAG/
├── backend/
│   ├── app/
│   │   ├── api/v1/endpoints/   # auth, users, documents, chat, health
│   │   ├── config/             # Settings
│   │   ├── core/               # logging, security, exceptions
│   │   ├── database/           # async SQLAlchemy
│   │   ├── models/             # ORM
│   │   ├── schemas/            # Pydantic DTOs
│   │   ├── repositories/       # persistence
│   │   ├── services/           # auth, documents, chat, Claude, Voyage/FAISS
│   │   ├── rag/                # loaders, chunker, BM25, fusion, retriever, prompts
│   │   ├── middleware/
│   │   ├── dependencies/
│   │   ├── utils/
│   │   └── tests/
│   ├── alembic/
│   ├── scripts/entrypoint.sh
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── api/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── contexts/
│   │   ├── services/
│   │   ├── styles/             # ink-and-moss design tokens
│   │   ├── theme/
│   │   └── types/
│   ├── nginx.conf
│   ├── Dockerfile
│   └── package.json
├── docs/                       # RAG comparison + Cursor canvas
├── docker-compose.yml
├── .env.example
└── README.md

---

Prerequisites

• Docker Desktop / Docker Engine + Compose v2
• or local development:
  • Node.js 20+
  • Python 3.11+ (3.12 recommended)
• ANTHROPIC_API_KEY — Claude chat
• VOYAGE_API_KEY — embeddings + rerank (when EMBEDDING_PROVIDER=voyage)

---

Configuration

copy .env.example .env

Required / important values:

Variable	Purpose
JWT_SECRET	Long random secret for JWT signing
ANTHROPIC_API_KEY	Claude API key
VOYAGE_API_KEY	Voyage embeddings / rerank (default provider)
EMBEDDING_PROVIDER	voyage (default in .env.example) or sentence-transformers
EMBEDDING_MODEL / EMBEDDING_DIMENSION	e.g. voyage-4-lite / 1024
DATABASE_URL	SQLite by default; swap to PostgreSQL when ready
VECTOR_DB_PATH	FAISS index directory
VECTOR_TOP_K / RAG_*	Retrieval quality knobs (hybrid, MMR, rerank)
CORS_ORIGINS	Allowed frontend origins

After changing embedding dimension or provider, clear FAISS and re-index documents.

---

Run with Docker (recommended)

copy .env.example .env
# Edit .env — set JWT_SECRET, ANTHROPIC_API_KEY, VOYAGE_API_KEY

docker compose up --build

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:8000
OpenAPI docs	http://localhost:8000/docs
Health	http://localhost:8000/api/health

Stop:

docker compose down

Persist data (uploads, FAISS, SQLite) lives in the backend_storage Docker volume.

---

Run locally (development)

Backend

cd backend
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements-dev.txt
alembic upgrade head
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend

cd frontend
npm install
npm run dev

App: http://localhost:5173 (Vite proxies /api to the backend)

---

API documentation

Interactive OpenAPI: http://localhost:8000/docs

Auth

Method	Path	Description
POST	/api/auth/register	Register
POST	/api/auth/login	Login
POST	/api/auth/refresh	Refresh tokens
POST	/api/auth/logout	Revoke refresh token
POST	/api/auth/forgot-password	Placeholder
GET	/api/users/profile	Authenticated profile

Documents

Method	Path	Description
POST	/api/documents/upload	Upload + queue indexing
GET	/api/documents	List / search
GET	/api/documents/{id}	Detail + chunks
DELETE	/api/documents/{id}	Delete
PUT	/api/documents/{id}	Replace
POST	/api/documents/{id}/reindex	Reprocess

Chat

Method	Path	Description
POST	/api/chat/new	New conversation
GET	/api/chat/history	List conversations
GET	/api/chat/{id}	Conversation detail
PATCH	/api/chat/{id}	Rename
DELETE	/api/chat/{id}	Delete
POST	/api/chat	SSE streaming RAG chat

SSE events (POST /api/chat)

Event	Payload
conversation	{ conversation_id, title }
token	{ text }
complete	{ conversation_id, message_id, citations }

Authenticate SSE and REST with:

Authorization: Bearer <access_token>

---

Testing

Backend

cd backend
pip install -r requirements-dev.txt
pytest

Frontend

cd frontend
npm run test
npm run build

---

Features

• JWT auth (register, login, refresh, logout)
• Document upload for PDF, DOCX, TXT, Markdown
• Voyage embeddings (optional local sentence-transformers)
• Hybrid retrieval: dense + BM25, RRF fusion, MMR, optional Voyage rerank
• User-scoped FAISS retrieval with citations
• Claude streaming answers (SSE)
• Conversation memory, rename/delete
• ChatGPT-like UI: collapsible sidebar, jump-to-latest, documents modal, dark/light mode
• Docker Compose for backend + frontend

---

Future improvements

• Replace FAISS with Pinecone or Qdrant via VECTOR_STORE_PROVIDER
• Replace SQLite with PostgreSQL via DATABASE_URL
• Real forgot-password email delivery
• Frontend code-splitting for smaller bundles
• Horizontal scaling with a shared vector store and object storage
• Observability (OpenTelemetry / Prometheus)
• Role-based access control and per-workspace document isolation

---

Phase roadmap

Phase	Scope	Status
1	Setup, structure, config	Complete
2	Auth, DB models, repositories	Complete
3	Document upload, processing, embeddings	Complete
4	Vector store + retriever	Complete
5	Claude + SSE streaming	Complete
6	ChatGPT-like frontend	Complete
7	Docker, testing, README	Complete
—	Voyage + hybrid RAG (BM25 / MMR / rerank)	Complete (v0.1.0)