metadata

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

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

Clone the repository:

git clone <repository-url>
cd scribbled-docs-notes

Install dependencies:
```
pip install -r requirements.txt
```

Set up Hugging Face authentication:

# Option 1: Environment variable
export HF_TOKEN="your_hugging_face_token"

# Option 2: Login via CLI
huggingface-cli login

Run the application:
```
python app.py
```
Access the interface:
- Local: http://localhost:7860
- Public link will be displayed in terminal when using share=True

📖 Usage

Method 1: Upload Medical Images

Take a photo or scan of handwritten/typed medical notes
Upload PNG or JPG files through the web interface
The system automatically extracts text using OCR
Click "Generate SOAP Note" to create structured documentation

Method 2: Manual Text Entry

Type or paste unstructured medical notes into the text area
Use the provided examples as templates
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

# 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:

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

Development Setup

# 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

# Clear Hugging Face cache
rm -rf ~/.cache/huggingface/
# Re-authenticate
huggingface-cli login

2. OCR Not Working

# Install system dependencies (Ubuntu/Debian)
sudo apt-get install tesseract-ocr
sudo apt-get install libgl1-mesa-glx

3. CUDA Out of Memory

# Force CPU usage
export CUDA_VISIBLE_DEVICES=""

4. Port Already in Use

# Kill process on port 7860
lsof -ti:7860 | xargs kill -9

📄 License

This project is licensed under the MIT License - see the 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
Discussions: GitHub Discussions
Email: [email protected]

Made with ❤️ for the medical community

Empowering healthcare professionals with AI-assisted documentation