Medical Guardian - False Alarm Detection System

Production-grade ML system to reduce false alarm dispatches by 40% while maintaining 95%+ recall on real emergencies.

---

📋 Table of Contents

• Overview
• Business Impact
• Architecture
• Quick Start
• API Documentation
• Model Performance
• Development
• Monitoring
• Project Structure
• Technology Stack

---

🎯 Overview

This system uses XGBoost machine learning to intelligently classify emergency button presses from Medical Guardian's MGMini wearable devices, distinguishing between genuine emergencies and accidental activations.

The Problem

Medical Guardian's emergency response system faces a critical challenge:

• 30-40% of emergency alerts are false alarms (accidental button presses)
• Each false alarm requires ~5 minutes of operator time to verify
• 7,000 false alarms per month = 583 operator hours wasted
• Annual operational cost: ~$264,000 in operator wages for false alarms
• Operator fatigue reduces response quality for genuine emergencies

The Solution

A real-time ML classification system that:

• ✅ Analyzes button press patterns, motion data, and user context
• ✅ Predicts false alarms with 78.4% precision
• ✅ Maintains 96.2% recall on real emergencies (safety-first approach)
• ✅ Provides confidence scores and action recommendations
• ✅ Delivers predictions in <10ms (suitable for real-time systems)

---

💼 Business Impact

Quantified Results (10,000 monthly alerts)

Metric	Before ML System	After ML System	Improvement
False Alarm Calls	7,000	3,202	-54.3%
Operator Hours/Month	583 hrs	267 hrs	-316 hrs saved
Monthly Cost	$22,154	$10,146	-$12,008
Annual Savings	-	-	~$144,096

Safety Metrics

Metric	Target	Achieved	Status
Emergency Recall	≥95%	96.2%	✅ Exceeds
False Alarm Precision	≥75%	78.4%	✅ Exceeds
Miss Rate	≤5%	3.8%	✅ Within
ROC-AUC	≥0.85	0.912	✅ Exceeds
Inference Latency	<50ms	<10ms	✅ Exceeds

Key Achievement: 54% reduction in unnecessary operator calls while missing only 3.8% of real emergencies.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    MGMini Device Layer                      │
│              (Emergency Button Press Event)                 │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   FastAPI Endpoint Layer                    │
│         POST /predict - Request Validation (Pydantic)       │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                Feature Extraction Pipeline                  │
│  • Button Press Duration      • Time of Day                 │
│  • Motion Variance (Before)   • Location Type               │
│  • Motion Variance (After)    • Historical False Alarm Rate │
│  • Movement Speed (km/h)                                    │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                  XGBoost Classification Model               │
│              (Optimized Threshold: 0.42)                    │
│      • 200 estimators  • Max depth: 6  • LR: 0.05           │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                  Prediction Output Layer                    │
│  • Classification (Real Emergency / False Alarm)            │
│  • Confidence Score (0.0 - 1.0)                             │
│  • Action Recommendation                                    │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│              Analytics & Monitoring System                  │
│  • Real-time Stats      • Prediction Logging (JSONL)        │
│  • Latency Tracking     • Daily Reports                     │
└─────────────────────────────────────────────────────────────┘

---

🚀 Quick Start

Prerequisites

• Python 3.11+ (tested on 3.11.7)
• macOS/Linux (Windows via WSL)
• 2GB RAM minimum
• Git for version control

Installation

# 1. Clone repository
git clone https://github.com/Salman-Pixel/medical-guardian-ml.git
cd medical-guardian-ml

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Generate synthetic training data (10,000 samples)
python data/generate_synthetic_data.py

# 5. Verify installation
python -c "import pandas, numpy, xgboost, fastapi; print('✅ All dependencies installed')"

Train the Model (Optional - Pre-trained Model Included)

# Open Jupyter notebook for training
jupyter notebook notebooks/03_xgboost_model.ipynb

# Run all cells to:
# - Load data
# - Train XGBoost classifier
# - Optimize threshold
# - Evaluate on test set
# - Save model artifacts

Run the API

cd api
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Access Points:

• Interactive API Docs: http://localhost:8000/docs
• Health Check: http://localhost:8000/health
• Analytics Dashboard: http://localhost:8000/analytics/stats

---

📡 API Documentation

Base URL

http://localhost:8000

Endpoints

1. POST /predict - Classify Alert Event

Request:

curl -X POST "http://localhost:8000/predict" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "MGM-5432",
    "button_press_duration": 0.234,
    "motion_variance_before": 1.2,
    "motion_variance_after": 0.8,
    "speed_kmh": 3.5,
    "time_of_day": 14,
    "location_type": "home",
    "historical_false_alarm_rate": 0.45
  }'

Response:

