RAG-over-PDF

# 1. Clone
git clone https://github.com/sarmakska/rag-over-pdf.git
cd rag-over-pdf

# 2. Install (pnpm is the committed lockfile)
pnpm install

# 3. Configure
cp .env.example .env.local
# then edit .env.local and set:
#   OPENAI_API_KEY=sk-...

# 4. Run
pnpm dev

# 5. Visit http://localhost:3000
#    - drop in one or more PDFs
#    - tick which documents to include
#    - ask a question
#    - watch citations stream first, then the answer

Full walkthrough including env var reference and tuning: Quick-Start wiki page.

// app/api/chat/route.ts (sketch of the real handler)
import { embed, chat } from '@/lib/openai'
import { store } from '@/lib/vector-store'
import { rerank } from '@/lib/reranker'
import { buildCitationsEvent, buildTokenEvent, buildDoneEvent } from '@/lib/citations'

export async function POST(req: Request) {
  const { question, docIds } = await req.json()

  // 1. Embed the question
  const [qVec] = await embed([question])

  // 2. Hybrid retrieval (dense + BM25, fused with RRF)
  const candidates = await store.hybridSearch(qVec, question, {
    k: 40,
    docIds, // optional scope to a subset of uploaded PDFs
  })

  // 3. Rerank the recall pool for precision
  const top = await rerank(question, candidates, { topK: 5 })

  // 4. Stream NDJSON: citations first, then tokens, then done
  const stream = new ReadableStream({
    async start(controller) {
      controller.enqueue(buildCitationsEvent(top))
      const completion = await chat.stream({
        system: groundingPrompt,
        messages: [{ role: 'user', content: buildPrompt(question, top) }],
      })
      for await (const token of completion) {
        controller.enqueue(buildTokenEvent(token))
      }
      controller.enqueue(buildDoneEvent())
      controller.close()
    },
  })

  return new Response(stream, {
    headers: { 'Content-Type': 'application/x-ndjson' },
  })
}

// Client reading the NDJSON stream
const res = await fetch('/api/chat', {
  method: 'POST',
  body: JSON.stringify({ question, docIds }),
})

const reader = res.body!.getReader()
const decoder = new TextDecoder()
let buf = ''

while (true) {
  const { value, done } = await reader.read()
  if (done) break
  buf += decoder.decode(value, { stream: true })
  const lines = buf.split('\n')
  buf = lines.pop()!
  for (const line of lines) {
    if (!line) continue
    const event = JSON.parse(line)
    if (event.type === 'citations') showSources(event.citations)
    if (event.type === 'token') appendToken(event.value)
    if (event.type === 'done') finish()
  }
}

-- Migration to swap the in-memory store for Postgres + pgvector.
-- Drop this into your Supabase SQL editor or any Postgres 15+ instance.

create extension if not exists vector;

create table chunks (
  id          text primary key,
  doc_id      text not null,
  source      text,
  page        int,
  content     text not null,
  embedding   vector(1536) not null,
  created_at  timestamptz default now()
);

-- HNSW for fast approximate cosine search
create index chunks_embedding_idx
  on chunks
  using hnsw (embedding vector_cosine_ops);

-- Scope queries to a document set efficiently
create index chunks_doc_id_idx on chunks (doc_id);

-- Optional: keep BM25 in Postgres via tsvector
alter table chunks add column content_tsv tsvector
  generated always as (to_tsvector('english', content)) stored;

create index chunks_content_tsv_idx on chunks using gin (content_tsv);

Full migration including how to keep BM25 inside Postgres via tsvector: Swap-to-pgvector wiki page.