medreport-ai 0.1.0

RAG-based medical PDF analyzer — ask plain-language questions, get grounded answers with citations

---

title: MedReport AI emoji: 🏥 colorFrom: blue colorTo: indigo sdk: docker app_port: 8000 pinned: false

MedReport AI 🏥

Ask plain-language questions about any medical PDF — every answer is grounded in the document with exact source citations.

---

What it does

Upload any medical PDF (discharge summaries, lab reports, referral letters) and ask questions in plain English. The app retrieves the most relevant passages from your document and uses Llama 3.3-70B via Groq to answer — never hallucinating beyond what the document says.

Feature	Detail
📄 PDF ingestion	PyMuPDF text extraction, 400-word chunks with 80-word overlap
🔍 Semantic search	sentence-transformers all-MiniLM-L6-v2 + FAISS cosine similarity
🤖 LLM	Groq llama-3.3-70b-versatile — fast, free tier available
💬 Chat UI	Dark-themed glass-morphism interface, source citations, page references
🔒 Privacy	Everything runs locally / in your container — no data leaves your server

---

Architecture

PDF Upload
    │
    ▼
PyMuPDF ──► Text Chunks (400w / 80w overlap)
                │
                ▼
        SentenceTransformer          FAISS IndexFlatIP
        (all-MiniLM-L6-v2)    ──►   (cosine similarity)
                                          │
User Question ──► embed ──────────────► top-5 chunks
                                          │
                                          ▼
                                  Groq llama-3.3-70b
                                  (system + context prompt)
                                          │
                                          ▼
                               Answer + Citations (page, score)

---

Quick start

Prerequisites

• Python 3.10+
• A free Groq API key

1. Clone & install

git clone https://github.com/abdullahkousa2/medreport-ai.git
cd medreport-ai
pip install -r requirements.txt

2. Set your API key

cp .env.example .env
# then edit .env and paste your Groq key:
# GROQ_API_KEY=gsk_...

3. Run

uvicorn app.main:app --host 127.0.0.1 --port 8000

Open http://localhost:8000 — drop in a PDF and start asking questions.

---

Docker

docker build -t medreport-ai .
docker run -p 8000:8000 -e GROQ_API_KEY=gsk_your_key_here medreport-ai

---

API Reference

Endpoint	Method	Description
GET /	GET	Serve the chat UI
POST /api/upload	POST	Upload a PDF → returns session_id
POST /api/ask	POST	Ask a question → returns answer + citations
GET /health	GET	Health check

Upload

POST /api/upload
Content-Type: multipart/form-data

file: <your-pdf>

{
  "session_id": "uuid-string",
  "filename": "report.pdf",
  "chunks_indexed": 47,
  "message": "Indexed 47 text segments — ready to answer questions."
}

Ask

POST /api/ask
Content-Type: application/json

{ "session_id": "uuid-string", "question": "What medications were prescribed?" }

{
  "answer": "According to Source 2, the patient was prescribed Aspirin 75mg...",
  "citations": [
    { "source": 1, "page": 4, "excerpt": "...", "score": 0.891 }
  ]
}

---

Sample report

A realistic fake cardiac discharge summary (sample_medical_report.pdf) is included for testing. Regenerate it with:

pip install reportlab
python generate_sample_report.py

---

Project structure

medreport-ai/
├── app/
│   ├── main.py              # FastAPI app, routes, static files
│   ├── rag_engine.py        # PDF processing, FAISS index, Groq Q&A
│   ├── routers/
│   │   └── api.py           # /api/upload and /api/ask endpoints
│   └── static/
│       ├── index.html       # Chat UI
│       ├── style.css        # Design system (dark glass-morphism)
│       └── app.js           # Upload, chat, citations logic
├── Dockerfile
├── requirements.txt
├── .env.example
├── generate_sample_report.py
└── sample_medical_report.pdf

---

Tech stack

Layer	Technology
Web framework	FastAPI 0.111
LLM	Groq API — llama-3.3-70b-versatile
Embeddings	sentence-transformers — all-MiniLM-L6-v2
Vector search	FAISS IndexFlatIP (cosine via L2-normalised inner product)
PDF parsing	PyMuPDF (fitz)
Frontend	Vanilla HTML / CSS / JS — no framework
Container	Docker (python:3.10-slim)

---

License

MIT — free to use, modify, and deploy.