Metadata-Version: 2.4
Name: medreport-ai
Version: 0.1.0
Summary: RAG-based medical PDF analyzer — ask plain-language questions, get grounded answers with citations
License-Expression: MIT
Project-URL: Homepage, https://github.com/abdullahkousa2/medreport-ai
Project-URL: Repository, https://github.com/abdullahkousa2/medreport-ai
Project-URL: Bug Tracker, https://github.com/abdullahkousa2/medreport-ai/issues
Keywords: medical,RAG,PDF,AI,FastAPI,LLM,FAISS,Groq
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi==0.111.0
Requires-Dist: uvicorn[standard]==0.30.1
Requires-Dist: python-multipart==0.0.9
Requires-Dist: groq>=0.9.0
Requires-Dist: pymupdf==1.24.5
Requires-Dist: sentence-transformers==3.0.1
Requires-Dist: faiss-cpu==1.8.0
Requires-Dist: numpy<2.0.0,>=1.24.0
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: pydantic>=2.0.0

---
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.**

![Python](https://img.shields.io/badge/Python-3.10+-3776AB?style=flat&logo=python&logoColor=white)
![FastAPI](https://img.shields.io/badge/FastAPI-0.111-009688?style=flat&logo=fastapi&logoColor=white)
![Groq](https://img.shields.io/badge/LLM-Groq%20Llama%203.3-F55036?style=flat)
![FAISS](https://img.shields.io/badge/Vector%20Store-FAISS-0078D4?style=flat)
![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=flat&logo=docker&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green?style=flat)

---

## 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](https://console.groq.com)

### 1. Clone & install

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

### 2. Set your API key

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

### 3. Run

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

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

---

## Docker

```bash
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
```http
POST /api/upload
Content-Type: multipart/form-data

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

### Ask
```http
POST /api/ask
Content-Type: application/json

{ "session_id": "uuid-string", "question": "What medications were prescribed?" }
```
```json
{
  "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:

```bash
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.
