RAG Supabase

A Retrieval-Augmented Generation (RAG) system built on top of Supabase with pgvector for semantic search.

Demo

UI

recording.mov

Features

• Semantic Search: Uses pgvector for cosine similarity search
• Local Embedding: Runs all-MiniLM-L6-v2 via sentence-transformers
• Local LLM: Runs Qwen2.5-1.5B via llama-cpp-python
• Streaming: SSE streaming for chat responses
• Self-hosted: Uses Docker Compose for local development

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     FastAPI Application                     │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐ ┌──────────────┐  ┌───────────────────┐   │
│  │  Embedding   │ │  pgvector    │  │  llama-cpp-python │   │
│  │  Pipeline    │ │  Search      │  │  (Qwen2.5-1.5B)   │   │
│  │  sentence-   │ │  (Supabase)  │  │                   │   │
│  │  transformers│ │              │  │                   │   │
│  └──────────────┘ └──────────────┘  └───────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │   Supabase       │
                    │   (PostgreSQL +  │
                    │    pgvector)     │
                    └──────────────────┘

Prerequisites

• Docker and Docker Compose
• uv (Python package manager)
• just (Command runner)
• curl (for downloading LLM model)

Quick Start

1. Install dependencies

just install

2. Start PostgreSQL

just db-up

3. Run migrations

just migrate

4. Seed the database

just seed

5. Start the API server

just dev

The API will be available at http://localhost:8000.

Commands

Run just to see all available commands:

Command	Description
just install	Install Python dependencies
just db-up	Start PostgreSQL via Docker
just db-down	Stop PostgreSQL
just migrate	Run Alembic migrations
just dev	Start development server
just seed	Seed database with sample data
just reseed	Clear and re-seed database
just run	Start full stack (DB + API)
just lint	Run linter
just typecheck	Run type checker

API Endpoints

Method	Endpoint	Description
GET	/api/rag/health	Health check
POST	/api/rag/query	Stateless RAG query
POST	/api/rag/chat	Conversational RAG
POST	/api/rag/chat/stream	SSE streaming chat
POST	/api/rag/seed	Ingest documents

Development

Adding New Migrations

just migrate-generate "Add users table"

Running Tests

uv run pytest

Code Formatting

just format

Kubernetes Deployment

Build Docker Images

just docker-build

Deploy to Kubernetes

just deploy

Port Forward

just port-forward-api

Environment Variables

Variable	Default	Description
DATABASE_URL	postgresql+asyncpg://postgres:...@localhost:5432/postgres	PostgreSQL connection URL
LLM_URL	http://127.0.0.1:8001/v1	llama-cpp-python server URL
LLM_MODEL	qwen2.5-1.5b-instruct	LLM model name
EMBEDDING_MODEL	all-MiniLM-L6-v2	Sentence-transformers model

Sample Data

The system comes with 30 sample articles covering:

• Python programming
• Machine learning
• Deep learning
• NLP
• Computer vision
• Databases
• Cloud computing
• And more...

Seed the database with:

just seed

License

MIT