diff --git a/README.md b/README.md index 5cede0e13..16de2a66b 100644 --- a/README.md +++ b/README.md @@ -6,20 +6,25 @@ [![CodeScene System Mastery](https://codescene.io/projects/70411/status-badges/system-mastery)](https://codescene.io/projects/70411) [![CodeScene general](https://codescene.io/images/analyzed-by-codescene-badge.svg)](https://codescene.io/projects/70411) - # SAMO Deep Learning Track + ## Production-Grade Emotion Detection System for Voice-First Journaling -> **SAMO** is an AI-powered journaling companion that transforms voice conversations into emotionally-aware insights. This repository contains the complete Deep Learning infrastructure powering real-time emotion detection and text summarization in production. +> **SAMO** is an AI-powered journaling companion that transforms voice conversations +> into emotionally-aware insights. This repository contains the complete Deep Learning +> infrastructure powering real-time emotion detection and text summarization in +> production. ## ๐ŸŽฏ Project Context & Scope -**Role**: Sole Deep Learning Engineer (originally 2-person team, now independent ownership) -**Responsibility**: End-to-end ML pipeline from research to production deployment +**Role**: Sole Deep Learning Engineer (originally 2-person team, now independent +ownership) **Responsibility**: End-to-end ML pipeline from research to production +deployment ### Architecture Overview #### Voice Processing Pipeline + ```text Voice Input โ†’ Whisper STT โ†’ DistilRoBERTa Emotion โ†’ T5 Summarization โ†’ Emotional Insights โ†“ โ†“ โ†“ โ†“ โ†“ @@ -27,6 +32,7 @@ Voice Input โ†’ Whisper STT โ†’ DistilRoBERTa Emotion โ†’ T5 Summarization โ†’ E ``` #### System Architecture +
99.5% availability** | +| Metric | Challenge | Solution | Result | +| --------------------- | ------------------ | ------------------------------------------------- | ------------------------- | +| **Model Accuracy** | Initial F1: 5.20% | Asymmetric loss + data augmentation + calibration | **45.70% F1** (+779%) | +| **Inference Speed** | PyTorch: ~300ms | ONNX optimization + quantization | **<500ms** (2.3x speedup) | +| **Model Size** | Original: 500MB | Dynamic quantization + compression | **150MB** (75% reduction) | +| **Production Uptime** | Research prototype | Docker + GCP + monitoring | **>99.5% availability** | ## ๐Ÿง  Technical Innovation ### Core ML Systems **1. Emotion Detection Pipeline** + - **Model**: Fine-tuned DistilRoBERTa (66M parameters) on GoEmotions dataset -- **Innovation**: Implemented focal loss for severe class imbalance (27 emotion categories) +- **Innovation**: Implemented focal loss for severe class imbalance (27 emotion + categories) - **Optimization**: ONNX Runtime deployment with dynamic quantization - **Performance**: 90.70% F1 score, 100-600ms inference time -**2. Text Summarization Engine** +**2. Text Summarization Engine** + - **Architecture**: T5-based transformer (60.5M parameters) - **Purpose**: Extract emotional core from journal conversations - **Integration**: Seamless pipeline with emotion detection API **3. Voice Processing Integration** + - **Model**: OpenAI Whisper for speech-to-text (<10% WER) - **Pipeline**: End-to-end voice journaling with emotional analysis - **Formats**: Multi-format audio support with real-time processing @@ -70,12 +80,14 @@ Voice Input โ†’ Whisper STT โ†’ DistilRoBERTa Emotion โ†’ T5 Summarization โ†’ E ### Production Engineering **MLOps Infrastructure** + - **Deployment**: Dockerized microservices on Google Cloud Run -- **Monitoring**: Prometheus metrics + custom model drift detection +- **Monitoring**: Prometheus metrics + custom model drift detection - **Security**: Rate limiting, input validation, comprehensive error handling - **Testing**: Complete test suite (Unit, Integration, E2E, Performance) **Performance Optimization** + - **Model Compression**: Dynamic quantization reducing inference memory by 4x - **Runtime Optimization**: ONNX conversion for production deployment - **Scalability**: Auto-scaling microservices architecture @@ -83,14 +95,15 @@ Voice Input โ†’ Whisper STT โ†’ DistilRoBERTa Emotion โ†’ T5 Summarization โ†’ E ## ๐Ÿ”ง Technical Stack -**ML Frameworks**: PyTorch, Transformers (Hugging Face), ONNX Runtime -**Model Architecture**: DistilRoBERTa, T5, Transformer-based NLP -**Production**: Docker, Kubernetes, Google Cloud Platform, Flask APIs -**MLOps**: Model monitoring, automated retraining, drift detection, CI/CD +**ML Frameworks**: PyTorch, Transformers (Hugging Face), ONNX Runtime **Model +Architecture**: DistilRoBERTa, T5, Transformer-based NLP **Production**: Docker, +Kubernetes, Google Cloud Platform, Flask APIs **MLOps**: Model monitoring, automated +retraining, drift detection, CI/CD ## ๐Ÿ“Š Live Production System ### API Endpoints + ```bash # Production emotion detection curl -X POST https://samo-emotion-api-[...].run.app/predict \ @@ -108,8 +121,9 @@ curl -X POST https://samo-emotion-api-[...].run.app/predict \ ``` ### System Health + - **Uptime**: >99.5% production availability -- **Latency**: 95th percentile under 500ms +- **Latency**: 95th percentile under 500ms - **Throughput**: 1000+ requests/minute capacity - **Error Rate**: <0.1% system errors @@ -126,7 +140,7 @@ SAMO--DL/ โ”‚ โ””โ”€โ”€ local/ # Development environment โ”œโ”€โ”€ scripts/ โ”‚ โ”œโ”€โ”€ testing/ # Comprehensive test suite -โ”‚ โ”œโ”€โ”€ deployment/ # Deployment automation +โ”‚ โ”œโ”€โ”€ deployment/ # Deployment automation โ”‚ โ””โ”€โ”€ optimization/ # Model optimization tools โ”œโ”€โ”€ docs/ โ”‚ โ”œโ”€โ”€ api/ # API documentation @@ -134,23 +148,29 @@ SAMO--DL/ โ”‚ โ””โ”€โ”€ architecture/ # System design documentation โ””โ”€โ”€ models/ โ”œโ”€โ”€ emotion_detection/ # Fine-tuned emotion models - โ”œโ”€โ”€ summarization/ # T5 summarization models + โ”œโ”€โ”€ summarization/ # T5 summarization models โ””โ”€โ”€ optimization/ # ONNX optimized models ``` ## ๐Ÿง  Training Repository -**Main Training Files**: All model training, experimentation, and optimization work is conducted in the dedicated [goemotions-deberta](https://github.com/uelkerd/goemotions-deberta) repository, located at `notebooks/goemotions-deberta/`. +**Main Training Files**: All model training, experimentation, and optimization work is +conducted in the dedicated +[goemotions-deberta](https://github.com/uelkerd/goemotions-deberta) repository, located +at `notebooks/goemotions-deberta/`. ### Repository Contents + - **๐Ÿ““ Complete training notebooks** for emotion detection model development -- **๐Ÿ”ง Performance optimization scripts** for model fine-tuning and hyperparameter tuning +- **๐Ÿ”ง Performance optimization scripts** for model fine-tuning and hyperparameter + tuning - **๐Ÿงช Comprehensive testing frameworks** for model validation and evaluation - **๐Ÿ“Š Scientific loss comparison tools** for model improvement and analysis - **๐Ÿค– DeBERTa-v3-large implementation** for multi-label emotion classification - **๐Ÿ“ˆ Model monitoring and tracking** for training progress and performance metrics ### Quick Access + ```bash # Navigate to training repository cd notebooks/goemotions-deberta/ @@ -163,17 +183,22 @@ python scripts/training/your_experiment.py ``` ### Integration with Production + The training repository is automatically initialized as a git submodule, ensuring: + - **Version Control**: Track specific commits of training code - **Easy Updates**: Pull latest training improvements when ready - **Clean Separation**: Maintain boundaries between research and production code - **CI/CD Integration**: Training code is automatically available in CI pipelines -> **Note**: This dedicated repository maintains clean separation between research/experimentation and production deployment code, while providing seamless integration through git submodules. +> **Note**: This dedicated repository maintains clean separation between +> research/experimentation and production deployment code, while providing seamless +> integration through git submodules. ## ๐Ÿ› ๏ธ Development Workflow ### Model Training (Google Colab) + ```python # Fine-tuning DistilRoBERTa for emotion detection trainer = EmotionTrainer( @@ -186,8 +211,8 @@ trainer = EmotionTrainer( trainer.train() # Achieved 90.70% F1 score ``` - ### Production Deployment + ```bash # Deploy optimized model to Google Cloud Run gcloud run deploy samo-emotion-api \ @@ -200,6 +225,7 @@ gcloud run deploy samo-emotion-api \ ``` ### Performance Monitoring + ```python # Real-time model performance tracking from prometheus_client import Counter, Histogram @@ -216,21 +242,25 @@ def predict_emotion(text): ## ๐ŸŽฏ Key Challenges Solved ### 1. **Severe Class Imbalance** (27 emotions) + - **Problem**: Standard cross-entropy loss yielding 5.20% F1 score - **Solution**: Implemented focal loss + strategic data augmentation - **Result**: 90.70% F1 score (+1,630% improvement) ### 2. **Production Latency Requirements** + - **Problem**: PyTorch inference too slow for real-time use (>1s) - **Solution**: ONNX optimization + dynamic quantization - **Result**: <500ms response time (2.3x speedup) ### 3. **Memory Efficiency for Scaling** + - **Problem**: 500MB model size limiting concurrent users - **Solution**: Model compression + efficient batching - **Result**: 75% size reduction, 4x memory efficiency ### 4. **Production Reliability** + - **Problem**: Research prototype โ†’ production system - **Solution**: Comprehensive MLOps infrastructure - **Result**: >99.5% uptime with automated monitoring @@ -238,17 +268,20 @@ def predict_emotion(text): ## ๐Ÿ“ˆ Impact & Metrics **Model Performance** + - Emotion detection accuracy: **90.70% F1 score** -- Voice transcription: **<10% Word Error Rate** +- Voice transcription: **<10% Word Error Rate** - Summarization quality: **>4.0/5.0 human evaluation** -**System Performance** +**System Performance** + - Average response time: **287ms** - 95th percentile latency: **<500ms** - Production uptime: **>99.5%** - Error rate: **<0.1%** **Engineering Impact** + - Model size optimization: **75% reduction** - Inference speedup: **2.3x faster** - Memory efficiency: **4x improvement** @@ -257,6 +290,7 @@ def predict_emotion(text): ## ๐Ÿ”ฌ Research & Experimentation ### Model Architecture Experiments + - **Baseline**: BERT-base (F1: 5.20%) - **Optimization 1**: Focal loss implementation (+15% F1) - **Optimization 2**: Data augmentation pipeline (+25% F1) @@ -264,6 +298,7 @@ def predict_emotion(text): - **Final**: DistilRoBERTa + ensemble (F1: 90.70%) ### Production Optimization Journey + - **Phase 1**: PyTorch prototype (300ms inference) - **Phase 2**: ONNX conversion (130ms inference, 2.3x speedup) - **Phase 3**: Dynamic quantization (75% size reduction) @@ -272,6 +307,7 @@ def predict_emotion(text): ## ๐Ÿš€ Getting Started ### Quick Test (Production API) + ```bash # Test emotion detection curl -X POST https://samo-emotion-api-[...].run.app/predict \ @@ -280,6 +316,21 @@ curl -X POST https://samo-emotion-api-[...].run.app/predict \ ``` ### Local Development + +#### Website Development Server + +```bash +git clone https://github.com/uelkerd/SAMO--DL.git +cd SAMO--DL/deployment/local +./start-simple.sh +# Or with custom port: PORT=8001 ./start-simple.sh +``` + +This starts a Flask development server with CORS enabled that serves the website files +for local testing against production APIs. + +#### API Development + ```bash git clone https://github.com/uelkerd/SAMO--DL.git cd SAMO--DL @@ -288,6 +339,7 @@ python deployment/local/api_server.py ``` ### Model Training + ```bash # Access main training repository (see Training Repository section above) cd notebooks/goemotions-deberta/ @@ -296,8 +348,6 @@ cd notebooks/goemotions-deberta/ # Experiment with hyperparameters and architectures ``` - - ## ๐Ÿ“… Project Roadmap
@@ -314,12 +364,14 @@ cd notebooks/goemotions-deberta/ ## ๐ŸŽฏ Future Enhancements **Model Improvements** + - [ ] Expand to 105+ fine-grained emotions - [ ] Multi-language support (German, Spanish, French) - [ ] Temporal emotion pattern detection - [ ] Cross-cultural emotion adaptation **Production Features** + - [ ] A/B testing framework for model comparison - [ ] Automated model retraining pipeline - [ ] Real-time model drift detection @@ -328,6 +380,7 @@ cd notebooks/goemotions-deberta/ ## ๐Ÿค Integration Examples **Backend Integration (Python)** + ```python import requests @@ -340,35 +393,38 @@ def analyze_emotion(text: str) -> dict: ``` **Frontend Integration (JavaScript)** + ```javascript async function detectEmotion(text) { - const response = await fetch('/api/predict', { - method: 'POST', - headers: {'Content-Type': 'application/json'}, - body: JSON.stringify({text}) - }); - return await response.json(); + const response = await fetch("/api/predict", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ text }), + }); + return await response.json(); } ``` - --- ## Support & Resources ### Documentation + - [API Documentation](docs/api/API_DOCUMENTATION.md) - [Integration Guide](docs/guides/INTEGRATION_GUIDE.md) - [Deployment Guide](docs/DEPLOYMENT_GUIDE.md) - [Architecture Overview](docs/ARCHITECTURE.md) ### Examples + - [Python Integration](examples/python_integration.py) - [JavaScript Integration](examples/javascript_integration.js) - [React Component](examples/ReactEmotionDetector.jsx) - [Vue Component](examples/VueEmotionDetector.vue) ### Testing + - [API Test Suite](scripts/testing/) - [Performance Benchmarks](scripts/testing/benchmarks.py) - [Integration Tests](scripts/testing/integration_tests.py) @@ -378,6 +434,7 @@ async function detectEmotion(text) { ## Project Success ### Achievements + - **Production Deployment**: Live API with 99.9% uptime - **Performance Optimization**: 2.3x speedup with ONNX - **Enterprise Security**: Comprehensive security features @@ -385,6 +442,7 @@ async function detectEmotion(text) { - **Documentation**: Complete guides and examples ### Impact + - **Model Performance**: 5.20% โ†’ >90% F1 score (+1,630% improvement) - **System Performance**: 2.3x faster inference - **Resource Efficiency**: 4x less memory usage diff --git a/deployment/local/requirements-simple.txt b/deployment/local/requirements-simple.txt new file mode 100644 index 000000000..c558a4af9 --- /dev/null +++ b/deployment/local/requirements-simple.txt @@ -0,0 +1,15 @@ +# Minimal dependencies for SAMO Local Development Server +# These are the only dependencies needed to run the simple web server + +# Web server framework +Flask==2.3.3 + +# CORS support for cross-origin requests +Flask-Cors==4.0.0 + +# Dependencies automatically installed with Flask: +# - Werkzeug>=2.3.7 +# - Jinja2>=3.1.2 +# - itsdangerous>=2.1.2 +# - click>=8.1.3 +# - blinker>=1.6.2 diff --git a/deployment/local/simple_server.py b/deployment/local/simple_server.py new file mode 100644 index 000000000..111267207 --- /dev/null +++ b/deployment/local/simple_server.py @@ -0,0 +1,179 @@ +#!/usr/bin/env python3 +"""Simple Web Server for Local Development +====================================== + +A lightweight Flask server that serves static website files with CORS enabled +for testing against deployed Cloud Run APIs. + +Usage: + python simple_server.py [--port PORT] + +Environment Variables: + PORT: Server port (default: 8000) + ENV: Environment mode ('prod' for production CORS, default: development) + ALLOWED_ORIGINS: Comma-separated list of allowed origins for CORS +""" + +import argparse +import os +import sys +from pathlib import Path + +try: + from flask import Flask, send_from_directory, send_file, jsonify + from flask_cors import CORS +except ImportError: + print("โŒ Missing required dependencies!") + print("Please install with: pip install -r requirements-simple.txt") + sys.exit(1) + +# Get the project root directory (two levels up from this script) +# Script is at deployment/local/simple_server.py, so we go up 2 levels +# to get to project root +PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent +WEBSITE_DIR = PROJECT_ROOT / "website" + +app = Flask(__name__) + +# Configure CORS based on environment +is_production = os.getenv("ENV", "").lower() == "prod" +allowed_origins = os.getenv("ALLOWED_ORIGINS", "") + +if is_production: + # Production: Use environment variable or default to localhost regex + if allowed_origins: + origins = [origin.strip() for origin in allowed_origins.split(",")] + else: + origins = [r"http://localhost:\d+", r"http://127\.0\.0\.1:\d+"] + + CORS(app, origins=origins, supports_credentials=True) + print("๐Ÿ”’ Production CORS: Restricted origins") +else: + # Development: Allow all origins for easier testing + CORS(app, origins="*", supports_credentials=True) + print("๐Ÿ”“ Development CORS: All origins allowed") + + +@app.route('/', defaults={'filename': 'index.html'}) +@app.route('/') +def serve_file(filename): + """Serve static files from the website directory.""" + return send_from_directory(WEBSITE_DIR, filename) + + +@app.route('/health') +def health_check(): + """Health check endpoint.""" + files_available = [] + if WEBSITE_DIR.exists(): + files_available = [f.name for f in WEBSITE_DIR.glob("*.html")] + + return jsonify({ + "status": "healthy", + "server": "SAMO Local Development Server", + "website_dir": str(WEBSITE_DIR), + "cors_mode": "production" if is_production else "development", + "files_available": files_available + }) + + +@app.errorhandler(404) +def not_found(_error): + """Custom 404 handler.""" + available_files = [] + if WEBSITE_DIR.exists(): + available_files = [f.name for f in WEBSITE_DIR.glob("*.html")] + + return jsonify({ + "error": "Not found", + "message": "The requested resource was not found on this server", + "available_files": available_files + }), 404 + + +@app.errorhandler(500) +def server_error(_error): + """Custom 500 handler.""" + return jsonify({ + "error": "Internal server error", + "message": "An unexpected error occurred" + }), 500 + + +def validate_environment(): + """Validate that the environment is set up correctly.""" + if not WEBSITE_DIR.exists(): + print(f"โŒ Website directory not found: {WEBSITE_DIR}") + print(f" Make sure you're running this script from: {PROJECT_ROOT}") + return False + + index_file = WEBSITE_DIR / "index.html" + if not index_file.exists(): + print(f"โŒ index.html not found: {index_file}") + return False + + print(f"โœ… Website directory found: {WEBSITE_DIR}") + print(f"โœ… Found {len(list(WEBSITE_DIR.glob('*.html')))} HTML files") + return True + + +def main(): + """Main entry point.""" + parser = argparse.ArgumentParser(description="SAMO Local Development Server") + parser.add_argument("--port", type=int, default=None, + help="Port to run the server on (default: 8000)") + parser.add_argument("--host", default="127.0.0.1", + help="Host to bind to (default: 127.0.0.1)") + parser.add_argument("--debug", action="store_true", + help="Enable debug mode") + + args = parser.parse_args() + + # Handle PORT environment variable with graceful error handling + if args.port is None: + port_env = os.getenv("PORT", "8000") + try: + args.port = int(port_env) + except ValueError: + print(f"โŒ Invalid PORT value: {port_env!r}. Please provide an integer.") + sys.exit(1) + + print("๐Ÿš€ SAMO Local Development Server") + print("=" * 40) + + # Validate environment + if not validate_environment(): + sys.exit(1) + + print(f"๐Ÿ“ Serving files from: {WEBSITE_DIR}") + print(f"๐ŸŒ Server URL: http://{args.host}:{args.port}") + print("๐Ÿ”— Direct links:") + print(f" โ€ข Main page: http://{args.host}:{args.port}/") + + # List available HTML files + html_files = list(WEBSITE_DIR.glob("*.html")) + for html_file in html_files: + if html_file.name != "index.html": + url = f"http://{args.host}:{args.port}/{html_file.name}" + print(f" โ€ข {html_file.stem.title()}: {url}") + + print(f"๐Ÿฅ Health check: http://{args.host}:{args.port}/health") + print("\nPress Ctrl+C to stop the server") + print("=" * 40) + + try: + app.run( + host=args.host, + port=args.port, + debug=args.debug, + threaded=True + ) + except KeyboardInterrupt: + print("\n๐Ÿ‘‹ Server stopped by user") + except Exception as e: + print(f"โŒ Server error: {e}") + sys.exit(1) + + +if __name__ == "__main__": + main() diff --git a/deployment/local/start-simple.sh b/deployment/local/start-simple.sh new file mode 100755 index 000000000..1c76a39fe --- /dev/null +++ b/deployment/local/start-simple.sh @@ -0,0 +1,101 @@ +#!/usr/bin/env bash +# Start simple local development server + +# Enable strict bash options for fail-fast behavior +set -euo pipefail +IFS=$'\n\t' + +# Change to script's directory for location independence +cd "$(dirname "$0")" + +echo "๐Ÿš€ STARTING SIMPLE LOCAL DEVELOPMENT SERVER" +echo "===========================================" + +# Check if Python 3 is available +if ! command -v python3 >/dev/null 2>&1; then + echo "โŒ Error: python3 not found in PATH" + echo "Please install Python 3 and try again" + exit 127 +fi + +echo "โœ… Python 3 found: $(python3 --version)" + +# Check if requirements file exists +if [ ! -f requirements-simple.txt ]; then + echo "โŒ Error: requirements-simple.txt not found" + echo "Expected location: $(pwd)/requirements-simple.txt" + exit 1 +fi + +echo "๐Ÿ“ฆ Installing minimal dependencies..." + +# Determine if we're in a virtual environment +if [ -z "${VIRTUAL_ENV:-}" ]; then + echo "๐Ÿ”ง Installing dependencies for user (not in virtual environment)" + USER_FLAG="--user" +else + echo "๐Ÿ”ง Installing dependencies in virtual environment: $VIRTUAL_ENV" + USER_FLAG="" +fi + +# Install dependencies +if ! python3 -m pip install $USER_FLAG -r requirements-simple.txt; then + echo "โŒ Failed to install dependencies" + echo "You may need to run: python3 -m pip install --upgrade pip" + exit 1 +fi + +echo "โœ… Dependencies installed successfully" + +# Get port from environment or use default +PORT="${PORT:-8000}" + +# Check if port is available (tries netstat, lsof, or ss; may not be universally reliable) +if command -v netstat >/dev/null 2>&1; then + if netstat -an | grep -q ":$PORT "; then + echo "โš ๏ธ Warning: Port $PORT appears to be in use" + echo "You can set a different port with: PORT=8001 $0" + fi +elif command -v lsof >/dev/null 2>&1; then + if lsof -iTCP:"$PORT" -sTCP:LISTEN -Pn | grep -q LISTEN; then + echo "โš ๏ธ Warning: Port $PORT appears to be in use" + echo "You can set a different port with: PORT=8001 $0" + fi +elif command -v ss >/dev/null 2>&1; then + if ss -ltn | grep -q ":$PORT "; then + echo "โš ๏ธ Warning: Port $PORT appears to be in use" + echo "You can set a different port with: PORT=8001 $0" + fi +else + echo "โ„น๏ธ Port availability check skipped: no suitable tool (netstat, lsof, ss) found." +fi + +echo "๐ŸŒ Starting simple development server..." +echo "๐Ÿ“ Serving website files with CORS enabled" +echo "๐Ÿ”— Server will be available at: http://localhost:${PORT}" +echo "" +echo "Available pages:" +echo " โ€ข Main page: http://localhost:${PORT}/" + +# Check for HTML files in website directory +WEBSITE_DIR="../../website" +if [ -d "$WEBSITE_DIR" ]; then + for html_file in "$WEBSITE_DIR"/*.html; do + if [ -f "$html_file" ]; then + filename=$(basename "$html_file") + if [ "$filename" != "index.html" ]; then + page_name=$(basename "$filename" .html) + echo " โ€ข ${page_name^}: http://localhost:${PORT}/${filename}" + fi + fi + done +fi + +echo " โ€ข Health check: http://localhost:${PORT}/health" +echo "" +echo "Press Ctrl+C to stop the server" +echo "===========================================" +echo "" + +# Start the server +exec python3 simple_server.py --port "${PORT}"