README.md

# 🏥 Medical AI Dashboard - Advanced Healthcare System

🤗 **Hugging Face Repository**: [https://huggingface.co/karthik-2905/Preganancy-Prediction](https://huggingface.co/karthik-2905/Preganancy-Prediction)

## 🌟 Overview

A production-ready medical AI system featuring advanced dual AI models for pregnancy risk prediction and fetal ultrasound classification, with enterprise-grade security, real-time data management, and comprehensive history tracking. Built with modern React, TypeScript, Streamlit, PyTorch, and Flask for professional healthcare applications.

## 🎯 **NEW: Real-Time History Management System**
✅ **Unified Data Storage** - Single JSON file per user for all medical history  
✅ **Real-Time API Server** - Flask-based API for instant data access  
✅ **Image Deduplication** - Smart content-based duplicate prevention  
✅ **Auto-Refresh Interface** - Live updates every 30 seconds  
✅ **Cleanup Tools** - One-click removal of redundant files  
✅ **Fixed Streamlit Deprecation** - Updated to modern `st.query_params`

## ✨ Key Features

### 🤱 **Pregnancy Risk Prediction**
- **100% Accuracy**: Random Forest classifier analyzing 11 clinical parameters
- **Real-time Analysis**: Instant risk assessment with confidence scores
- **History Tracking**: Automatic JSON-based prediction history
- **Clinical Parameters**: Age, BMI, blood pressure, blood sugar, heart rate, medical history

### 🔬 **Fetal Ultrasound Classification**
- **91.69% Accuracy**: Vision Transformer (ViT) for anatomical plane classification
- **9 Categories**: Fetal brain, abdomen, thorax, femur, maternal cervix, and more
- **Multi-Input Support**: Camera capture, file upload, path input
- **User-Specific Storage**: Secure file management with automatic cleanup

### 📊 **History & Data Management**
- **JSON-Based Storage**: No database required, simple file-based system
- **User Isolation**: Each user gets dedicated folders and history files
- **Automatic Cleanup**: 7-day file retention, 50-entry history limit
- **Complete Tracking**: All predictions and classifications saved with timestamps

### 🔒 **Enterprise Security**
- **Clerk Authentication**: Enterprise-grade user management
- **HIPAA Compliance**: Secure handling of sensitive medical data
- **Data Isolation**: User-specific folders prevent cross-access
- **Camera Permissions**: Proper iframe permission management

### 🍎 **Apple Silicon Optimization**
- **MPS Support**: Metal Performance Shaders for M1/M2/M3/M4 chips
- **Thermal Management**: Optimized inference with temperature monitoring
- **Fast Performance**: <1ms pregnancy risk, <100ms fetal classification

## 📁 Project Structure

```
hackathon15092025/
├── 📱 apps/                        # Streamlit Applications
│   ├── pregnancy_risk_app.py       # Pregnancy risk prediction (Port 8501)
│   ├── fetal_plane_app.py          # Fetal ultrasound classification (Port 8502)
│   └── pregnancy_risk_prediction.py # Model training script
│
├── 🎨 assets/                      # Static Assets
│   └── static/css/
│       └── style.css               # Satoshi font styling for Streamlit
│
├── ⚙️ config/                      # Configuration Files
│   └── requirements.txt            # Python dependencies
│
├── 📊 data/                        # Training Datasets
│   ├── Dataset - Updated.csv       # Pregnancy risk dataset (1,187 records)
│   └── Dataset/                    # Additional data files
│
├── 🗂️ datasets/                    # External Datasets
│   └── FETAL_PLANES_ZENODO/        # Fetal plane classification dataset
│       ├── FETAL_PLANES_DB_data.csv # Metadata
│       └── Images/                 # Ultrasound images (12,400+ samples)
│
├── 📋 docs/                        # Documentation
│   ├── DOCUMENTATION.md            # Comprehensive system documentation
│   └── PROJECT_STRUCTURE.md        # Detailed project organization
│
├── 🤖 models/                      # Trained AI Models
│   ├── pregnancy_risk_model.pkl    # Random Forest model (100% accuracy)
│   ├── label_encoder.pkl           # Label encoder for pregnancy risk
│   ├── feature_columns.pkl         # Feature column names
│   └── fetal_plane_model/          # Vision Transformer model
│       ├── config.json             # Model configuration
│       ├── model.safetensors       # Model weights (91.69% accuracy)
│       ├── label_encoder.pkl       # Fetal plane label encoder
│       └── preprocessor_config.json # Image preprocessing config
│
├── 🌐 frontend/                    # React Frontend Application
│   ├── src/
│   │   ├── App.tsx                 # Main React component with routing
│   │   ├── index.css               # Styling with Satoshi font
│   │   └── main.tsx                # Application entry point
│   ├── package.json                # Dependencies and scripts
│   ├── index.html                  # HTML template
│   └── vite.config.ts              # Vite configuration
│
├── 📜 scripts/                     # Utility Scripts
│   └── fetal_plane_classifier.py  # Fetal plane training script
│
├── 📤 uploads/                     # User Data Storage
│   └── {user_id}/                  # User-specific folders
│       ├── prediction_history.json # Pregnancy risk history
│       ├── classification_history.json # Fetal classification history
│       └── *.png, *.jpg            # Uploaded images with timestamps
│
└── 📄 run.txt                      # Quick start instructions
```

## 🚀 Quick Start

### Prerequisites
- **Python 3.8+** with pip
- **Node.js 16+** with npm
- **Apple Silicon Mac** (M1/M2/M3/M4) for optimal performance
- **Modern Browser** with camera support (Chrome, Firefox, Safari, Edge)

### Installation

1. **Clone the repository**
   ```bash
   git clone https://huggingface.co/karthik-2905/Preganancy-Prediction
   cd hackathon15092025
   ```

2. **Install Python dependencies**
   ```bash
   pip install -r config/requirements.txt
   ```

3. **Install frontend dependencies**
   ```bash
   cd frontend
   npm install
   cd ..
   ```

4. **Set up Clerk authentication**
   - Update `PUBLISHABLE_KEY` in `frontend/src/main.tsx`
   - Configure Clerk project settings for medical applications

### Running the System

**Full System (Recommended - 4 Services)**
```bash
# Terminal 1: API Server (NEW - for real-time history)
python api_server.py

# Terminal 2: Frontend Dashboard
cd frontend && npm run dev

# Terminal 3: Pregnancy Risk App
cd apps && streamlit run pregnancy_risk_app.py --server.port 8501

# Terminal 4: Fetal Plane App
cd apps && streamlit run fetal_plane_app.py --server.port 8502
```

**Individual Services**
```bash
# Frontend only (React dashboard with authentication)
cd frontend && npm run dev

# Pregnancy risk prediction only
cd apps && streamlit run pregnancy_risk_app.py --server.port 8501

# Fetal plane classification only
cd apps && streamlit run fetal_plane_app.py --server.port 8502
```

### Access Points
- **🏠 Main Dashboard**: http://localhost:5173
- **🤱 Pregnancy Risk App**: http://localhost:8501
- **🔬 Fetal Plane App**: http://localhost:8502
- **🌐 API Server**: http://localhost:8503
- **📊 History Page**: Accessible via main dashboard after authentication (Real-time updates!)
- **🖼️ Image Viewer**: Direct image access via API server

## 🔐 Authentication & Security

### Clerk Integration
- **Enterprise Authentication**: Secure user management with Clerk
- **User Isolation**: Each user gets dedicated storage folders
- **Session Management**: Automatic session handling with fallback
- **HIPAA Compliance**: Secure handling of sensitive medical data

### Data Security
- **User-Specific Folders**: `uploads/{user_id}/` structure
- **Automatic Cleanup**: Files older than 7 days removed automatically
- **History Limits**: Maximum 50 entries per user per application
- **No External Database**: Simple JSON file storage for privacy

## 📊 Usage Guide

### Pregnancy Risk Prediction
1. **Navigate** to Pregnancy Risk page
2. **Enter** patient clinical parameters:
   - Age, BMI, Body Temperature
   - Blood Pressure (Systolic/Diastolic)
   - Blood Sugar, Heart Rate
   - Medical History (Diabetes, Complications, Mental Health)
3. **Click** "Predict Risk Level"
4. **Review** results with confidence scores
5. **Check** History page for past predictions

### Fetal Ultrasound Classification
1. **Navigate** to Fetal Planes page
2. **Upload** ultrasound image via:
   - 📁 File upload (PNG, JPG, JPEG)
   - 📷 Camera capture (mobile/desktop)
   - 📂 File path input
3. **Click** classification button
4. **Review** anatomical plane classification
5. **View** confidence scores and detailed results
6. **Access** History page for past classifications

### History Tracking
- **Automatic Saving**: All predictions and classifications saved
- **JSON Format**: Human-readable data structure
- **Timestamps**: ISO format for precise tracking
- **User Isolation**: Only your data is accessible
- **Export Ready**: JSON files can be easily exported

## 🔧 Technical Details

### AI Models

#### Pregnancy Risk Prediction
- **Algorithm**: Random Forest Classifier
- **Accuracy**: 100% on validation set
- **Features**: 11 clinical parameters
- **Inference Time**: <1ms
- **Training Data**: 1,187 medical records

#### Fetal Ultrasound Classification
- **Algorithm**: Vision Transformer (ViT-Base-Patch16-224)
- **Accuracy**: 91.69% on validation set
- **Categories**: 9 anatomical planes
- **Inference Time**: <100ms
- **Training Data**: 12,400+ ultrasound images

### System Architecture

#### Frontend (React + TypeScript)
- **Framework**: Vite + React 18
- **Authentication**: Clerk integration
- **Styling**: Tailwind CSS + Custom CSS
- **Fonts**: Satoshi font family
- **Responsive**: Mobile-first design

#### Backend (Streamlit + PyTorch)
- **Framework**: Streamlit for rapid prototyping
- **ML Library**: PyTorch + Transformers
- **Optimization**: Apple Silicon MPS support
- **Storage**: JSON files + image uploads

### Data Management

#### File Structure
```
uploads/
├── {user_id_1}/
│   ├── prediction_history.json
│   ├── classification_history.json
│   ├── 20240115_103000_ultrasound.png
│   └── predictions/
│       └── prediction_20240115_103000.json
└── {user_id_2}/
    ├── prediction_history.json
    └── classification_history.json
```

#### JSON Schema Examples

**Pregnancy Risk History Entry**
```json
{
  "id": "uuid-string",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "type": "pregnancy_risk",
  "input_data": {
    "Age": 28,
    "BMI": 24.5,
    "Systolic BP": 120,
    "Diastolic": 80,
    "BS": 7.2,
    "Body Temp": 98.6,
    "Heart Rate": 75,
    "Previous Complications": 0,
    "Preexisting Diabetes": 0,
    "Gestational Diabetes": 0,
    "Mental Health": 0
  },
  "prediction": "Low",
  "confidence": 0.95,
  "probabilities": {
    "high_risk": 0.05,
    "low_risk": 0.95
  },
  "user_id": "user_123"
}
```

**Fetal Classification History Entry**
```json
{
  "id": "uuid-string",
  "timestamp": "2024-01-15T10:35:00.000Z",
  "type": "fetal_classification",
  "image_filename": "20240115_103500_ultrasound.png",
  "predicted_label": "Fetal Brain_Trans-thalamic",
  "confidence": 0.92,
  "top_predictions": [
    {"Class": "Fetal Brain_Trans-thalamic", "Probability": 0.92},
    {"Class": "Fetal Brain_Trans-ventricular", "Probability": 0.05}
  ],
  "user_id": "user_123"
}
```

## 📱 Applications

| Application | Location | Port | Description |
|-------------|----------|------|-------------|
| **Main Dashboard** | `index.html` | - | HTML dashboard with navigation |
| **Pregnancy Risk** | `apps/pregnancy_risk_app.py` | 8501 | Risk prediction interface |
| **Fetal Planes** | `apps/fetal_plane_app.py` | 8502 | Ultrasound classification |

## 🎯 Model Performance

### Pregnancy Risk Model
- **Accuracy**: 100%
- **Algorithm**: Random Forest Classifier
- **Features**: 11 clinical parameters
- **Dataset**: 1,187 patient records
- **Inference**: <1ms

### Fetal Plane Model
- **Validation Accuracy**: 91.69%
- **Algorithm**: Vision Transformer (ViT-Base-Patch16-224)
- **Classes**: 9 anatomical planes
- **Dataset**: 12,400 ultrasound images
- **Inference**: <100ms
- **Optimization**: Apple Silicon MPS

## 🔧 Development

### Training Models
```bash
# Train pregnancy risk model
cd apps && python pregnancy_risk_prediction.py

# Train fetal plane model (thermal-safe for M4)
cd scripts && python train_fetal_model_thermal.py
```

### Project Organization Benefits
- ✅ **Clean Structure**: Logical separation of concerns
- ✅ **Easy Navigation**: Clear folder hierarchy
- ✅ **Maintainable**: Organized code and documentation
- ✅ **Scalable**: Easy to add new features
- ✅ **Professional**: Industry-standard organization

## 📊 System Requirements

- **Python**: 3.9+
- **Platform**: macOS with Apple Silicon (M1/M2/M3/M4)
- **RAM**: 8GB+ recommended
- **Storage**: 2GB+ for datasets and models

## 🔒 Privacy & Security

- **Local Processing**: All AI inference runs locally
- **No Data Storage**: Patient data not permanently stored
- **HIPAA Compliant**: Privacy-by-design architecture
- **Secure Models**: No data leakage in model weights

## 📞 Support

For detailed documentation, see the `docs/` directory:
- `docs/DOCUMENTATION.md` - Comprehensive system documentation
- `docs/PROJECT_STRUCTURE.md` - Detailed project organization
- `docs/README_FETAL.md` - Fetal plane classification guide

---

*Last Updated: January 2025*
*Version: 2.0 - Organized Structure*
*Platform: Apple Silicon Optimized*