AI-powered Q&A for your organization's documents

ARCHIVED - See https://github.com/backchainai/evermore

Features • Quick Start • Configuration • Deployment • Documentation

Retriever: AI-Powered Document Q&A with RAG

Retriever is an open-source retrieval-augmented generation (RAG) system for document question-answering. It indexes an organization's PDFs, Word documents, spreadsheets, and web pages, then answers natural-language questions with cited sources. Built by Chris Krough under Backchain.

Retriever is an AI-powered question-answering system that helps users find information in your organization's policy and procedure documents. Upload your documents, and Retriever uses RAG (Retrieval-Augmented Generation) to provide accurate, sourced answers.

Retriever can be adapted for any organization with documentation that users need to search.

Features

• Natural Language Q&A — Ask questions in plain English and get accurate answers with source citations
• Multi-Document Support — Index multiple markdown and text documents
• Source Citations — Every answer includes clickable citations to the original documents
• Conversation History — Continue conversations with context from previous questions
• Hybrid Search — Combines semantic understanding with keyword matching for better retrieval
• Content Safety — Built-in moderation and hallucination detection
• User Authentication — Secure login system with JWT tokens
• Semantic Caching — Faster responses for similar questions
• Rate Limiting — Prevent abuse with configurable request limits

Quick Start

Prerequisites

• Python 3.13+ with uv
• Docker
• Supabase CLI
• API keys: OpenRouter (LLM) and OpenAI (embeddings/moderation)

Get Running

git clone https://github.com/ckrough/retriever.git
cd retriever
cp .env.example .env
# Edit .env with your API keys

supabase start                    # Auth + Supabase services
docker compose up -d              # pgvector postgres + jaeger

cd backend && uv sync --dev
uv run alembic upgrade head
uv run uvicorn retriever.main:app --reload --port 8000

Backend API: http://localhost:8000/docs. The frontend portal lives in the separate stacker repository.

See CONTRIBUTING.md for full development setup, quality checks, and workflow.

Usage

Web Interface

1. Login — Create an account or log in at /login
2. Ask Questions — Type your question in the chat interface
3. View Sources — Click citation cards to see the original document text
4. Continue Conversations — Ask follow-up questions with context preserved

API

Retriever exposes a REST API for programmatic access:

# Ask a question
curl -X POST http://localhost:8000/api/v1/rag/ask \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"question": "What is the check-in procedure?"}'

API documentation is available at /docs (OpenAPI/Swagger).

Configuration

See .env.example for all configuration options. Required API keys:

Variable	Description
OPENROUTER_API_KEY	LLM provider API key
OPENAI_API_KEY	Embeddings and moderation API key

Auth is handled by Supabase (local via supabase start, production via Supabase project). See CONTRIBUTING.md for full environment setup.

Document Preparation

For best results:

• Use markdown format with clear headings (#, ##, ###)
• Keep sections focused on single topics
• Use descriptive headings that match how users ask questions
• Include relevant keywords naturally in the text

Deployment

• Backend: Cloud Run via gcloud run deploy --source ./backend
• Database: Supabase (managed Postgres + pgvector)
• Frontend: deployed from the stacker repository (Cloudflare Pages)

Production Checklist

• Set DEBUG=false
• Configure Supabase project with RLS policies
• Set up Cloudflare AI Gateway for LLM routing
• Configure OpenTelemetry (GCP Cloud Trace or OTLP endpoint)
• Enable Langfuse for LLM observability (optional)
• HTTPS handled by Cloud Run / Cloudflare Pages

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    DOCUMENT PIPELINE                         │
│  [Markdown/Text] → [Chunker] → [Embeddings] → [pgvector]     │
└─────────────────────────────────────────────────────────────┘
                                                    ↓
┌─────────────────────────────────────────────────────────────┐
│                      QUERY FLOW                              │
│  [Question] → [Hybrid Search] → [Rerank] → [LLM] → [Answer]  │
└─────────────────────────────────────────────────────────────┘

Tech Stack:

• Backend: Python 3.13+, FastAPI, SQLAlchemy 2.0 async, Pydantic 2.x
• LLM: OpenRouter via Cloudflare AI Gateway
• Vector DB: Supabase Postgres + pgvector (HNSW cosine + GIN full-text)
• Auth: Supabase Auth / JWKS
• Observability: structlog + OpenTelemetry + Langfuse
• Deploy: Cloud Run (backend)
• Frontend: stacker (separate repo): SvelteKit + Svelte 5 runes + Skeleton UI v4

Development

See CONTRIBUTING.md for full setup and quality check commands.

Documentation

• Architecture Overview
• Development Standards
• Implementation Roadmap
• Deployment Guide
• Adding Documents

License

Apache License 2.0 (Apache-2.0). See LICENSE for the full text and NOTICE for attribution.

Copyright (C) 2025 Backchain LLC

About / Built by

I'm Chris Krough, and I build production AI systems like this one. Retriever is the kind of work I do: retrieval pipelines, LLM safety, and observability shipped as real, deployable software. Find me on my site and LinkedIn.

Retriever is developed and maintained under Backchain, my AI transformation consulting practice. Backchain helps organizations discover where AI works: Discover Where AI Works.

If Retriever is useful to you, star the repo and reach out. I'm open to collaboration, consulting, and conversations about applied AI.