convez.ai
PluginBusca & PesquisaIntermediário
santanu2908

Chat com PDF via RAG Minimalista

santanu2908/chat-with-pdf-rag

RAG from scratch: PDF → FAISS + BM25 → respostas com fontes

Ver no GitHub
InicialPluginScore · de 0 a 100

Pipeline RAG leve e direto: upload de PDF, busca híbrida (FAISS + BM25) e respostas citadas. Implementação de ~300 linhas em FastAPI sem LangChain, ideal para prototipação rápida e aprendizado de retrieval-augmented generation.

Instalação

$npx convez-ai santanu2908/chat-with-pdf-rag

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
4
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Prototipação de sistemas de Q&A sobre documentos
  • Demonstração educacional de retrieval-augmented generation
  • Consulta local de PDFs com respostas citadas e grounding

Veredito

Excelente referência didática para quem quer entender RAG sem abstrações de frameworks. Implementação clara, bem documentada e production-ready para casos simples; bom ponto de partida antes de migrar para stacks maiores.

README

A tradução para o português deste README ainda está na fila.

Chat with PDF (RAG Lite)

A minimal Retrieval-Augmented Generation (RAG) service. Upload a PDF, ask questions, get answers grounded in the document with cited source chunks.

Read the full write-up: I built a RAG pipeline from scratch — no LangChain, just FastAPI + FAISS

How it works

PDF ─► extract text (pypdf) ─► chunk (500 char, 50 overlap) ─► embed (MiniLM-L6-v2)
                                                                        │
                                                                        ▼
question ─► embed ─► FAISS + BM25 hybrid search (RRF) ─► build prompt with chunks ─► LLM ─► answer + sources

Stack

LayerChoiceWhy
APIFastAPIType-safe, async, auto Swagger UI
PDFpypdfPure Python, no system deps
Embeddingssentence-transformers (all-MiniLM-L6-v2)Free, local, 384-dim, CPU-friendly
Vector storeFAISS (IndexFlatIP) + BM25 (rank-bm25)Hybrid retrieval with Reciprocal Rank Fusion
LLMGroq / OpenAI / AnthropicSwappable via LLM_PROVIDER env var

Quickstart

