README.md

metadata

title: QUADRANT RAG - Medical AI Assistant
emoji: 🩺
colorFrom: indigo
colorTo: blue
sdk: streamlit
sdk_version: 1.28.0
app_file: app.py
pinned: false

🩺 QUADRANT RAG - Medical AI Assistant

A sophisticated Retrieval-Augmented Generation (RAG) system optimized for medical education, specifically designed for MRCS, USMLE, and NEET-PG exam preparation.

🚀 Features

• 🌐 Cloud-Native: Uses Qdrant Cloud for scalable vector storage
• 🧠 Advanced AI: Powered by OpenAI GPT-4o-mini for medical responses
• 📚 Medical-Optimized: Specialized for Harrison's Principles and medical textbooks
• 🔍 Semantic Search: Advanced embedding-based document retrieval
• 📖 Citation System: Proper source attribution with page references
• 💊 Clinical Pearls: Highlights crucial practical medical insights

🛠️ Technology Stack

• Frontend: Streamlit (optimized for HuggingFace Spaces)
• Vector Database: Qdrant Cloud
• LLM: OpenAI GPT-4o-mini
• Embeddings: OpenAI text-embedding-3-small
• PDF Processing: pypdf with medical text optimization

🔧 Setup

Environment Variables

Create a .env file with your credentials:

# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key-here

# Qdrant Cloud Configuration
QDRANT_URL=https://your-cluster-url.qdrant.tech
QDRANT_API_KEY=your-qdrant-api-key-here
QDRANT_COLLECTION_NAME=documents

# Application Configuration
USE_MEMORY_DB=false
STREAMLIT_SERVER_PORT=7860
STREAMLIT_SERVER_ADDRESS=0.0.0.0

Local Development

pip install -r requirements.txt
streamlit run app.py

HuggingFace Spaces Deployment

1. Configure Space metadata (already in this repo)

• README.md includes the Spaces front matter that declares a Streamlit app: app_file: app.py.

2. Set Secrets in your Space (Settings → Variables and secrets)

• OPENAI_API_KEY
• OPENAI_COMPLETIONS_MODEL=gpt-4o-mini
• QDRANT_URL
• QDRANT_API_KEY
• QDRANT_COLLECTION_NAME=documents
• Optional reliability on Spaces:
  • QDRANT_TIMEOUT=120
  • QDRANT_UPSERT_BATCH=16
  • QDRANT_PREFER_GRPC=false

3. Deploy via helper script (from your local repo)

export HF_USER=athulnambiar
export HF_SPACE=pyqsprag
export HF_TOKEN=hf_xxx   # write token
./scripts/push_to_hf.sh

4. Open your Space App tab and “Restart this Space” if needed.

📖 Usage

1. Upload Documents: Use the sidebar to upload medical PDF documents
2. Select Active Document: Click on a document to make it active for querying
3. Ask Medical Questions: Type natural language medical queries
4. Review Responses: Get structured, exam-focused answers with citations

Sample Questions

• "What are the diagnostic criteria for fever of unknown origin?"
• "Explain the differential diagnosis of anion gap metabolic acidosis"
• "What is the workup for neutropenic fever?"
• "Describe the MUDPILES mnemonic for metabolic acidosis"

🏥 Medical Education Focus

The system is specifically optimized for:

• Structured Learning: Organized responses by clinical categories
• Exam Preparation: MRCS, USMLE, NEET-PG focused content
• Clinical Pearls: Highlighted practical insights
• Evidence-Based: Citations from authoritative medical texts
• Differential Diagnosis: Systematic approach to medical conditions

🔐 Security & Privacy

• API keys are stored securely in environment variables
• No medical data is persistently stored
• All processing happens in secure cloud infrastructure
• Compliant with medical education standards

📊 System Architecture

PDF Upload → Text Extraction → Chunking → Embedding → Qdrant Cloud
                                                           ↓
User Query → Query Expansion → Vector Search → Context Retrieval
                                                           ↓
Context + Query → GPT-4o-mini → Medical Response → Citations

🤝 Contributing

This system is designed for medical education and research purposes. Contributions focused on improving medical accuracy and educational value are welcome.

⚠️ Disclaimer

This tool is for educational purposes only and should not be used for actual clinical decision-making. Always consult authoritative medical sources and qualified healthcare professionals for patient care decisions.

📄 License

Educational and research use only. Please respect medical education licensing and copyright requirements.