🏆 CommunityMed AI - MedGemma Impact Challenge Submission

🌍 Project: Community Health Worker Diagnostic Assistant

Empowering 3.5 million CHWs to provide accurate, immediate health assessments in resource-limited settings using HAI-DEF models.

---

📋 Competition Requirements Met

---

🎯 Problem Statement

The Crisis

• 18 million global shortage of healthcare workers (WHO 2030 estimate)
• 3.5 million Community Health Workers serve 5+ billion people
• 68% of the world lacks access to diagnostic imaging expertise
• Average CHW sees 50+ patients/day with 0 diagnostic tools

Our Solution: CommunityMed AI

An offline-capable, multimodal diagnostic assistant that:

1. Analyzes chest X-rays for TB, pneumonia, and 15+ conditions
2. Processes symptom descriptions via voice in local languages
3. Provides evidence-based triage recommendations
4. Maintains doctor-in-the-loop via async review system

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    CommunityMed AI Platform                      │
├─────────────────────────────────────────────────────────────────┤
│  📱 Mobile App (Flutter)                                        │
│  ├── Offline-first design with sync                             │
│  ├── Voice input (multilingual)                                 │
│  └── Camera integration for X-rays                              │
├─────────────────────────────────────────────────────────────────┤
│  🤖 Agentic Workflow Layer                                      │
│  ├── Orchestrator Agent → Routes to specialists                 │
│  ├── Radiology Agent → MedGemma-4B-IT + MedSigLIP              │
│  ├── Clinical Reasoning Agent → MedGemma-27B-text               │
│  ├── Audio Analysis Agent → HeAR (lung sounds)                  │
│  └── Triage Agent → Risk stratification                         │
├─────────────────────────────────────────────────────────────────┤
│  🧠 HAI-DEF Model Stack                                         │
│  ├── MedGemma-4B-IT: Multimodal radiology analysis             │
│  ├── MedGemma-27B-text: Clinical reasoning & synthesis         │
│  ├── MedSigLIP: Medical image embeddings                       │
│  ├── HeAR: Lung sound analysis                                  │
│  └── Fine-tuned LoRA adapters for TB/tropical diseases         │
├─────────────────────────────────────────────────────────────────┤
│  💾 Data Layer                                                  │
│  ├── Local SQLite for offline                                  │
│  ├── Redis for session caching                                 │
│  └── PostgreSQL for sync                                       │
└─────────────────────────────────────────────────────────────────┘

---

📁 Project Structure

MedGemma/
├── README.md                           # This file
├── requirements.txt                    # Python dependencies
├── pyproject.toml                      # Modern Python package config
├── Dockerfile                          # Container deployment
├── docker-compose.yml                  # Multi-service orchestration
├── LICENSE                             # MIT License
├── .gitignore                          # Git ignore patterns
│
├── config/                             # Configuration files
│   ├── model_config.yaml               # HAI-DEF model paths and settings
│   └── training_config.yaml            # QLoRA fine-tuning hyperparameters
│
├── src/                                # Source code
│   ├── models/                         # Model implementations
│   │   ├── medgemma_loader.py          # 🌟 MedGemma 1.5/4B/27B with quantization
│   │   ├── hear_loader.py              # 🎤 HeAR audio embeddings (Novel Task)
│   │   ├── medsiglip_loader.py         # 🖼️ MedSigLIP image embeddings
│   │   └── fine_tuning.py              # QLoRA fine-tuning pipeline
│   │
│   ├── agents/                         # Agentic workflow (Prize Target!)
│   │   ├── orchestrator.py             # Multi-agent routing
│   │   ├── radiology_agent.py          # X-ray analysis (MedGemma-4B)
│   │   ├── clinical_agent.py           # Clinical reasoning (MedGemma-27B)
│   │   ├── audio_agent.py              # Cough analysis (HeAR)
│   │   └── triage_agent.py             # Risk stratification
│   │
│   ├── demo/                           # Interactive demos
│   │   └── gradio_app.py               # 🎯 Live Gradio demo app
│   │
│   ├── api/                            # FastAPI backend
│   │   ├── main.py                     # Application entry
│   │   ├── routes.py                   # REST endpoints
│   │   └── schemas.py                  # Pydantic schemas
│   │
│   └── utils/                          # Utilities
│       └── impact_calculator.py        # WHO-based impact metrics
│
├── examples/                           # Usage examples
│   └── tb_screening_demo.py            # 🏥 End-to-end TB screening
│
├── scripts/                            # Utility scripts
│   ├── benchmark.py                    # ⚡ Performance benchmarking
│   ├── train.py                        # Training script
│   └── evaluate.py                     # Evaluation script
│
├── submission/                         # Kaggle submission materials
│   ├── writeup.md                      # 3-page writeup (competition template)
│   ├── video_script.md                 # 3-min video script
│   └── impact_analysis.md              # WHO-cited impact model
│
├── tests/                              # Unit tests
│   ├── test_models.py                  # Model loading tests
│   ├── test_haidef_models.py           # HeAR/MedSigLIP tests
│   └── test_api.py                     # API endpoint tests
│
└── notebooks/                          # Jupyter notebooks
    ├── 01_data_exploration.ipynb
    ├── 02_fine_tuning.ipynb
    └── 03_evaluation.ipynb

---

🚀 Quick Start

1. Setup Environment

# Clone repository
git clone https://github.com/dihannahdi/communitymed-ai.git
cd communitymed-ai

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

2. Configure HuggingFace Access

# Login to HuggingFace (requires token with model access)
huggingface-cli login

3. Run the Demo (No GPU Required)

# Run end-to-end TB screening demo (mock mode)
python examples/tb_screening_demo.py

# Launch interactive Gradio demo
python -m src.demo.gradio_app

4. Run Benchmarks (GPU Recommended)

# Benchmark HAI-DEF models
python scripts/benchmark.py --model hear --samples 100
python scripts/benchmark.py --model medsiglip --samples 100

# Full MedGemma benchmark (requires GPU)
python scripts/benchmark.py --model medgemma-4b-it --samples 50

5. Start API Server

# Start FastAPI server
uvicorn src.api.main:app --host 0.0.0.0 --port 8000

6. Fine-tune Models (Optional)

# Download datasets
python scripts/download_datasets.py

# Fine-tune MedGemma with QLoRA
python scripts/train.py --config config/training_config.yaml

---

📊 Impact Metrics

Evidence-based methodology using WHO data - see submission/impact_analysis.md

---

🛠️ Technical Details

HAI-DEF Models Used

Fine-tuning Configuration

• Method: QLoRA (4-bit quantization)
• Rank: 16
• Alpha: 16
• Epochs: 3
• Learning Rate: 2e-4
• Batch Size: 4 (with gradient accumulation 4)

Edge Deployment

• Quantization: GPTQ 4-bit → GGUF
• Target Device: Android 10+, 6GB RAM
• Model Size: ~2GB (MedGemma-4B quantized)
• Inference Time: <2s on Snapdragon 865

---

📄 License

This project is licensed under CC BY 4.0 as required by the competition.

---

👥 Team

• [Your Name] - Lead Developer & ML Engineer
• Role: Fine-tuning, deployment, agentic workflow

---

🔗 Links

• Video Demo: [YouTube/Loom link]
• Live Demo: [HuggingFace Spaces link]
• Model: [HuggingFace Model link]
• Kaggle Writeup: [Writeup link]

---

📚 References

1. Google MedGemma Technical Report (2025)
2. WHO Community Health Worker Guidelines
3. HAI-DEF Developer Documentation
4. Kaggle MedGemma Impact Challenge Rules