rag-docs-real

A FastAPI backend + static frontend for indexing real documents (PDF/TXT/CSV/MD) into FAISS and asking questions with citations. Includes a Mermaid diagram generator for a vertical (cascata) flowchart.

Features

• Upload documents and persist locally
• Extract text from PDF/TXT/MD/CSV
• Chunk + embed with SentenceTransformers (MiniLM-L6-v2)
• FAISS vector search with metadata persistence
• Q&A with citations and confidence score
• Mindmap/flowchart generation (no LLM, fast)
• Frontend UI (Upload / Index / Ask / Mindmap)
• Export diagram as SVG/PNG (PNG may be blocked by browser security)
• Reset button to clear the index

Tech Stack

• FastAPI, Uvicorn
• FAISS (CPU)
• SentenceTransformers
• httpx
• pypdf, pandas

Setup

Python

Recommended: Python 3.10+

Create and activate venv

python -m venv .venv
.venv\Scripts\Activate.ps1

Install dependencies

pip install -r requirements.txt

Configure environment

copy .env.example .env

Run the backend

uvicorn src.main:app --reload

Run the frontend

cd frontend
python -m http.server 8001

Open: http://127.0.0.1:8001

API Usage (curl)

Upload

curl.exe -X POST "http://127.0.0.1:8000/upload" -F "file=@C:\path\to\file.txt"

Index

curl.exe -X POST "http://127.0.0.1:8000/index/YOUR_DOC_ID"

Ask

curl.exe -X POST "http://127.0.0.1:8000/ask" -H "Content-Type: application/json" -d "{\"question\":\"...\",\"top_k\":5,\"max_context_chunks\":4}"

Mindmap (vertical flowchart)

curl.exe -X POST "http://127.0.0.1:8000/mindmap" -H "Content-Type: application/json" -d "{\"doc_id\":\"YOUR_DOC_ID\",\"top_k\":12,\"max_context_chunks\":8}"

Reset index

curl.exe -X POST "http://127.0.0.1:8000/reset"

Notes

• If /ask returns 502, check your LLM provider settings in .env
• The index is global: use Reset Index to clear old docs
• PNG export may be blocked by browser security; use SVG export

Troubleshooting

• PDF extraction: scanned PDFs need OCR before upload
• If embeddings are slow, reduce document size or chunking limits
• If frontend shows no diagram, check browser Console for errors

Roadmap

• Reranking
• Multi-doc namespaces
• Authentication
• UI improvements