DescriberAI

Stage 1 MVP for a citation-aware PDF RAG assistant. Upload a single PDF, index it once, and ask grounded questions against the most relevant chunks.

The current retrieval pipeline includes text cleaning, recursive chunking, MMR-based retrieval diversification, grounded prompting, and citation snippets.

The locked Stage 1 product contract lives in docs/stage-1-contract.md.

Stack

• Frontend: React, TypeScript, Vite, Tailwind CSS, TanStack Query
• Backend: FastAPI, PyMuPDF, FAISS, SQLite
• AI providers: OpenAI or Gemini via environment variables

Run Locally

Fastest Start

cp .env.example .env
./start.sh

Then open http://localhost:5173.

Manual Backend

python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
cp .env.example .env
uvicorn backend.app.main:app --reload

Set either OPENAI_API_KEY or GEMINI_API_KEY in .env and choose LLM_PROVIDER.

2. Frontend

npm install --prefix frontend
npm run dev --prefix frontend

The frontend expects the API at http://localhost:8000 by default.

API

• POST /upload with multipart file
• POST /chat with { "document_id": "...", "question": "..." }
• GET /documents/{document_id}

Product Contract

• one active document at a time
• soft replace when a new document is uploaded
• browser-persisted client settings
• chunked plain-text streaming reserved for the Stage 1 streaming phase

See docs/stage-1-contract.md for the full contract.

Notes

• Files are stored under backend/storage/uploads
• FAISS indexes are stored under backend/storage/faiss/<document_id>
• SQLite database defaults to backend/storage/app.db