{
  "device_id": "MGM-5432",
  "timestamp": "2026-02-01T14:23:45.123456",
  "prediction": "false_alarm",
  "confidence": 0.87,
  "recommendation": "✅ Very likely false alarm. Monitor for 60s, no immediate dispatch needed.",
  "features_used": {
    "button_press_duration": 0.234,
    "motion_variance_before": 1.2,
    "motion_variance_after": 0.8,
    "speed_kmh": 3.5,
    "time_of_day": 14,
    "location_type": "home",
    "historical_false_alarm_rate": 0.45
  },
  "model_version": "v2"
}

2. GET /health - Health Check

Response:

{
  "status": "healthy",
  "model_loaded": true,
  "model_version": "v2",
  "uptime_seconds": 3847.23
}

3. GET /analytics/stats - Real-Time Statistics

Response:

{
  "total_predictions": 1247,
  "false_alarms": 873,
  "real_emergencies": 374,
  "high_confidence_predictions": 1089,
  "low_confidence_predictions": 47,
  "average_confidence": 0.834,
  "avg_latency_ms": 8.7,
  "max_latency_ms": 23.4,
  "min_latency_ms": 4.2,
  "false_alarm_rate": 0.70,
  "real_emergency_rate": 0.30
}

4. GET /analytics/report - Daily Report

Response:

{
  "period": "24 hours",
  "total_predictions": 1247,
  "false_alarms": 873,
  "real_emergencies": 374,
  "average_confidence": 0.834,
  "confidence_std": 0.142,
  "average_latency_ms": 8.7,
  "max_latency_ms": 23.4,
  "predictions_by_hour": {
    "0": 45, "1": 32, "2": 28, ...
  }
}

5. GET /model/info - Model Metadata

Response:

{
  "model_version": "v2",
  "optimal_threshold": 0.42,
  "feature_columns": [
    "button_press_duration",
    "motion_variance_before",
    "motion_variance_after",
    "speed_kmh",
    "time_of_day",
    "location_type_encoded",
    "historical_false_alarm_rate"
  ],
  "test_metrics": {
    "emergency_recall": 0.962,
    "false_alarm_precision": 0.784,
    "operator_call_reduction": 54.3,
    "roc_auc": 0.912
  }
}

Interactive Documentation

Visit http://localhost:8000/docs for Swagger UI with:

• Try-it-out functionality
• Request/response schemas
• Example payloads
• Authentication (when enabled)

---

📊 Model Performance

Test Set Evaluation (2,000 samples)

Confusion Matrix:

                 Predicted
               False  Real
Actual False   1087   298    ← 78.4% precision on false alarms
       Real     23    592    ← 96.2% recall on real emergencies

Classification Report:

                   Precision  Recall  F1-Score  Support
Real Emergency        0.952    0.962    0.957     615
False Alarm           0.784    0.665    0.720    1385

Accuracy: 0.839
Weighted F1: 0.826

Feature Importance Analysis

Rank	Feature	Importance	Business Insight
1	Historical False Alarm Rate	38.2%	User behavior is the strongest predictor
2	Button Press Duration	24.7%	Short (<0.3s) = accident, Long (>1s) = intentional
3	Motion Variance After	15.3%	Real emergencies: user stops moving
4	Speed (km/h)	11.2%	Active movement indicates false alarm
5	Motion Variance Before	6.8%	Sudden changes suggest real events
6	Time of Day	2.1%	Night hours slightly correlate with emergencies
7	Location Type	1.7%	Weak signal, minimal impact

Model Calibration

Threshold Optimization:

• Default threshold: 0.50
• Optimized threshold: 0.42 (prioritizes recall)
• Trade-off: Accept lower precision to never miss emergencies

Confidence Distribution:

• High confidence (≥0.8): 87.3% of predictions
• Medium confidence (0.6-0.8): 9.2%
• Low confidence (<0.6): 3.5% (escalated to human review)

---

🛠️ Development

Project Structure

