README.md

---
title: Scribbled Docs Notes
emoji: 🐨
colorFrom: pink
colorTo: yellow
sdk: gradio
sdk_version: 5.36.2
app_file: app.py
pinned: false
license: mit
short_description: An app to convert doc notes to SOAP
---
# 🏥 Scribbled Docs Notes - Medical SOAP Note Generator

# 🏥 Medical OCR SOAP Generator - LIVE DEMO

## 🎯 For Competition Judges:

### **INSTANT DEMO (2 minutes):**
1. **Upload any medical image** OR **enter medical text** below
2. **Click "Generate SOAP Note"** 
3. **Wait ~60-90 seconds** for AI processing
4. **See professional SOAP note** generated by Gemma 3n

### **Sample Text to Try:**


Transform unstructured medical notes and handwritten documents into professional SOAP (Subjective, Objective, Assessment, Plan) documentation using Google's Gemma 3N model and advanced OCR technology.

## 🚀 Features

- **📸 Image OCR**: Upload PNG/JPG images of medical notes (typed or handwritten)
- **🤖 AI-Powered**: Uses Google's Gemma 3N multimodal model for intelligent SOAP generation
- **📝 Manual Input**: Enter medical notes directly via text interface
- **🔒 Privacy-First**: All processing performed locally - no data sent to external servers
- **🌐 Web Interface**: User-friendly Gradio interface with shareable links
- **📋 Professional Format**: Generates structured SOAP notes following medical standards
- **📋 Copy Ready**: Built-in copy button for easy transfer to medical records

## 🎯 What is SOAP?

SOAP notes are a standardized method for documenting medical encounters:
- **S - SUBJECTIVE**: Patient's reported symptoms and medical history
- **O - OBJECTIVE**: Observable clinical findings, vital signs, test results
- **A - ASSESSMENT**: Clinical diagnosis and medical reasoning
- **P - PLAN**: Treatment plan, medications, and follow-up instructions

## 🛠️ Installation

### Prerequisites
- Python 3.8 or higher
- CUDA-compatible GPU (optional, but recommended for faster processing)
- Hugging Face account and API token

### Quick Start

1. **Clone the repository**:
   ```bash
   git clone <repository-url>
   cd scribbled-docs-notes
   ```

2. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Set up Hugging Face authentication**:
   ```bash
   # Option 1: Environment variable
   export HF_TOKEN="your_hugging_face_token"
   
   # Option 2: Login via CLI
   huggingface-cli login
   ```

4. **Run the application**:
   ```bash
   python app.py
   ```

5. **Access the interface**:
   - Local: `http://localhost:7860`
   - Public link will be displayed in terminal when using `share=True`

## 📖 Usage

### Method 1: Upload Medical Images
1. Take a photo or scan of handwritten/typed medical notes
2. Upload PNG or JPG files through the web interface
3. The system automatically extracts text using OCR
4. Click "Generate SOAP Note" to create structured documentation

### Method 2: Manual Text Entry
1. Type or paste unstructured medical notes into the text area
2. Use the provided examples as templates
3. Generate professional SOAP documentation

### Example Input:
```
Patient John Smith, 45yo male, came in complaining of chest pain for 2 days. 
Pain is sharp, 7/10 intensity, worse with movement. Vital signs: BP 140/90, 
HR 88, Temp 98.6F. Physical exam shows tenderness over left chest wall, 
no murmurs. EKG normal. Diagnosed with costochondritis. Prescribed 
ibuprofen 600mg TID.
```

### Generated SOAP Output:
```
SUBJECTIVE:
45-year-old male presents with chief complaint of chest pain persisting 
for 2 days. Patient describes pain as sharp in quality with intensity 
rated 7/10. Pain is exacerbated by movement.

OBJECTIVE:
Vital Signs: Blood pressure 140/90 mmHg, heart rate 88 bpm, 
temperature 98.6°F
Physical Examination: Tenderness noted over left chest wall. 
Cardiovascular examination reveals no murmurs. 
Diagnostic Studies: EKG shows normal sinus rhythm.

ASSESSMENT:
Costochondritis

PLAN:
1. Medication: Ibuprofen 600mg three times daily
2. Activity: Rest as needed
3. Follow-up: Return if symptoms persist
```

## 🧠 Technical Details

