README.md

---
title: RAGnosis
emoji: 🧠
colorFrom: red
colorTo: indigo
sdk: gradio
sdk_version: 5.36.2
app_file: app.py
pinned: false
license: mit
short_description: Clinical Query Answering with RAG + MIMIC-IV Notes.
---

# 🧠 RAGnosis – Clinical Reasoning via Retrieval-Augmented Generation

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![Hugging Face](https://img.shields.io/badge/HuggingFace-RAGnosis-blue?logo=huggingface)](https://huggingface.co/spaces/asadsandhu/RAGnosis)
[![GitHub Repo](https://img.shields.io/badge/GitHub-asadsandhu/RAG--Diagnostic--Assistant-black?logo=github)](https://github.com/asadsandhu/RAG-Diagnostic-Assistant)

> ⚕️ A CPU-friendly RAG assistant for explainable clinical diagnosis, built using annotated notes from the [MIMIC-IV-Ext-DiReCT](https://github.com/asadsandhu/RAG-Diagnostic-Assistant/blob/main/mimic-iv-ext-direct-1.0.0.zip) dataset.

---

## 🖼️ Live Demo

Try it on **Hugging Face Spaces** (CPU-based, ~500s latency) 👉  :

🔗 https://huggingface.co/spaces/asadsandhu/RAGnosis

<p align="center">
  <img src="assets/demo.png" alt="Demo" width="750">
</p>

---

## ⚙️ Technical Stack

| Component      | Details                                                                 |
|----------------|-------------------------------------------------------------------------|
| 🧠 Model        | [`BioMistral/BioMistral-7B`](https://huggingface.co/BioMistral/BioMistral-7B) |
| 🏥 Dataset      | [`MIMIC-IV-Ext-DiReCT`](https://github.com/asadsandhu/RAG-Diagnostic-Assistant/blob/main/mimic-iv-ext-direct-1.0.0.zip) |
| 🔍 Retrieval    | FAISS + SentenceTransformers (`all-MiniLM-L6-v2`)                      |
| 💬 Interface    | Gradio (Runs on Hugging Face Spaces)                                   |
| ⚙️ Backend      | PyTorch + Transformers (CPU inference)                                 |

---

## 🩺 Key Features

- 🔎 Top-k clinical note retrieval from structured diagnostic chains  
- 🧠 Diagnosis generation using `BioMistral-7B` without GPU  
- 🗂️ MIMIC-IV-Ext-DiReCT backed medical reasoning  
- 💬 Natural query input and interpretable LLM output  
- ✅ Optimized for Hugging Face's free CPU tier (16GB RAM)

---

## 🧪 Example Prompt

> *patient is experiencing shortness of breath*

💬 **Model response:**  
> Shortness of breath is a common symptom that can be caused by a variety of respiratory conditions. The differential diagnosis for shortness of breath includes asthma, chronic obstructive pulmonary disease (COPD), congestive heart failure, pneumonia, and pneumothorax. In order to determine the cause of the shortness of breath, it is important to consider the patient's medical history, physical examination findings, and diagnostic testing results. For example, if the patient has a history of asthma and is experiencing wheezing and a prolonged expiratory phase on examination, this would suggest asthma as the cause of the shortness of breath. On the other hand, if the patient has a history of congestive heart failure and is experiencing orthopnea, crackles on auscultation, and a history of edema, this would suggest congestive heart failure as the cause of the shortness of breath.

---

## 🔧 Under the Hood

### 🧠 Step 1: Retrieval
- Sentence embeddings (`MiniLM-L6-v2`)
- FAISS indexing → [`faiss_index.bin`](https://github.com/asadsandhu/RAG-Diagnostic-Assistant/blob/main/faiss_index.bin)
- Source: [`retrieval_corpus.csv`](https://github.com/asadsandhu/RAG-Diagnostic-Assistant/blob/main/retrieval_corpus.csv)

### 🧱 Step 2: Prompt Construction
- Clinical query + retrieved chunks form an instruction prompt

### 🧬 Step 3: Generation
- Uses `BioMistral/BioMistral-7B`
- Generated on CPU (expect ~500 seconds)

---

## ⚠️ Note on Performance

| Feature      | Hugging Face (CPU)        | Colab / Local (GPU)                  |
|--------------|----------------------------|--------------------------------------|
| Model Used   | `BioMistral-7B`            | `Nous-Hermes-2-Mistral-7B-DPO`       |
| Speed        | ~500 seconds/query 🐢      | ~10 seconds/query ⚡                 |
| Accuracy     | ✅ Good                     | ✅ Great                             |
| Requirements | 1 CPU (free tier)          | CUDA GPU (Colab/Kaggle/local)        |

> Want faster responses? Use the [GPU version on GitHub](https://github.com/asadsandhu/RAG-Diagnostic-Assistant) with `app.py`.

---

## ⚙️ Run It Locally (GPU Recommended)

```bash
# 1. Clone the repository
git clone https://github.com/asadsandhu/RAG-Diagnostic-Assistant.git
cd RAG-Diagnostic-Assistant

# 2. Install dependencies
pip install -r requirements.txt

# 3. Run the app (auto-detects GPU)
python app.py
````

Required files (already in repo):

* ✅ [`retrieval_corpus.csv`](https://github.com/asadsandhu/RAG-Diagnostic-Assistant/blob/main/retrieval_corpus.csv)
* ✅ [`faiss_index.bin`](https://github.com/asadsandhu/RAG-Diagnostic-Assistant/blob/main/faiss_index.bin)

---

## 📁 Project Structure

```
RAG-Diagnostic-Assistant/
├── app.py
├── faiss_index.bin
├── retrieval_corpus.csv
├── requirements.txt
├── assets/
│   └── demo.png
└── README.md
```

---

## 👤 Author

Built with ❤️ by [Asad Ali](https://www.linkedin.com/in/asadsandhu0/)

* 🧠 Medium: [@asadsandhu](https://medium.com/@asadsandhu)
* 💻 GitHub: [@asadsandhu](https://github.com/asadsandhu)
* 🤗 Hugging Face: [@asadsandhu](https://huggingface.co/asadsandhu)

---

## 📜 License

MIT License — see [LICENSE](https://opensource.org/license/mit)

---

## 🙏 Acknowledgments

* MIMIC-IV-Ext-DiReCT – Annotated diagnostic dataset
* Hugging Face Transformers + Gradio
* SentenceTransformers + FAISS
* BioMistral + NousResearch

---

> ⚠️ **Disclaimer**: This is a research prototype and not intended for clinical decision-making.