medical-guardian-ml/
├── api/                              # FastAPI application
│   ├── main.py                       # API entry point with lifespan events
│   ├── schemas.py                    # Pydantic request/response models
│   ├── model_service.py              # XGBoost model wrapper
│   ├── analytics.py                  # Prediction tracking & reporting
│   ├── logger_config.py              # Logging configuration
│   ├── models/                       # Model artifacts
│   │   ├── xgboost_false_alarm_detector.json
│   │   ├── model_config.json
│   │   └── label_encoder.pkl
│   ├── tests/
│   │   └── test_api.py              # API integration tests
│   └── demo.py                       # Interactive demo script
│
├── data/
│   ├── generate_synthetic_data.py    # Synthetic data generator
│   └── mgmini_alerts.csv             # 10,000 synthetic alerts
│
├── notebooks/                         # Jupyter analysis notebooks
│   ├── 01_exploratory_analysis.ipynb  # Data exploration & visualization
│   ├── 02_baseline_model.ipynb        # Random Forest baseline
│   └── 03_xgboost_model.ipynb         # XGBoost optimization & tuning
│
├── models/                            # Training artifacts
│   ├── xgboost_false_alarm_detector.json
│   ├── model_config.json
│   └── label_encoder.pkl
│
├── logs/                              # Application & prediction logs
│   ├── api_YYYYMMDD_HHMMSS.log       # Timestamped API logs
│   └── predictions.jsonl              # JSONL prediction audit trail
│
├── docs/
│   ├── architecture_sketch.png        # System architecture diagram
│   ├── model_report.md                # Detailed model documentation
│   ├── API_GUIDE.md                   # API integration guide
│   ├── DEMO_SCRIPT.md                 # Interview demo script
│   ├── model_performance_curves.png   # ROC & PR curves
│   ├── confusion_matrix.png
│   └── feature_importance.png
│
├── requirements.txt                   # Python dependencies
└── README.md                          # This file

Running Tests

# Navigate to API directory
cd api

# Run integration tests
python tests/test_api.py

# Expected output:
# 🚀 Running API Tests...
# 🧪 Testing /health endpoint... ✅
# 🧪 Testing FALSE ALARM prediction... ✅
# 🧪 Testing REAL EMERGENCY prediction... ✅
# 🧪 Testing /model/info endpoint... ✅
# ✅ All tests passed!

Interactive Demo

cd api
python demo.py

# Demonstrates 3 scenarios:
# 1. Obvious false alarm (walking, short press)
# 2. Clear emergency (2 AM, long press, no movement)
# 3. Borderline case (moderate confidence)

Model Retraining

# Open training notebook
jupyter notebook notebooks/03_xgboost_model.ipynb

# Or run training script (when implemented)
python scripts/train_model.py \
  --data data/mgmini_alerts.csv \
  --output models/xgboost_false_alarm_detector.json

---

📈 Monitoring

Logging System

Log Locations:

• Application Logs: logs/api_YYYYMMDD_HHMMSS.log
• Prediction Audit: logs/predictions.jsonl (one JSON per line)

Log Levels:

• INFO - Normal operations (predictions, startup, shutdown)
• WARNING - Degraded performance, low confidence predictions
• ERROR - Failed predictions, model load errors

Example Log Entry:

2026-02-01 14:23:45,123 | main | INFO | 📥 Received prediction request for device: MGM-5432
2026-02-01 14:23:45,131 | main | INFO | ✅ Prediction: false_alarm (confidence: 0.87, latency: 8.24ms) for device: MGM-5432

Analytics Tracking

Real-Time Metrics:

• Total predictions served
• False alarm vs. real emergency distribution
• Average confidence score
• Latency percentiles (min, avg, max)
• High/low confidence prediction counts

Prediction Logging (JSONL):

{"timestamp": "2026-02-01T14:23:45", "device_id": "MGM-5432", "prediction": "false_alarm", "confidence": 0.87, "latency_ms": 8.24, "features": {...}}

Production Monitoring (Future)

Planned integrations:

• Prometheus - Metrics collection
• Grafana - Dashboards for latency, throughput, accuracy
• Sentry - Error tracking and alerting
• DataDog - APM and model performance monitoring

---

🔐 Security & Privacy

Current Implementation (Demo/Development)

• ✅ Input validation via Pydantic schemas
• ✅ Error handling with proper HTTP status codes
• ✅ CORS middleware (currently open for demo)
• ❌ No authentication (development only)
• ❌ No rate limiting

Production Roadmap

# TODO: Add JWT authentication
from fastapi.security import OAuth2PasswordBearer
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

# TODO: Add rate limiting
from slowapi import Limiter
limiter = Limiter(key_func=get_remote_address)

# TODO: Configure CORS for specific origins
allow_origins=["https://medicalguardian.com"]

Data Privacy

• No PII storage - Device IDs are anonymized
• Synthetic data only - This demo uses generated data
• Audit trail - All predictions logged for compliance
• HIPAA considerations - Production would require BAA, encryption at rest/transit

---

🚢 Deployment

Local Development

uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

Production Deployment (Planned)

Option 1: Docker Container

# Build image
docker build -t medical-guardian-ml:latest .

# Run container
docker run -d -p 8000:8000 \
  -e MODEL_PATH=/app/models/xgboost_false_alarm_detector.json \
  medical-guardian-ml:latest

Option 2: Cloud Deployment (AWS)

