Skip to main content

​
Overview

A production-ready Retrieval-Augmented Generation template you can fork, customize, and deploy on bult.ai. Upload documents, ask questions, get answers with source citations. Supports multiple LLM providers (OpenAI, Anthropic, Google, Ollama), hybrid search with reranking, OCR for scanned PDFs, multi-user authentication, and conversation export.

​
Features

  • Multi-model LLM support — switch between OpenAI, Anthropic, Google AI, or local Ollama models via environment variable
  • Advanced RAG pipeline — hybrid search (BM25 + vector), cross-encoder reranking, HyDE query transformation, multi-query retrieval, query decomposition
  • Document processing — PDF, DOCX, PPTX, TXT, MD, CSV, JSON, HTML; automatic OCR for scanned PDFs via Tesseract
  • Inline citations — every response cites source documents with relevance scores
  • Authentication — JWT login/register + optional Google OAuth
  • Analytics dashboard — usage metrics, cost tracking, query latency, top projects
  • Conversation export — Markdown, JSON, and PDF export with full Unicode support
  • Background processing — async job queue with progress tracking and retry logic
  • Single-page frontend — clean UI with streaming responses, markdown rendering, dark mode

​
Deploy on bult.ai

bult.ai is a PaaS that deploys from GitHub with built-in database templates and Docker support. You need three services: the app (GitHub), a PostgreSQL database, and a pgvector instance. Prerequisites
  • GitHub account
  • OpenAI API key (get one here)
  • bult.ai account
Step 1: Fork or clone this repository Fork this repo on GitHub (or clone it and push to your own repo). Step 2: Create the app service (GitHub)
  1. On bult.ai, click Create > GitHub
  2. Select your forked repository
  3. Go to the Git tab and change build settings from Nixpacks to Dockerfile. Set Dockerfile Path to Dockerfile and Dockerfile Context to .
  4. Inside the service settings, set the port to 8002
  5. Go to Environment Variables and add the variables from .env.example. The required ones:
PG_CONN: postgresql://YOUR_USER:YOUR_PASSWORD @pgvector:5432/YOUR_DB OPENAI_API_KEY: Your OpenAI API key JWT_SECRET: A random string (generate: python -c “import A random string (generate: python -c “import secrets; print(secrets.token_urlsafe(32))”) Add any other settings from .env.example as needed (LLM_MODEL, EMBEDDING_MODEL, etc.). Note: The PG_CONN hostname must match the name of your pgvector Docker service (step 4). Set the user, password, and database name to match your Postgres service (step 3). Step 3: Create the PostgreSQL database
  1. Click Create > in the list of services, go to Databases > Postgres
  2. This creates a Postgres instance from a built-in template — it’s automated
  3. The only thing you need to configure is the environment variables:
POSTGRES_USER: Your database username (e.g., pgvector) POSTGRES_PASSWORD: A strong password POSTGRES_DB: Your database name (e.g., ragdb) These values must match what you put in PG_CONN in step 2. Step 4: Create the pgvector service (Docker) The app needs the pgvector extension for vector search. Create a Docker service for it:
  1. Click Create > Docker
  2. Docker image: ankane/pgvector:latest
  3. Name this service to match the hostname in your PG_CONN (e.g., pgvector)
  4. Deploy the service
  5. After it’s running, add a volume mounted at /var/lib/postgresql/data for persistent storage
  6. Add internal port 5432
Step 5: Deploy and verify
  1. All three services should show as running
  2. Check the app service logs — you should see database migrations and the worker starting
  3. Open the public URL for your app service. Register a user and start chatting.
Troubleshooting Problems: Database connection error: Verify PG_CONN hostname matches your pgvector service name. Check that POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB match across services. Documents stuck in “queued”: Check app logs for errors. Verify OPENAI_API_KEY is set correctly. OCR not working: Nixpacks installs Tesseract automatically from nixpacks.toml. Check build logs. Build fails: Make sure your fork is up to date. Check build logs on bult.ai.