Requires uv (install: curl -LsSf https://astral.sh/uv/install.sh | sh).

uv sync                            # creates .venv and installs deps from pyproject.toml
cp .env.example .env               # then edit .env — see env vars below
uv run uvicorn app.main:app --reload

Open http://localhost:8000/docs and:

  1. Use POST /upload to send a PDF (a sample is included at data/sample_test_file.pdf)
  2. Use POST /query with {"question": "...", "top_k": 3}

Adding a dependency later: uv add <package>. Running any script: uv run <cmd>.

Environment variables

VariableRequiredDescription
LLM_PROVIDERYesgroq, openai, or anthropic
GROQ_API_KEYIf provider = groqAPI key from Groq console
OPENAI_API_KEYIf provider = openaiAPI key from OpenAI
ANTHROPIC_API_KEYIf provider = anthropicAPI key from Anthropic
GROQ_MODELNoDefaults to llama-3.3-70b-versatile
OPENAI_MODELNoDefaults to gpt-4o-mini
ANTHROPIC_MODELNoDefaults to claude-haiku-4-5-20251001

API

  • GET /health — sanity check + how many chunks are indexed
  • POST /upload — multipart file (PDF). Replaces any previous index.
  • POST /query — {question, top_k} → {answer, sources[]}

Design notes (the interesting bits)

Chunking. 500 characters with 50-char overlap, chunked within each page so every chunk has an unambiguous page number. Character-based (not token-based) for v1 simplicity; production would use a tokenizer.

Embeddings. all-MiniLM-L6-v2 is normalized so we can use FAISS IndexFlatIP (inner product) as cosine similarity. Tradeoff vs OpenAI embeddings: lower quality but zero API cost and works offline.

Retrieval. Hybrid search combining FAISS (dense/semantic) and BM25 (sparse/keyword), fused with Reciprocal Rank Fusion (RRF, k=60). This catches exact keyword matches (e.g. "CEO") that pure vector search misses.

Grounding. System prompt instructs the model to answer only from context and explicitly say "I couldn't find that in the document." otherwise. Sources are returned to the user separately, not formatted into the answer — this keeps the LLM from hallucinating citations.

LLM swap. Single LLMClient.generate(system, user) interface. Three implementations behind LLM_PROVIDER=groq|openai|anthropic. No streaming in v1 (streaming is where SDKs diverge sharply).

Example

Request:

POST /query
{"question": "What is the list price of the Magpie-7?", "top_k": 3}

Response:

{
  "answer": "The list price of the Magpie-7 is €68,400 per unit.",
  "sources": [
    {"chunk_id": 4, "text": "...", "page": 2, "score": 0.7542}
  ]
}

Sample Q&A results

Tested against the included data/sample_test_file.pdf — a fictional 5-page company/product document. Results are grouped by difficulty.

Single-hop (direct lookup)

QuestionExpected answerResult
What is the list price of the Magpie-7?€68,400 per unit (p2)Correct
What is the IP rating of the Magpie-7?IP54 (p2)Correct
When was the Magpie-7 released?14 September 2025 (p2, p5)Correct
What's the response SLA on the Enterprise tier?1 hour, 24/7 (p3)Correct
Who is the CEO of Zentara Robotics?Iris Kallas (p1)Correct (fixed in v2 with hybrid retrieval)

Specific numbers (hallucination check)

QuestionExpected answerResult
How long does it take to charge the Magpie-7 from 0 to 80%?42 minutes (p2)Correct
What's the maximum payload per arm?22 kg / 40 kg total (p2)Correct
What's the MTBF of the Magpie-7?4,200 hours (p5)Correct
How many employees does Zentara have?287 as of 1 March 2026 (p1)Correct with top_k=5 (fixed in v2 with hybrid retrieval)

Tables

QuestionExpected answerResult
What's included in the Standard tier?€2,150/month, 4-hour SLA, 750k picks/month (p3)Correct
List all company history milestones from 2020 onwards2020 Series A, 2022 Voorhuis deployment, 2024 Series B + Kraków, 2025 Magpie-7 launch + 1M picks, 2026 Munich office (p5)Correct

Multi-hop / synthesis

QuestionExpected answerResult
If I want 1-hour SLA support, what will it cost per month?€4,800/month — Enterprise tier (p3)Correct
Which languages will the voice interface support after the June 2026 update?7 total: EN, DE, ET, PL, JA + ES and FR (p4)Correct
What happens if I want to cancel my subscription early?60 days' notice; early termination fee = 2 months of contracted rate (p3)Correct

Negative tests (should say "not in document")

QuestionExpected answerResult
Who is Zentara's Chief Financial Officer?Not stated — only CEO, CTO, and Head of People are namedCorrect
Does the Magpie-7 support Mandarin?Not supported and not on the roadmapCorrect
What's Zentara's stock ticker?Not in the document (company appears private)Correct

Tricky retrieval (info spread across pages)

QuestionExpected answerResult
What forms or certifications do operators need?Zentara Safety Certification (4-hr course), Form ZR-INSP-22, ISO 10218-2, ISO/TS 15066 (p4)Correct
Compare the Starter and Enterprise tiersStarter: €1,200/mo, next-biz-day SLA, 200k picks. Enterprise: €4,800/mo, 1-hr 24/7 SLA, unlimited picks (p3)Correct

v1 → v2: hybrid retrieval fixed the failures

In v1 (pure FAISS), "Who is the CEO?" and "How many employees?" both failed because page 1's dense "Company snapshot" table produced muddy embeddings. In v2, BM25 catches the exact keyword matches and RRF fuses them with FAISS results. The CEO question now passes at default top_k=3. The employee count question passes at top_k=5 — the chunk still ranks lower due to fact density, but hybrid retrieval brings it within reach.

Known limitations

  • Scanned PDFs aren't OCR'd
  • One PDF at a time (re-uploading replaces the index)
  • No persistence — index is in-memory
  • No conversation history (each query is independent)
  • Dense fact-packed chunks can still rank low even with hybrid retrieval (may need higher top_k)

What I'd add next

  • Hybrid retrieval (BM25 + vector) to catch keyword matches ✓ Added in v2
  • Reranker (e.g. cross-encoder) for better precision
  • Retrieval evaluation set to measure accuracy
  • Streaming responses
  • Conversation memory
Ver o original no GitHub

Bom para

Relacionados