ahsananwar102/MedReport-Explainer

🏥 Medical Report Explainer

An AI-powered web application that helps users understand medical reports through intelligent explanations, summaries, and Q&A functionality using RAG (Retrieval-Augmented Generation) and Groq API.

✨ Features

• —📄 Document Upload: Support for PDF, TXT, and DOCX medical reports
• —🔍 Text Extraction: Advanced extraction with fallback methods for complex documents
• —📚 RAG System: Retrieval-Augmented Generation using medical corpus (PubMed + Mayo Clinic)
• —🧠 AI Explanations: Groq-powered explanations at different reading levels (ultra-fast inference)
• —📝 Smart Summaries: Generate patient-friendly summaries
• —❓ Interactive Q&A: Ask questions about medical terms and conditions
• —🏷️ Term Highlighting: Identify and explain complex medical terminology
• —👍 Feedback System: User feedback collection and analytics
• —⚠️ Medical Disclaimer: Prominent medical disclaimers and safety warnings

🛠️ Tech Stack

• —Frontend: Streamlit
• —Backend: Python 3.10+
• —Vector Store: FAISS for similarity search
• —Embeddings: Sentence-BERT (all-MiniLM-L6-v2)
• —LLM: Groq API (ultra-fast inference with Llama3-70B)
• —Document Processing: PyMuPDF, python-docx
• —Data Sources: PubMed (via Entrez API), Mayo Clinic articles
• —Deployment: Docker + Hugging Face Spaces

🚀 Quick Start

1. Get Groq API Key

1. 1.Go to Groq Console
2. 2.Sign up for a free account
3. 3.Create a new API key
4. 4.Copy the API key for deployment

2. Deploy to Hugging Face Spaces

1. 1.Create a new Space:
2. 2.Go to Hugging Face Spaces
3. 3.Click "Create new Space"
4. 4.Choose "Docker" as the SDK
5. 5.Set visibility (public/private)

1. 1.Upload files:
2. 2.Upload all project files to your Space
3. 3.Ensure Dockerfile is in the root directory

1. 1.Set environment variables:
2. 2.In your Space settings, add:
3. 3.GROQ_API_KEY: Your Groq API key

1. 1.Deploy:
2. 2.The Space will automatically build using the Dockerfile
3. 3.Build time: ~10-15 minutes for first deployment

📁 Project Structure

medreport_explainer/
├── Dockerfile                 # Docker configuration for deployment
├── .dockerignore             # Files to exclude from Docker build
├── streamlit_app.py          # Main Streamlit application
├── app.py                    # Entry point for Hugging Face Spaces
├── requirements.txt          # Python dependencies (optimized)
├── README.md                 # This file
├── config/
│   ├── __init__.py
│   └── config.py            # Configuration settings
├── src/
│   ├── __init__.py
│   ├── data_ingestion.py    # PubMed & Mayo Clinic data download
│   ├── document_processor.py # PDF/TXT/DOCX text extraction
│   ├── embeddings.py        # FAISS vector store & embeddings
│   └── llm_integration.py   # Google Gemini integration
├── utils/
│   ├── __init__.py
│   └── feedback.py          # User feedback management
└── data/                    # Data storage (created at runtime)
    ├── corpus/              # Medical corpus storage
    ├── embeddings/          # FAISS index files
    └── feedback.json        # User feedback data

🔧 Configuration

Key configuration options in config/config.py:

# API Settings
GROQ_API_KEY = os.getenv("GROQ_API_KEY")
GROQ_MODEL = "llama3-70b-8192"  # Fast Groq model

# Embedding Settings
EMBEDDING_MODEL = "all-MiniLM-L6-v2"  # Lightweight model
EMBEDDING_DIMENSION = 384
CHUNK_SIZE = 500
CHUNK_OVERLAP = 50

# File Processing
MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
SUPPORTED_FORMATS = [".pdf", ".txt", ".docx"]

📚 Usage

Basic Workflow

1. 1.Upload a medical report (PDF, TXT, or DOCX)
2. 2.Choose reading level (12-year-old or 8th-grade)
3. 3.Review extracted sections and highlighted complex terms
4. 4.Generate summary for easy understanding
5. 5.Ask questions about specific terms or conditions
6. 6.Provide feedback to improve the system

Reading Levels

• —12-year-old: Very simple language, short sentences, no medical jargon
• —8th-grade: Clear language with medical terms explained in parentheses

🛡️ Safety & Disclaimers

This application includes comprehensive medical disclaimers and safety warnings:

• —⚠️ Educational purposes only - Not medical advice
• —👨‍⚕️ Always consult healthcare professionals for medical decisions
• —🚨 Emergency situations - Contact emergency services immediately
• —📋 Information limitations - May not apply to specific situations

🔍 Data Sources

Medical Corpus

• —PubMed: Medical literature abstracts via Entrez API
• —Mayo Clinic: Disease and condition articles
• —Processing: Chunked and embedded for RAG retrieval

Privacy

• —No patient data is stored permanently
• —Feedback is stored locally and anonymized
• —API calls to Gemini follow Google's privacy policies

🐛 Troubleshooting

Common Issues

1. 1.API Key Error

   Error: GROQ_API_KEY environment variable not set

Solution: Set your Groq API key in Hugging Face Space settings

1. 1.Docker Build Issues

   Build timeout or memory errors

Solution: The Dockerfile is optimized for Hugging Face Spaces limits

1. 1.File Upload Issues

   Error: Unsupported format

Solution: Use PDF, TXT, or DOCX files under 10MB

🤝 Contributing

1. 1.Fork the repository
2. 2.Create feature branch (git checkout -b feature/amazing-feature)
3. 3.Commit changes (git commit -m 'Add amazing feature')
4. 4.Push to branch (git push origin feature/amazing-feature)
5. 5.Open a Pull Request

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• —Groq for ultra-fast AI inference
• —Hugging Face for hosting platform
• —PubMed/NCBI for medical literature access
• —Mayo Clinic for patient education resources
• —Streamlit for the web framework

⚠️ Important: This tool is for educational purposes only. Always consult qualified healthcare professionals for medical advice, diagnosis, and treatment decisions.