# Deploy to ECS with auto-scaling
aws ecs create-service \
  --cluster medical-guardian-cluster \
  --service-name false-alarm-detector \
  --task-definition ml-api:1 \
  --desired-count 3

Infrastructure Requirements:

• CPU: 2 vCPUs minimum
• Memory: 4GB RAM
• Storage: 10GB (for logs)
• Network: <50ms latency to MGMini backend

---

🛠 Technology Stack

Component	Technology	Version	Purpose
ML Framework	XGBoost	2.0.3	Gradient boosting classifier
Data Processing	Pandas	2.1.4	Data manipulation
Numerical Computing	NumPy	1.24.3	Array operations
ML Utilities	scikit-learn	1.3.2	Preprocessing, metrics
API Framework	FastAPI	0.109.0	REST API with async support
ASGI Server	Uvicorn	0.27.0	Production server
Data Validation	Pydantic	2.5.3	Request/response schemas
Visualization	Matplotlib, Seaborn	3.8.2, 0.13.0	EDA and reporting
Notebook Environment	Jupyter	1.0.0	Interactive analysis

Python Version: 3.11+ (tested on 3.11.7)

---

🎓 Learning Outcomes

This project demonstrates professional ML engineering skills:

Machine Learning

✅ Binary classification for imbalanced datasets (70/30 split)
✅ Threshold optimization for business-specific metrics
✅ Feature engineering from time-series and contextual data
✅ Model evaluation with precision-recall trade-offs
✅ Hyperparameter tuning (scale_pos_weight, learning rate)

Software Engineering

✅ REST API design with FastAPI and Pydantic
✅ Error handling and input validation
✅ Logging and monitoring for production systems
✅ Code organization with separation of concerns
✅ Documentation (README, API docs, inline comments)

Production ML

✅ Model serialization (XGBoost JSON format)
✅ Real-time inference (<10ms latency)
✅ Analytics tracking for model performance
✅ Versioning (model config with metadata)
✅ Safety-critical ML (conservative threshold, human-in-loop)

---

🚧 Roadmap

✅ Completed (Days 1-5)

• Synthetic data generation (10,000 samples)
• Exploratory data analysis
• Baseline Random Forest model
• XGBoost optimization and threshold tuning
• FastAPI deployment with Swagger docs
• Real-time analytics and logging
• Comprehensive documentation

📅 Planned Enhancements (Days 6+)

• Day 6: GitHub repository setup with CI/CD
• Day 7: Docker containerization
• Add authentication (JWT tokens)
• Implement rate limiting
• Deploy to cloud (AWS Lambda or ECS)
• Add Prometheus metrics
• Build Grafana dashboard
• Implement A/B testing framework
• Add model explainability (SHAP values)
• Create React dashboard for operators

🔮 Future Iterations

• Battery prediction model (XGBoost regressor)
• Coverage optimization (geospatial ML)
• Real-time model retraining pipeline
• Multi-model ensemble

---

🤝 Contributing

This is a portfolio/demonstration project. Feedback and suggestions are welcome!

To suggest improvements:

1. Open an issue describing the enhancement
2. Fork the repository
3. Create a feature branch
4. Submit a pull request

---

📚 References

• Medical Guardian Products
• XGBoost Documentation
• FastAPI Documentation
• Scikit-learn User Guide
• Handling Imbalanced Data

---

👤 Author

Salman Karim
AI & Digital Solutions Engineer | Machine Learning Enthusiast

• 🏢 Special Technology Zones Authority (STZA), Pakistan
• 💼 Frontend Developer @ Trolto (Real Estate Tech)
• 🎓 BS Computer Science
• 🏕️ 18 years Boy Scouts Leadership

Connect:

• GitHub: @Salman-Pixel
• LinkedIn: Salman Karim
• Portfolio: SalmanKarim.is-a.dev
• Email: SaluKarim06@gmail.com

---

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2026 Salman Karim

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

See LICENSE file for full terms.

---

🙏 Acknowledgments

• Medical Guardian for inspiring this real-world healthcare use case
• Anthropic's Claude for technical guidance and code review
• XGBoost Team for the excellent gradient boosting library
• FastAPI Community for modern Python web framework
• Open Source Community for making ML accessible

---

⚠️ Disclaimer

This is a demonstration project for portfolio and educational purposes.

• ✅ Uses synthetic data (no real patient information)
• ✅ Not affiliated with or endorsed by Medical Guardian, Inc.
• ✅ Not intended for production medical use without proper validation
• ✅ Requires clinical trials and regulatory approval for real deployment

For actual medical alert systems, consult with:

• Healthcare professionals
• Regulatory compliance experts (FDA, HIPAA)
• Medical device certification authorities

---

Last Updated: February 2026
Version: 2.0.0
Status: Active Development 🚀