### Model Architecture
- **Model**: Google Gemma 3N (3B parameters)
- **Type**: Multimodal (text, image, audio)
- **Size**: ~2.9GB
- **Languages**: 140 text + 35 multimodal languages
- **Precision**: FP16 (GPU) / FP32 (CPU)

### OCR Technology
- **Primary**: EasyOCR (optimized for handwritten text)
- **Fallback**: Tesseract OCR with medical text configuration
- **Preprocessing**: Image enhancement, noise removal, contrast optimization

### System Requirements
- **RAM**: 8GB minimum, 16GB recommended
- **Storage**: 5GB free space for model downloads
- **GPU**: Optional but recommended (NVIDIA with CUDA support)
- **CPU**: Multi-core processor recommended for CPU-only inference

## 🔧 Configuration

### Environment Variables
```bash
# Required
HF_TOKEN=your_hugging_face_token

# Optional
CUDA_VISIBLE_DEVICES=0  # GPU selection
GRADIO_SERVER_PORT=7860 # Custom port
```

### Model Configuration
The application automatically configures optimal settings based on your hardware:
- **GPU Available**: Uses CUDA with FP16 precision
- **CPU Only**: Falls back to CPU with FP32 precision
- **Memory Management**: Implements low CPU memory usage for large models

## 📊 Performance

### Processing Times (Approximate)
- **GPU (RTX 3080)**: 2-5 seconds per SOAP note
- **CPU (8-core)**: 10-30 seconds per SOAP note
- **OCR Processing**: 1-3 seconds per image

### Accuracy
- **Typed Text OCR**: 95-99% accuracy
- **Handwritten Text**: 80-95% accuracy (depends on handwriting clarity)
- **SOAP Generation**: Clinical evaluation recommended

## 🚨 Important Medical Disclaimer

**⚠️ FOR EDUCATIONAL AND RESEARCH PURPOSES ONLY**

This application is designed to assist healthcare professionals and is not intended to:
- Replace clinical judgment or medical expertise
- Provide medical diagnosis or treatment recommendations
- Be used as the sole source for patient care decisions

**Always verify AI-generated content with qualified medical professionals before clinical use.**

## 🔒 Privacy & Security

- **Local Processing**: All AI inference performed on your hardware
- **No Data Transmission**: Medical data never leaves your system
- **Temporary Storage**: Images and text processed in memory only
- **HIPAA Consideration**: Suitable for environments requiring data privacy

## 🤝 Contributing

We welcome contributions! Please follow these steps:

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

### Development Setup
```bash
# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-test.txt

# Run the simple tests first
python -m pytest tests/test_simple.py -v

# Run all real tests  
python -m pytest tests/test_real_functionality.py -v

# See what's available vs missing
python -m pytest tests/test_simple.py::test_optional_dependencies -v -s

# Run all tests with coverage
python -m pytest tests/ --cov=app -v

# Format code
black app.py
flake8 app.py
```

## 📋 Roadmap

- [ ] Support for additional medical document formats
- [ ] Multi-language SOAP note generation
- [ ] Integration with Electronic Health Records (EHR)
- [ ] Voice-to-text medical note capture
- [ ] Advanced medical terminology validation
- [ ] Batch processing capabilities
- [ ] Custom SOAP templates
- [ ] Mobile app development

## 🐛 Troubleshooting

### Common Issues

**1. Model Download Fails**
```bash
# Clear Hugging Face cache
rm -rf ~/.cache/huggingface/
# Re-authenticate
huggingface-cli login
```

**2. OCR Not Working**
```bash
# Install system dependencies (Ubuntu/Debian)
sudo apt-get install tesseract-ocr
sudo apt-get install libgl1-mesa-glx
```

**3. CUDA Out of Memory**
```bash
# Force CPU usage
export CUDA_VISIBLE_DEVICES=""
```

**4. Port Already in Use**
```bash
# Kill process on port 7860
lsof -ti:7860 | xargs kill -9
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **Google**: For the Gemma 3N model
- **Hugging Face**: For model hosting and transformers library
- **Gradio**: For the intuitive web interface framework
- **EasyOCR & Tesseract**: For optical character recognition capabilities

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/your-repo/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-repo/discussions)
- **Email**: [email protected]

---

**Made with ❤️ for the medical community**

*Empowering healthcare professionals with AI-assisted documentation*