upload 32 files for the ml

Dockerfile.hf

@@ -0,0 +1,35 @@
+# Dockerfile for Hugging Face Spaces
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1
+WORKDIR /app
+
+# System dependencies for opencv and runtime model download
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libgl1 \
+    libglib2.0-0 \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements
+COPY requirements.txt /app/requirements.txt
+
+# Upgrade pip
+RUN python -m pip install --upgrade pip setuptools wheel
+
+# Install requirements
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy app code
+COPY . /app/
+
+# Make entrypoint executable
+RUN chmod +x /app/scripts/entrypoint.sh
+
+# Hugging Face Spaces uses port 7860
+EXPOSE 7860
+
+# Use entrypoint script
+ENTRYPOINT ["/app/scripts/entrypoint.sh"]
+

app/__init__.py

@@ -0,0 +1,762 @@
+# app/__init__.py
+import os
+import datetime
+import csv
+import traceback
+import logging
+
+from flask import Flask, request, jsonify
+from flask_cors import CORS
+from werkzeug.utils import secure_filename
+from werkzeug.exceptions import RequestEntityTooLarge
+
+
+# ----------------------------
+# Module-level config (deterministic)
+# ----------------------------
+PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+TMP_DIR_DEFAULT = os.path.join(PROJECT_ROOT, "tmp")
+IMAGES_DIR_DEFAULT = os.path.join(PROJECT_ROOT, "images")
+LOG_CSV = os.path.join(PROJECT_ROOT, "predictions_log.csv")
+DB_PATH = os.path.join(PROJECT_ROOT, "predictions.db")
+
+# App-level defaults (can be overridden via app.config)
+DEFAULTS = {
+    "MIN_CONFIDENCE": 0.18,  # Lowered to 0.18 for ambiguous cases (was 0.20, originally 0.5)
+    "MAX_FILE_SIZE": 5 * 1024 * 1024,  # 5 MB
+    "TMP_DIR": TMP_DIR_DEFAULT,
+    "IMAGES_DIR": IMAGES_DIR_DEFAULT,
+    "ALLOWED_EXT": (".jpg", ".jpeg", ".png"),
+    "CORS_ORIGINS": "*",  # Can be overridden for production
+}
+
+# Ensure directories exist
+os.makedirs(DEFAULTS["TMP_DIR"], exist_ok=True)
+os.makedirs(DEFAULTS["IMAGES_DIR"], exist_ok=True)
+
+# Ensure CSV header exists (helpful for older logs)
+if not os.path.exists(LOG_CSV):
+    try:
+        with open(LOG_CSV, "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+            writer.writerow(["timestamp", "filename", "emotion", "confidence"])
+    except Exception:
+        # Non-fatal — keep module import light.
+        pass
+
+
+# ----------------------------
+# Factory
+# ----------------------------
+def create_app(config: dict | None = None):
+    """
+    Create and return the Flask application.
+    Heavy imports (model loading, db init) are performed inside this factory
+    so importing modules from scripts/tests doesn't trigger expensive work.
+    """
+    # Merge defaults with provided config
+    cfg = DEFAULTS.copy()
+    if config:
+        cfg.update(config)
+
+    app = Flask(__name__)
+    
+    # CORS configuration - allow config override
+    cors_origins = cfg.get("CORS_ORIGINS", DEFAULTS["CORS_ORIGINS"])
+    if cors_origins == "*":
+        CORS(app, resources={r"/*": {"origins": "*"}})
+    else:
+        # Allow list of origins
+        origins_list = cors_origins.split(",") if isinstance(cors_origins, str) else cors_origins
+        CORS(app, resources={r"/*": {"origins": origins_list}})
+
+    # ---------- file logging setup (after app created) ----------
+    LOG_DIR = os.path.join(PROJECT_ROOT, "logs")
+    try:
+        os.makedirs(LOG_DIR, exist_ok=True)
+    except Exception:
+        # If logs dir cannot be created, continue; app.logger will still work to stdout
+        pass
+
+    log_path = os.path.join(LOG_DIR, "app.log")
+    try:
+        file_handler = logging.FileHandler(log_path)
+        file_handler.setLevel(logging.INFO)  # change to ERROR if you prefer
+        formatter = logging.Formatter("%(asctime)s [%(levelname)s] %(module)s: %(message)s")
+        file_handler.setFormatter(formatter)
+
+        # avoid adding duplicate handlers when reloading
+        abs_log_path = os.path.abspath(log_path)
+        if not any(
+            isinstance(h, logging.FileHandler) and getattr(h, "baseFilename", None) == abs_log_path
+            for h in app.logger.handlers
+        ):
+            app.logger.addHandler(file_handler)
+            # set app logger level (don't lower if already configured higher)
+            app.logger.setLevel(logging.INFO)
+    except Exception:
+        # If logging can't be configured, keep going — logger will fallback to default handlers.
+        app.logger.exception("Failed to configure file logging")
+
+    # Apply config to app
+    app.config["MAX_CONTENT_LENGTH"] = cfg["MAX_FILE_SIZE"]
+    app.config["TMP_DIR"] = cfg["TMP_DIR"]
+    app.config["IMAGES_DIR"] = cfg.get("IMAGES_DIR", DEFAULTS["IMAGES_DIR"])
+    app.config["ALLOWED_EXT"] = cfg["ALLOWED_EXT"]
+    app.config["MIN_CONFIDENCE"] = cfg["MIN_CONFIDENCE"]
+    
+
+    # Ensure tmp directory exists (again, per app)
+    os.makedirs(app.config["TMP_DIR"], exist_ok=True)
+
+    # Local (deferred) imports — avoid import-time side effects
+    from .model_loader import load_emotion_model
+    from .db_logger import init_db, log_prediction, get_metrics, tail_rows, get_total_count, delete_prediction
+    from .utils import preprocess_face
+    from .image_storage import save_image, get_image_path, ensure_images_dir
+    from .validators import validate_image_file, validate_pagination_params, validate_confidence_range
+    from .rate_limiter import detect_limiter, logs_limiter, images_limiter, get_client_identifier
+
+    # Initialize DB
+    try:
+        init_db(DB_PATH)
+        app.logger.info("Initialized SQLite DB at %s", DB_PATH)
+    except Exception:
+        app.logger.exception("Failed to initialize DB at startup")
+
+    # Load model & labels. Keep these local to the factory (no module-level side effects).
+    # We'll load models on-demand based on request parameter
+    base_model = None
+    base_labels = None
+    base_model_version = "unknown"
+    base_model_type = "unknown"
+    finetuned_model = None
+    finetuned_labels = None
+    finetuned_model_version = "unknown"
+    finetuned_model_type = "unknown"
+    
+    # Load base model by default
+    try:
+        # load_emotion_model returns (model, labels, version, model_type)
+        res = load_emotion_model(force_model='base')
+        if isinstance(res, tuple) and len(res) == 4:
+            base_model, base_labels, base_model_version, base_model_type = res
+        elif isinstance(res, tuple) and len(res) == 3:
+            base_model, base_labels, base_model_version = res
+            base_model_type = "keras"  # Default for old format
+        elif isinstance(res, tuple) and len(res) == 2:
+            base_model, base_labels = res
+            base_model_type = "keras"  # Default for old format
+        else:
+            # Unexpected return shape - try to be permissive
+            try:
+                base_model = res
+                base_labels = None
+                base_model_type = "keras"
+            except Exception:
+                base_model = None
+                base_labels = None
+                base_model_type = "unknown"
+        app.logger.info("Base model loaded: %s (version=%s, type=%s)", bool(base_model), base_model_version, base_model_type)
+        print(f"[APP] Base model loaded: type={base_model_type}, version={base_model_version}, labels={len(base_labels) if base_labels else 0}")
+    except Exception as exc:
+        app.logger.exception("Base model failed to load at startup: %s", exc)
+        base_model = None
+        base_labels = None
+        base_model_version = "failed"
+        base_model_type = "unknown"
+    
+    # Try to load fine-tuned model
+    try:
+        res = load_emotion_model(force_model='fine-tuned')
+        if isinstance(res, tuple) and len(res) == 4:
+            finetuned_model, finetuned_labels, finetuned_model_version, finetuned_model_type = res
+        elif isinstance(res, tuple) and len(res) == 3:
+            finetuned_model, finetuned_labels, finetuned_model_version = res
+            finetuned_model_type = "keras"
+        elif isinstance(res, tuple) and len(res) == 2:
+            finetuned_model, finetuned_labels = res
+            finetuned_model_type = "keras"
+        app.logger.info("Asripa model loaded: %s (version=%s, type=%s)", bool(finetuned_model), finetuned_model_version, finetuned_model_type)
+        print(f"[APP] Asripa model loaded: type={finetuned_model_type}, version={finetuned_model_version}")
+    except Exception as exc:
+        app.logger.warning("Asripa model not available: %s", exc)
+        finetuned_model = None
+        finetuned_labels = None
+        finetuned_model_version = "not-available"
+        finetuned_model_type = "unknown"
+
+    # Store in app.config - default to base model
+    app.config["BASE_MODEL"] = base_model
+    app.config["BASE_LABELS"] = base_labels
+    app.config["BASE_MODEL_VERSION"] = base_model_version
+    app.config["BASE_MODEL_TYPE"] = base_model_type
+    app.config["FINETUNED_MODEL"] = finetuned_model
+    app.config["FINETUNED_LABELS"] = finetuned_labels
+    app.config["FINETUNED_MODEL_VERSION"] = finetuned_model_version
+    app.config["FINETUNED_MODEL_TYPE"] = finetuned_model_type
+    # Default to base model
+    app.config["MODEL"] = base_model
+    app.config["LABELS"] = base_labels
+    app.config["MODEL_VERSION"] = base_model_version
+    app.config["MODEL_TYPE"] = base_model_type
+
+    # ----------------------------
+    # Error handlers (import before routes to ensure proper handling)
+    # ----------------------------
+    from .error_handlers import register_error_handlers, APIError, ValidationError, NotFoundError, ServiceUnavailableError
+    
+    register_error_handlers(app)
+    
+    # Make these available in route scope
+    globals()['APIError'] = APIError
+    globals()['ValidationError'] = ValidationError
+    globals()['NotFoundError'] = NotFoundError
+    globals()['ServiceUnavailableError'] = ServiceUnavailableError
+    
+    @app.errorhandler(RequestEntityTooLarge)
+    def handle_large_file(e):
+        return jsonify({"error": "File too large", "max_size_mb": app.config.get("MAX_CONTENT_LENGTH", 5 * 1024 * 1024) / (1024 * 1024)}), 413
+
+    # ----------------------------
+    # Routes
+    # ----------------------------
+    @app.route("/")
+    def index():
+        return jsonify({"status": "ok", "message": "Flask backend running"}), 200
+
+    @app.route("/health", methods=["GET"])
+    def health():
+        """
+        Lightweight health check endpoint.
+        Optimized for speed - minimal checks to avoid timeouts.
+        """
+        try:
+            # Quick check - don't do expensive operations
+            model_loaded = bool(app.config.get("MODEL"))
+            model_type = app.config.get("MODEL_TYPE", "unknown")
+            model_version = app.config.get("MODEL_VERSION", "unknown")
+            
+            # Get labels count quickly
+            labels_obj = app.config.get("LABELS")
+            labels_count = len(labels_obj) if labels_obj and hasattr(labels_obj, "__len__") else 0
+            
+            return jsonify(
+                {
+                    "ok": True,
+                    "model_loaded": model_loaded,
+                    "model_type": model_type,
+                    "model_version": model_version,
+                    "labels_count": labels_count,
+                }
+            ), 200
+        except Exception as e:
+            # Even if there's an error, return 200 to indicate service is running
+            # This prevents false "offline" status
+            app.logger.warning(f"Health check error (non-fatal): {e}")
+            return jsonify(
+                {
+                    "ok": True,
+                    "model_loaded": False,
+                    "model_type": "unknown",
+                    "model_version": "unknown",
+                    "labels_count": 0,
+                    "warning": "Health check had minor issues but service is running",
+                }
+            ), 200
+
+    @app.route("/metrics")
+    def metrics():
+        try:
+            m = get_metrics(DB_PATH)
+            recent = tail_rows(DB_PATH, limit=10)
+            return jsonify({"ok": True, "metrics": m, "recent": recent}), 200
+        except Exception as exc:
+            app.logger.exception("Failed to fetch metrics")
+            return jsonify({"error": "Failed to fetch metrics", "details": str(exc)}), 500
+
+    @app.route("/logs", methods=["GET"])
+    def logs():
+        """
+        GET /logs?limit=20&offset=0&emotion=happy&min_confidence=0.5&max_confidence=1.0&date_from=2024-01-01&date_to=2024-12-31
+        
+        Returns paginated and filtered logs.
+        """
+        # Rate limiting
+        client_id = get_client_identifier(request)
+        is_allowed, remaining = logs_limiter.is_allowed(client_id)
+        if not is_allowed:
+            return jsonify({
+                "error": "Rate limit exceeded",
+                "detail": f"Maximum {logs_limiter.max_requests} requests per {logs_limiter.window_seconds} seconds",
+                "retry_after": logs_limiter.window_seconds,
+            }), 429
+        
+        try:
+            # Validate pagination
+            limit, offset, pagination_error = validate_pagination_params(
+                request.args.get("limit"),
+                request.args.get("offset"),
+            )
+            if pagination_error:
+                return jsonify({"error": pagination_error}), 400
+            
+            # Validate confidence range
+            min_confidence, max_confidence, confidence_error = validate_confidence_range(
+                request.args.get("min_confidence"),
+                request.args.get("max_confidence"),
+            )
+            if confidence_error:
+                return jsonify({"error": confidence_error}), 400
+            
+            # Filters
+            emotion_filter = request.args.get("emotion", None)
+            if emotion_filter and emotion_filter.strip():
+                emotion_filter = emotion_filter.strip()
+            else:
+                emotion_filter = None
+            
+            date_from = request.args.get("date_from", None)
+            date_to = request.args.get("date_to", None)
+            
+            # Fetch data
+            rows = tail_rows(
+                DB_PATH,
+                limit=limit,
+                offset=offset,
+                emotion_filter=emotion_filter,
+                min_confidence=min_confidence,
+                max_confidence=max_confidence,
+                date_from=date_from,
+                date_to=date_to,
+            )
+            
+            total = get_total_count(
+                DB_PATH,
+                emotion_filter=emotion_filter,
+                min_confidence=min_confidence,
+                max_confidence=max_confidence,
+                date_from=date_from,
+                date_to=date_to,
+            )
+            
+            # Convert to list of dicts
+            result = []
+            for r in rows:
+                if len(r) == 6:
+                    _id, ts, filename, image_path, emotion, confidence = r
+                    record = {
+                        "id": _id,
+                        "ts": ts,
+                        "filename": filename,
+                        "image_path": image_path or filename,  # Fallback to filename if no image_path
+                        "emotion": emotion,
+                        "confidence": confidence,
+                    }
+                elif len(r) == 5:
+                    _id, ts, filename, emotion, confidence = r
+                    record = {
+                        "id": _id,
+                        "ts": ts,
+                        "filename": filename,
+                        "image_path": filename,  # Fallback
+                        "emotion": emotion,
+                        "confidence": confidence,
+                    }
+                elif len(r) == 4:
+                    ts, filename, emotion, confidence = r
+                    record = {
+                        "ts": ts,
+                        "filename": filename,
+                        "image_path": filename,  # Fallback
+                        "emotion": emotion,
+                        "confidence": confidence,
+                    }
+                else:
+                    record = {"row": r}
+                result.append(record)
+            
+            return jsonify({
+                "ok": True,
+                "logs": result,
+                "pagination": {
+                    "total": total,
+                    "limit": limit,
+                    "offset": offset,
+                    "has_more": (offset + limit) < total,
+                },
+            }), 200
+        except Exception as exc:
+            app.logger.exception("Failed to fetch logs")
+            return jsonify({"error": "Failed to fetch logs", "detail": str(exc)}), 500
+
+    @app.route("/logs/<int:prediction_id>", methods=["DELETE"])
+    def delete_log(prediction_id: int):
+        """
+        DELETE /logs/<id>
+        
+        Delete a prediction by ID.
+        """
+        # Rate limiting
+        client_id = get_client_identifier(request)
+        is_allowed, remaining = logs_limiter.is_allowed(client_id)
+        if not is_allowed:
+            return jsonify({
+                "error": "Rate limit exceeded",
+                "detail": f"Maximum {logs_limiter.max_requests} requests per {logs_limiter.window_seconds} seconds",
+                "retry_after": logs_limiter.window_seconds,
+            }), 429
+        
+        try:
+            # Delete from database
+            deleted = delete_prediction(DB_PATH, prediction_id)
+            
+            if not deleted:
+                return jsonify({"error": "Prediction not found"}), 404
+            
+            # Optionally delete associated image file
+            from .image_storage import delete_image
+            # Note: We'd need to fetch the image_path first, but for now just delete from DB
+            # You can enhance this later to also delete the image file
+            
+            return jsonify({"ok": True, "message": "Prediction deleted successfully"}), 200
+        except Exception as exc:
+            app.logger.exception(f"Failed to delete prediction {prediction_id}")
+            return jsonify({"error": "Failed to delete prediction", "detail": str(exc)}), 500
+
+    @app.route("/detect", methods=["POST"])
+    def detect():
+        """
+        POST form-data: image file under key 'image'
+        Returns: JSON {emotion, confidence} or error JSON
+        """
+        # Rate limiting
+        client_id = get_client_identifier(request)
+        is_allowed, remaining = detect_limiter.is_allowed(client_id)
+        if not is_allowed:
+            return jsonify({
+                "error": "Rate limit exceeded",
+                "detail": f"Maximum {detect_limiter.max_requests} requests per {detect_limiter.window_seconds} seconds",
+                "retry_after": detect_limiter.window_seconds,
+            }), 429
+        
+        # Get model selection from query parameter (default: 'base')
+        model_selection = request.args.get("model", "base").lower()
+        if model_selection == "fine-tuned" or model_selection == "finetuned":
+            model_local = app.config.get("FINETUNED_MODEL")
+            labels_local = app.config.get("FINETUNED_LABELS") or []
+            model_type = app.config.get("FINETUNED_MODEL_TYPE", "keras")
+            model_version = app.config.get("FINETUNED_MODEL_VERSION", "unknown")
+            if model_local is None:
+                app.logger.warning("Asripa model requested but not available, using base model")
+                model_local = app.config.get("BASE_MODEL")
+                labels_local = app.config.get("BASE_LABELS") or []
+                model_type = app.config.get("BASE_MODEL_TYPE", "keras")
+                model_version = app.config.get("BASE_MODEL_VERSION", "unknown")
+        else:
+            # Use base model (default)
+            model_local = app.config.get("BASE_MODEL")
+            labels_local = app.config.get("BASE_LABELS") or []
+            model_type = app.config.get("BASE_MODEL_TYPE", "keras")
+            model_version = app.config.get("BASE_MODEL_VERSION", "unknown")
+        
+        app.logger.info(f"Using model: {model_selection} (version: {model_version})")
+
+        if model_local is None:
+            app.logger.error("Detect called but model not loaded")
+            raise ServiceUnavailableError("Model not loaded on server")
+        
+        print(f"[DETECT] Using model type: {model_type}")
+
+        # Validate upload presence
+        if "image" not in request.files:
+            raise ValidationError("No image provided")
+        
+        file = request.files["image"]
+        
+        # Comprehensive validation
+        is_valid, error_msg, filename = validate_image_file(
+            file,
+            max_size=app.config.get("MAX_CONTENT_LENGTH", DEFAULTS["MAX_FILE_SIZE"]),
+            allowed_extensions=app.config.get("ALLOWED_EXT", DEFAULTS["ALLOWED_EXT"]),
+        )
+        
+        if not is_valid:
+            raise ValidationError(error_msg)
+
+        tmp_dir = app.config.get("TMP_DIR", TMP_DIR_DEFAULT)
+        tmp_path = os.path.join(tmp_dir, filename)
+        used_filename = filename
+
+        try:
+            # Save file and verify it was saved
+            file.save(tmp_path)
+            if not os.path.exists(tmp_path):
+                app.logger.error("Failed to save uploaded file to %s", tmp_path)
+                raise ValidationError("Failed to save uploaded image")
+            
+            file_size = os.path.getsize(tmp_path)
+            if file_size == 0:
+                app.logger.error("Saved file is empty: %s", tmp_path)
+                raise ValidationError("Uploaded image is empty")
+            
+            print(f"[DETECT] Saved file: {tmp_path}, size: {file_size} bytes")
+            app.logger.info("Saved file: %s, size: %d bytes", tmp_path, file_size)
+
+            # Import numpy for both paths
+            import numpy as np
+
+            # Handle ViT and Keras models differently
+            if model_type == "vit":
+                # Vision Transformer model - needs RGB PIL Image
+                from app.vit_utils import preprocess_face_for_vit, predict_with_vit
+                from PIL import Image
+                
+                face_image, used_filename = preprocess_face_for_vit(tmp_path)
+                if face_image is None:
+                    app.logger.warning("No face detected for file %s (size: %d bytes)", filename, file_size)
+                    raise ValidationError("No face detected in image. Please ensure your face is clearly visible, well-lit, and facing the camera.")
+                
+                # Run ViT prediction
+                idx, confidence, all_probs = predict_with_vit(model_local, face_image, labels_local)
+                emotion = labels_local[idx] if idx < len(labels_local) else str(idx)
+                
+                # Debug output
+                sorted_probs = sorted(all_probs.items(), key=lambda x: x[1], reverse=True)
+                app.logger.info(f"Prediction probabilities for {filename} (sorted): {sorted_probs}")
+                print(f"[DETECT] All emotion probabilities (sorted by confidence):")
+                for emo, prob in sorted_probs:
+                    marker = " <-- SELECTED" if emo == emotion else ""
+                    print(f"  {emo}: {prob:.3f}{marker}")
+                print(f"[DETECT] Predicted emotion: {emotion}, confidence: {confidence:.3f}")
+                
+                # Warn if happy probability is suspiciously low (potential misclassification)
+                happy_prob = all_probs.get('happy', 0.0)
+                if happy_prob < 0.15 and confidence > 0.3 and emotion != 'happy':
+                    app.logger.warning(f"⚠️  Low happy probability ({happy_prob:.3f}) but high confidence ({confidence:.3f}) for {emotion}. Possible misclassification.")
+                    print(f"[DETECT] ⚠️  WARNING: Happy probability is very low ({happy_prob:.3f}) - possible misclassification")
+                
+                # Convert to numpy array format for compatibility with rest of code
+                probs = np.array([all_probs.get(labels_local[i] if i < len(labels_local) else f"class_{i}", 0.0) 
+                                 for i in range(len(labels_local))])
+            else:
+                # Keras model - existing code path
+                # Preprocess face - preprocess_face is imported above in factory scope
+                res = preprocess_face(tmp_path)
+                if isinstance(res, tuple):
+                    face_array, used_filename = res
+                else:
+                    face_array = res
+
+                if face_array is None:
+                    app.logger.warning("No face detected for file %s (size: %d bytes)", filename, file_size)
+                    raise ValidationError("No face detected in image. Please ensure your face is clearly visible, well-lit, and facing the camera.")
+
+                # Defensive conversion and validations (numpy already imported above)
+                try:
+                    face_input = np.asarray(face_array)
+                except Exception as exc:
+                    app.logger.exception("Failed converting preprocessed face to numpy array")
+                    return jsonify({"error": "Invalid preprocessed face data."}), 500
+
+                if getattr(face_input, "dtype", None) == object:
+                    app.logger.error("face_input has object dtype (likely contains None) for file %s", filename)
+                    return jsonify({"error": "Invalid preprocessed face data (object dtype)."}), 500
+
+                # Ensure batch dim and channel dim
+                if face_input.ndim == 2:
+                    # (H, W) -> (1, H, W, 1)
+                    face_input = np.expand_dims(np.expand_dims(face_input, axis=-1), axis=0)
+                elif face_input.ndim == 3:
+                    # (H, W, C) -> (1, H, W, C)
+                    face_input = np.expand_dims(face_input, axis=0)
+                elif face_input.ndim == 4:
+                    # already batched
+                    pass
+                else:
+                    app.logger.error("Unsupported preprocessed face ndim %s for file %s", getattr(face_input, "ndim", None), filename)
+                    return jsonify({"error": "Unsupported preprocessed face shape."}), 500
+
+                # sanity checks
+                if face_input.shape[0] < 1:
+                    return jsonify({"error": "Empty batch sent to model."}), 500
+                try:
+                    if not np.isfinite(face_input.astype("float32")).all():
+                        app.logger.error("face_input contains non-finite values for file %s", filename)
+                        return jsonify({"error": "Preprocessed face contains non-finite values."}), 500
+                except Exception:
+                    app.logger.exception("Failed checking finiteness of face_input")
+                    return jsonify({"error": "Preprocessed face contains invalid numeric values."}), 500
+
+                # Run prediction
+                try:
+                    preds = model_local.predict(face_input, verbose=0)
+                except Exception as exc:
+                    app.logger.exception("Model predict failed for file %s", filename)
+                    return jsonify({"error": "Prediction failed", "detail": str(exc)}), 500
+
+                if preds is None:
+                    return jsonify({"error": "Prediction returned no output"}), 500
+
+                arr = np.asarray(preds)
+                if arr.ndim == 2:
+                    probs = arr[0]
+                elif arr.ndim == 1:
+                    probs = arr
+                else:
+                    app.logger.error("Unexpected prediction shape %s for file %s", getattr(arr, "shape", None), filename)
+                    return jsonify({"error": "Unexpected prediction shape", "shape": list(getattr(arr, "shape", []))}), 500
+
+                if probs.size == 0:
+                    return jsonify({"error": "Empty prediction probabilities"}), 500
+                
+                # Verify model output matches expected number of classes
+                expected_classes = len(labels_local) if isinstance(labels_local, (list, dict)) else 7
+                if len(probs) != expected_classes:
+                    app.logger.warning(f"Model output has {len(probs)} classes but labels have {expected_classes}. Labels: {labels_local}")
+                    print(f"[WARNING] Model output shape mismatch: {len(probs)} classes vs {expected_classes} labels")
+
+                idx = int(np.argmax(probs))
+                confidence = float(probs[idx])
+                
+                # Debug: Log all prediction probabilities to understand model behavior
+                all_probs = {}
+                for i in range(len(probs)):
+                    if isinstance(labels_local, list) and i < len(labels_local):
+                        all_probs[labels_local[i]] = float(probs[i])
+                    elif isinstance(labels_local, dict):
+                        label_key = str(i) if str(i) in labels_local else i if i in labels_local else f"class_{i}"
+                        all_probs[label_key] = float(probs[i])
+                    else:
+                        all_probs[str(i)] = float(probs[i])
+                
+                # Sort by probability (highest first) for easier debugging
+                sorted_probs = sorted(all_probs.items(), key=lambda x: x[1], reverse=True)
+                app.logger.info(f"Prediction probabilities for {filename} (sorted): {sorted_probs}")
+                print(f"[DETECT] All emotion probabilities (sorted by confidence):")
+                for emotion, prob in sorted_probs:
+                    marker = " <-- SELECTED" if emotion == (labels_local[idx] if isinstance(labels_local, list) and idx < len(labels_local) else str(idx)) else ""
+                    print(f"  {emotion}: {prob:.3f}{marker}")
+                print(f"[DETECT] Predicted emotion index: {idx}, confidence: {confidence:.3f}")
+                print(f"[DETECT] Available labels: {labels_local}")
+
+                # Resolve label safely
+                if isinstance(labels_local, dict):
+                    emotion = labels_local.get(str(idx)) or labels_local.get(idx) or list(labels_local.values())[idx]
+                elif isinstance(labels_local, list):
+                    emotion = labels_local[idx] if 0 <= idx < len(labels_local) else str(idx)
+                else:
+                    emotion = str(idx)
+                
+                print(f"[DETECT] Mapped emotion label: {emotion}")
+
+            # Save image even for low confidence (for debugging/analysis)
+            images_dir = app.config.get("IMAGES_DIR", IMAGES_DIR_DEFAULT)
+            stored_filename = None
+            try:
+                stored_filename = save_image(tmp_path, images_dir, used_filename)
+            except Exception:
+                app.logger.exception("Failed to save image, continuing without storage")
+            
+            # Confidence threshold - slightly lower for better detection in challenging conditions
+            # But still maintain quality standards
+            min_conf = app.config.get("MIN_CONFIDENCE", DEFAULTS["MIN_CONFIDENCE"])
+            # Allow slightly lower confidence (0.45) but warn user
+            if confidence < min_conf:
+                try:
+                    log_prediction(DB_PATH, used_filename, "low_confidence", confidence, stored_filename)
+                except Exception:
+                    app.logger.exception("Failed logging low-confidence prediction")
+                return jsonify({
+                    "error": "low confidence",
+                    "confidence": round(confidence, 3),
+                    "filename": stored_filename or used_filename,
+                }), 422
+
+            # Log and respond (image already saved above)
+            try:
+                log_prediction(DB_PATH, used_filename, emotion, confidence, stored_filename)
+            except Exception:
+                app.logger.exception("Failed to log prediction to DB")
+
+            # Return all probabilities for debugging (frontend can use this to show top emotions)
+            all_emotion_probs = {}
+            if model_type == "vit":
+                # For ViT, all_probs already contains the dict
+                all_emotion_probs = {k: round(v, 4) for k, v in all_probs.items()}
+            else:
+                # For Keras, build from probs array
+                for i in range(len(probs)):
+                    if isinstance(labels_local, list) and i < len(labels_local):
+                        all_emotion_probs[labels_local[i]] = round(float(probs[i]), 4)
+                    elif isinstance(labels_local, dict):
+                        label_key = str(i) if str(i) in labels_local else i if i in labels_local else f"class_{i}"
+                        all_emotion_probs[label_key] = round(float(probs[i]), 4)
+            
+            return jsonify({
+                "emotion": emotion,
+                "confidence": round(confidence, 3),
+                "filename": stored_filename or used_filename,
+                "all_probabilities": all_emotion_probs,  # Include all probabilities for debugging
+                "model": model_selection,
+                "model_version": model_version,
+            }), 200
+
+        except (ValidationError, APIError, NotFoundError, ServiceUnavailableError) as exc:
+            # Let Flask's error handler process these
+            raise
+        except Exception as exc:
+            app.logger.exception("detection error for file %s", filename)
+            tb = traceback.format_exc()
+            return jsonify({"error": "internal error", "detail": str(exc), "trace": tb}), 500
+
+        finally:
+            # cleanup tmp file (image is already saved to images/ if successful)
+            try:
+                if os.path.exists(tmp_path):
+                    os.remove(tmp_path)
+            except Exception:
+                app.logger.exception("failed removing tmp file")
+
+    # ----------------------------
+    # Image serving endpoint
+    # ----------------------------
+    @app.route("/images/<filename>", methods=["GET"])
+    def serve_image(filename: str):
+        """
+        Serve stored images.
+        GET /images/{filename}
+        """
+        from flask import send_from_directory, abort
+        
+        # Rate limiting
+        client_id = get_client_identifier(request)
+        is_allowed, remaining = images_limiter.is_allowed(client_id)
+        if not is_allowed:
+            return jsonify({
+                "error": "Rate limit exceeded",
+                "detail": f"Maximum {images_limiter.max_requests} requests per {images_limiter.window_seconds} seconds",
+                "retry_after": images_limiter.window_seconds,
+            }), 429
+        
+        try:
+            images_dir = app.config.get("IMAGES_DIR", IMAGES_DIR_DEFAULT)
+            image_path = get_image_path(images_dir, filename)
+            
+            if not image_path:
+                app.logger.warning("Image not found: %s (checked in %s)", filename, images_dir)
+                abort(404)
+            
+            # Extract the actual filename from the path (in case secure_filename changed it)
+            actual_filename = os.path.basename(image_path)
+            
+            return send_from_directory(
+                images_dir,
+                actual_filename,
+                mimetype="image/jpeg",  # Default, will be auto-detected
+            )
+        except Exception as exc:
+            app.logger.exception("Failed to serve image %s", filename)
+            return jsonify({"error": "Failed to serve image", "detail": str(exc)}), 500
+
+    return app

app/db_logger.py

@@ -0,0 +1,286 @@
+
+import sqlite3
+import os
+import datetime
+from typing import Dict, Tuple, List, Optional
+import threading
+
+SCHEMA = """
+PRAGMA foreign_keys = ON;
+CREATE TABLE IF NOT EXISTS predictions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT NOT NULL,
+    filename TEXT,
+    image_path TEXT,
+    emotion TEXT,
+    confidence REAL
+);
+
+-- Indexes for better query performance
+CREATE INDEX IF NOT EXISTS idx_predictions_ts ON predictions(ts DESC);
+CREATE INDEX IF NOT EXISTS idx_predictions_emotion ON predictions(emotion);
+CREATE INDEX IF NOT EXISTS idx_predictions_confidence ON predictions(confidence);
+"""
+
+# Connection pool for better performance
+_db_lock = threading.Lock()
+_connection_pool: Dict[str, sqlite3.Connection] = {}
+
+
+def get_connection(db_path: str, timeout: int = 10) -> sqlite3.Connection:
+    """
+    Get a database connection with connection pooling.
+    For SQLite, we use a simple per-thread connection approach.
+    """
+    thread_id = threading.get_ident()
+    key = f"{db_path}_{thread_id}"
+    
+    with _db_lock:
+        if key not in _connection_pool:
+            conn = sqlite3.connect(db_path, timeout=timeout, check_same_thread=False)
+            # Optimize SQLite settings
+            conn.execute("PRAGMA journal_mode=WAL;")
+            conn.execute("PRAGMA synchronous=NORMAL;")
+            conn.execute("PRAGMA cache_size=10000;")
+            conn.execute("PRAGMA temp_store=MEMORY;")
+            _connection_pool[key] = conn
+        return _connection_pool[key]
+
+
+def init_db(db_path: str):
+    db_dir = os.path.dirname(db_path)
+    if db_dir and not os.path.exists(db_dir):
+        os.makedirs(db_dir, exist_ok=True)
+
+    conn = sqlite3.connect(db_path, timeout=10)
+    try:
+        conn.execute("PRAGMA journal_mode=WAL;")
+        conn.execute("PRAGMA synchronous=NORMAL;")
+        conn.execute("PRAGMA cache_size=10000;")
+        conn.executescript(SCHEMA)
+        conn.commit()
+    finally:
+        conn.close()
+
+def log_prediction(db_path: str, filename: str, emotion: str, confidence: float, image_path: Optional[str] = None):
+    """
+    Logs a prediction row. This function ensures ts is a string and that
+    values bound to SQLite are primitive types (no functions or callables).
+    
+    Args:
+        db_path: Path to SQLite database
+        filename: Original filename
+        emotion: Detected emotion
+        confidence: Confidence score
+        image_path: Path to stored image file (optional)
+    """
+    # Defensive conversions
+    try:
+        ts = datetime.datetime.now(datetime.UTC).isoformat()
+    except Exception:
+        # fallback to str(datetime)
+        ts = str(datetime.datetime.utcnow())
+
+    if filename is None:
+        filename = ""
+    else:
+        filename = str(filename)
+
+    if emotion is None:
+        emotion = ""
+    else:
+        emotion = str(emotion)
+
+    if image_path is None:
+        image_path = ""
+    else:
+        image_path = str(image_path)
+
+    try:
+        confidence_val = float(confidence or 0.0)
+    except Exception:
+        confidence_val = 0.0
+
+    conn = get_connection(db_path)
+    try:
+        cur = conn.cursor()
+        # Check if image_path column exists, if not, add it
+        cur.execute("PRAGMA table_info(predictions)")
+        columns = [row[1] for row in cur.fetchall()]
+        
+        if "image_path" not in columns:
+            # Migrate schema - add image_path column
+            cur.execute("ALTER TABLE predictions ADD COLUMN image_path TEXT")
+            conn.commit()
+        
+        cur.execute(
+            "INSERT INTO predictions (ts, filename, image_path, emotion, confidence) VALUES (?, ?, ?, ?, ?)",
+            (ts, filename, image_path, emotion, confidence_val)
+        )
+        conn.commit()
+        return cur.lastrowid
+    except Exception:
+        # On error, close connection and retry with new connection
+        with _db_lock:
+            thread_id = threading.get_ident()
+            key = f"{db_path}_{thread_id}"
+            if key in _connection_pool:
+                try:
+                    _connection_pool[key].close()
+                except:
+                    pass
+                del _connection_pool[key]
+        raise
+
+def get_metrics(db_path: str) -> Dict:
+    conn = get_connection(db_path)
+    try:
+        cur = conn.cursor()
+        cur.execute("SELECT COUNT(*) FROM predictions")
+        total = cur.fetchone()[0] or 0
+        cur.execute("SELECT emotion, COUNT(*) FROM predictions GROUP BY emotion")
+        rows = cur.fetchall()
+        by_label = {r[0]: r[1] for r in rows}
+        return {"total": total, "by_label": by_label}
+    except Exception:
+        with _db_lock:
+            thread_id = threading.get_ident()
+            key = f"{db_path}_{thread_id}"
+            if key in _connection_pool:
+                try:
+                    _connection_pool[key].close()
+                except:
+                    pass
+                del _connection_pool[key]
+        raise
+
+def tail_rows(db_path: str, limit: int = 10, offset: int = 0, emotion_filter: Optional[str] = None, 
+              min_confidence: Optional[float] = None, max_confidence: Optional[float] = None,
+              date_from: Optional[str] = None, date_to: Optional[str] = None) -> Tuple:
+    """
+    Fetch rows from predictions table with filtering and pagination.
+    
+    Returns:
+        List of tuples: (id, ts, filename, image_path, emotion, confidence) or 
+        (ts, filename, image_path, emotion, confidence) depending on query
+    """
+    conn = get_connection(db_path)
+    try:
+        cur = conn.cursor()
+        
+        # Build query with filters
+        query = "SELECT id, ts, filename, image_path, emotion, confidence FROM predictions WHERE 1=1"
+        params = []
+        
+        if emotion_filter:
+            query += " AND emotion = ?"
+            params.append(emotion_filter)
+        
+        if min_confidence is not None:
+            query += " AND confidence >= ?"
+            params.append(min_confidence)
+        
+        if max_confidence is not None:
+            query += " AND confidence <= ?"
+            params.append(max_confidence)
+        
+        if date_from:
+            query += " AND ts >= ?"
+            params.append(date_from)
+        
+        if date_to:
+            query += " AND ts <= ?"
+            params.append(date_to)
+        
+        query += " ORDER BY id DESC LIMIT ? OFFSET ?"
+        params.extend([limit, offset])
+        
+        cur.execute(query, params)
+        return cur.fetchall()
+    except Exception:
+        with _db_lock:
+            thread_id = threading.get_ident()
+            key = f"{db_path}_{thread_id}"
+            if key in _connection_pool:
+                try:
+                    _connection_pool[key].close()
+                except:
+                    pass
+                del _connection_pool[key]
+        raise
+
+
+def delete_prediction(db_path: str, prediction_id: int) -> bool:
+    """
+    Delete a prediction by ID.
+    
+    Args:
+        db_path: Path to SQLite database
+        prediction_id: ID of prediction to delete
+    
+    Returns:
+        True if deleted, False otherwise
+    """
+    conn = get_connection(db_path)
+    try:
+        cur = conn.cursor()
+        cur.execute("DELETE FROM predictions WHERE id = ?", (prediction_id,))
+        conn.commit()
+        return cur.rowcount > 0
+    except Exception:
+        with _db_lock:
+            thread_id = threading.get_ident()
+            key = f"{db_path}_{thread_id}"
+            if key in _connection_pool:
+                try:
+                    _connection_pool[key].close()
+                except:
+                    pass
+                del _connection_pool[key]
+        raise
+
+
+def get_total_count(db_path: str, emotion_filter: Optional[str] = None,
+                   min_confidence: Optional[float] = None, max_confidence: Optional[float] = None,
+                   date_from: Optional[str] = None, date_to: Optional[str] = None) -> int:
+    """Get total count of predictions matching filters."""
+    conn = get_connection(db_path)
+    try:
+        cur = conn.cursor()
+        
+        query = "SELECT COUNT(*) FROM predictions WHERE 1=1"
+        params = []
+        
+        if emotion_filter:
+            query += " AND emotion = ?"
+            params.append(emotion_filter)
+        
+        if min_confidence is not None:
+            query += " AND confidence >= ?"
+            params.append(min_confidence)
+        
+        if max_confidence is not None:
+            query += " AND confidence <= ?"
+            params.append(max_confidence)
+        
+        if date_from:
+            query += " AND ts >= ?"
+            params.append(date_from)
+        
+        if date_to:
+            query += " AND ts <= ?"
+            params.append(date_to)
+        
+        cur.execute(query, params)
+        return cur.fetchone()[0] or 0
+    except Exception:
+        with _db_lock:
+            thread_id = threading.get_ident()
+            key = f"{db_path}_{thread_id}"
+            if key in _connection_pool:
+                try:
+                    _connection_pool[key].close()
+                except:
+                    pass
+                del _connection_pool[key]
+        raise

app/error_handlers.py

@@ -0,0 +1,64 @@
+"""
+Structured error handling for API responses.
+"""
+from flask import jsonify
+from typing import Dict, Any
+
+
+class APIError(Exception):
+    """Base exception for API errors."""
+    status_code = 500
+    message = "An error occurred"
+    
+    def __init__(self, message: str = None, status_code: int = None, details: Dict[str, Any] = None):
+        super().__init__()
+        self.message = message or self.message
+        self.status_code = status_code or self.status_code
+        self.details = details or {}
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "error": self.message,
+            **self.details,
+        }
+
+
+class ValidationError(APIError):
+    """Validation error (400)."""
+    status_code = 400
+    message = "Validation error"
+
+
+class NotFoundError(APIError):
+    """Resource not found (404)."""
+    status_code = 404
+    message = "Resource not found"
+
+
+class ServiceUnavailableError(APIError):
+    """Service unavailable (503)."""
+    status_code = 503
+    message = "Service unavailable"
+
+
+def register_error_handlers(app):
+    """Register error handlers for the Flask app."""
+    
+    @app.errorhandler(APIError)
+    def handle_api_error(error: APIError):
+        response = jsonify(error.to_dict())
+        response.status_code = error.status_code
+        return response
+    
+    @app.errorhandler(404)
+    def handle_not_found(e):
+        return jsonify({"error": "Endpoint not found"}), 404
+    
+    @app.errorhandler(405)
+    def handle_method_not_allowed(e):
+        return jsonify({"error": "Method not allowed"}), 405
+    
+    @app.errorhandler(500)
+    def handle_internal_error(e):
+        app.logger.exception("Internal server error")
+        return jsonify({"error": "Internal server error"}), 500

app/image_cleanup.py

@@ -0,0 +1,200 @@
+"""
+Image cleanup utility to remove orphaned images (not referenced in database).
+Can be run as a scheduled job or manually.
+"""
+import os
+import sqlite3
+from pathlib import Path
+from typing import Set
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def get_referenced_images(db_path: str) -> Set[str]:
+    """
+    Get set of all image filenames referenced in the database.
+    
+    Returns:
+        Set of image filenames (basenames only)
+    """
+    conn = sqlite3.connect(db_path, timeout=10)
+    try:
+        cur = conn.cursor()
+        
+        # Check if image_path column exists
+        cur.execute("PRAGMA table_info(predictions)")
+        columns = [row[1] for row in cur.fetchall()]
+        
+        if "image_path" not in columns:
+            # Column doesn't exist yet, return empty set
+            return set()
+        
+        # Get all non-empty image_path values
+        cur.execute("SELECT DISTINCT image_path FROM predictions WHERE image_path IS NOT NULL AND image_path != ''")
+        rows = cur.fetchall()
+        
+        # Extract just the filenames (basenames)
+        referenced = set()
+        for row in rows:
+            if row[0]:
+                filename = os.path.basename(row[0])
+                if filename:
+                    referenced.add(filename)
+        
+        return referenced
+    finally:
+        conn.close()
+
+
+def cleanup_orphaned_images(images_dir: str, db_path: str, dry_run: bool = True) -> dict:
+    """
+    Remove image files that are not referenced in the database.
+    
+    Args:
+        images_dir: Directory containing images
+        db_path: Path to SQLite database
+        dry_run: If True, only report what would be deleted without actually deleting
+    
+    Returns:
+        Dict with cleanup statistics
+    """
+    if not os.path.exists(images_dir):
+        logger.warning(f"Images directory does not exist: {images_dir}")
+        return {
+            "total_images": 0,
+            "referenced": 0,
+            "orphaned": 0,
+            "deleted": 0,
+            "errors": 0,
+        }
+    
+    # Get referenced images from database
+    referenced = get_referenced_images(db_path)
+    logger.info(f"Found {len(referenced)} referenced images in database")
+    
+    # Get all image files in directory
+    image_extensions = {".jpg", ".jpeg", ".png", ".gif", ".bmp"}
+    all_images = []
+    
+    for file_path in Path(images_dir).iterdir():
+        if file_path.is_file() and file_path.suffix.lower() in image_extensions:
+            all_images.append(file_path.name)
+    
+    total_images = len(all_images)
+    logger.info(f"Found {total_images} image files in directory")
+    
+    # Find orphaned images
+    orphaned = [img for img in all_images if img not in referenced]
+    
+    stats = {
+        "total_images": total_images,
+        "referenced": len(referenced),
+        "orphaned": len(orphaned),
+        "deleted": 0,
+        "errors": 0,
+    }
+    
+    if not orphaned:
+        logger.info("No orphaned images found")
+        return stats
+    
+    logger.info(f"Found {len(orphaned)} orphaned images")
+    
+    # Delete orphaned images
+    for filename in orphaned:
+        file_path = os.path.join(images_dir, filename)
+        try:
+            if not dry_run:
+                os.remove(file_path)
+                logger.debug(f"Deleted orphaned image: {filename}")
+            else:
+                logger.debug(f"Would delete orphaned image: {filename}")
+            stats["deleted"] += 1
+        except Exception as e:
+            logger.error(f"Failed to delete {filename}: {e}")
+            stats["errors"] += 1
+    
+    if dry_run:
+        logger.info(f"DRY RUN: Would delete {stats['deleted']} orphaned images")
+    else:
+        logger.info(f"Deleted {stats['deleted']} orphaned images")
+    
+    return stats
+
+
+def cleanup_old_images(images_dir: str, db_path: str, days_old: int = 30, dry_run: bool = True) -> dict:
+    """
+    Remove images older than specified days that are not referenced in recent predictions.
+    
+    Args:
+        images_dir: Directory containing images
+        db_path: Path to SQLite database
+        days_old: Remove images older than this many days
+        dry_run: If True, only report what would be deleted
+    
+    Returns:
+        Dict with cleanup statistics
+    """
+    import datetime
+    
+    if not os.path.exists(images_dir):
+        return {
+            "total_images": 0,
+            "old_images": 0,
+            "deleted": 0,
+            "errors": 0,
+        }
+    
+    # Calculate cutoff date
+    cutoff_date = datetime.datetime.now(datetime.UTC) - datetime.timedelta(days=days_old)
+    cutoff_iso = cutoff_date.isoformat()
+    
+    # Get images referenced after cutoff
+    conn = sqlite3.connect(db_path, timeout=10)
+    try:
+        cur = conn.cursor()
+        cur.execute("""
+            SELECT DISTINCT image_path 
+            FROM predictions 
+            WHERE image_path IS NOT NULL 
+            AND image_path != '' 
+            AND ts >= ?
+        """, (cutoff_iso,))
+        recent_images = {os.path.basename(row[0]) for row in cur.fetchall() if row[0]}
+    finally:
+        conn.close()
+    
+    # Find old images
+    image_extensions = {".jpg", ".jpeg", ".png", ".gif", ".bmp"}
+    old_images = []
+    
+    for file_path in Path(images_dir).iterdir():
+        if file_path.is_file() and file_path.suffix.lower() in image_extensions:
+            # Check file modification time
+            mtime = datetime.datetime.fromtimestamp(file_path.stat().st_mtime, tz=datetime.UTC)
+            if mtime < cutoff_date:
+                # Only delete if not in recent images
+                if file_path.name not in recent_images:
+                    old_images.append(file_path.name)
+    
+    stats = {
+        "total_images": len(list(Path(images_dir).iterdir())),
+        "old_images": len(old_images),
+        "deleted": 0,
+        "errors": 0,
+    }
+    
+    for filename in old_images:
+        file_path = os.path.join(images_dir, filename)
+        try:
+            if not dry_run:
+                os.remove(file_path)
+            stats["deleted"] += 1
+        except Exception as e:
+            logger.error(f"Failed to delete {filename}: {e}")
+            stats["errors"] += 1
+    
+    return stats
+
+

app/image_storage.py

@@ -0,0 +1,124 @@
+"""
+Image storage utilities for saving and serving uploaded images.
+"""
+import os
+import uuid
+import shutil
+from pathlib import Path
+from typing import Optional, Tuple
+from werkzeug.utils import secure_filename
+
+
+def ensure_images_dir(images_dir: str) -> str:
+    """Ensure images directory exists and return its path."""
+    os.makedirs(images_dir, exist_ok=True)
+    return images_dir
+
+
+def generate_unique_filename(original_filename: str) -> str:
+    """
+    Generate a unique filename to avoid collisions.
+    Format: {uuid}_{secure_original_name} or just {uuid}.jpg if original is invalid
+    """
+    # Get secure base name
+    base_name = secure_filename(original_filename)
+    if not base_name:
+        base_name = "upload.jpg"
+    
+    # Add UUID prefix for uniqueness (use full UUID to ensure uniqueness)
+    name, ext = os.path.splitext(base_name)
+    if not ext or ext.lower() not in ('.jpg', '.jpeg', '.png'):
+        ext = '.jpg'
+    unique_id = str(uuid.uuid4())  # Full UUID for better uniqueness
+    return f"{unique_id}_{name}{ext}"
+
+
+def save_image(source_path: str, images_dir: str, original_filename: str) -> Optional[str]:
+    """
+    Save an image from source_path to images_dir with a unique filename.
+    
+    Args:
+        source_path: Path to source image file
+        images_dir: Directory to save images to
+        original_filename: Original filename for reference
+    
+    Returns:
+        Stored filename (relative to images_dir) or None on failure
+    """
+    try:
+        ensure_images_dir(images_dir)
+        
+        # Generate unique filename
+        stored_filename = generate_unique_filename(original_filename)
+        dest_path = os.path.join(images_dir, stored_filename)
+        
+        # Copy file
+        shutil.copy2(source_path, dest_path)
+        
+        return stored_filename
+    except Exception as e:
+        # Log error but don't fail the request
+        import logging
+        logging.getLogger(__name__).exception(f"Failed to save image: {e}")
+        return None
+
+
+def get_image_path(images_dir: str, filename: str) -> Optional[str]:
+    """
+    Get full path to an image file if it exists.
+    
+    Args:
+        images_dir: Base images directory
+        filename: Image filename
+    
+    Returns:
+        Full path to image or None if not found
+    """
+    if not filename:
+        return None
+    
+    # Security: ensure filename doesn't contain path traversal
+    # Extract just the basename to prevent directory traversal
+    base_filename = os.path.basename(filename)
+    safe_filename = secure_filename(base_filename)
+    
+    if not safe_filename:
+        return None
+    
+    # Use safe_filename for the path (secure_filename may have sanitized it)
+    # But also try the original if it's already safe
+    image_path = os.path.join(images_dir, safe_filename)
+    
+    if os.path.exists(image_path) and os.path.isfile(image_path):
+        return image_path
+    
+    # Also try the original filename if it's different and seems safe
+    if safe_filename != base_filename:
+        # Check if original is safe (no path separators, no parent dir references)
+        if base_filename == filename and '/' not in base_filename and '\\' not in base_filename and '..' not in base_filename:
+            alt_path = os.path.join(images_dir, base_filename)
+            if os.path.exists(alt_path) and os.path.isfile(alt_path):
+                return alt_path
+    
+    return None
+
+
+def delete_image(images_dir: str, filename: str) -> bool:
+    """
+    Delete an image file.
+    
+    Args:
+        images_dir: Base images directory
+        filename: Image filename to delete
+    
+    Returns:
+        True if deleted, False otherwise
+    """
+    try:
+        image_path = get_image_path(images_dir, filename)
+        if image_path and os.path.exists(image_path):
+            os.remove(image_path)
+            return True
+        return False
+    except Exception:
+        return False

app/model_loader.py

@@ -0,0 +1,187 @@
+# app/model_loader.py
+import os
+import json
+from pathlib import Path
+from typing import Tuple, Any, Optional, Dict
+
+DEFAULT_LABELS = ['angry', 'disgust', 'fear', 'happy', 'neutral', 'sad', 'surprise']
+# HardlyHumans model uses 8 emotions (adds contempt)
+HARDLYHUMANS_LABELS = ['anger', 'contempt', 'sad', 'happy', 'neutral', 'disgust', 'fear', 'surprise']
+
+def load_emotion_model(force_model: str = None):
+    """
+    Load emotion detection model. Supports both Keras and Vision Transformer models.
+    
+    Args:
+        force_model: 'base' to force base model, 'fine-tuned' to force fine-tuned, None for auto
+    
+    Returns: (model_dict, labels, model_version, model_type)
+    model_dict: For ViT: {'model': model, 'processor': processor, 'type': 'vit'}
+                For Keras: model object
+    model_type: 'keras' or 'vit' (Vision Transformer)
+    """
+    this_dir = Path(__file__).resolve().parent  # app/
+    repo_root = this_dir.parent                 # project root (/app in container)
+    models_dir = repo_root / "models"
+    fine_tuned_dir = models_dir / "fine_tuned_vit"
+
+    # Try to load fine-tuned model first (trained on FER2013 for better happy/surprise detection)
+    # Unless force_model is 'base'
+    if force_model != 'base':
+        try:
+            from transformers import AutoImageProcessor, AutoModelForImageClassification
+            
+            # Check if fine-tuned model exists
+            if fine_tuned_dir.exists() and (fine_tuned_dir / "model.safetensors").exists():
+                print(f"[MODEL] 🎯 Loading Asripa model (FER2013 Enhanced): {fine_tuned_dir}")
+                print(f"[MODEL] Accuracy: 78.26% (fine-tuned on FER2013)")
+                print(f"[MODEL] Optimized for happy/surprise detection!")
+                
+                processor = AutoImageProcessor.from_pretrained(
+                    str(fine_tuned_dir),
+                    local_files_only=True
+                )
+                model = AutoModelForImageClassification.from_pretrained(
+                    str(fine_tuned_dir),
+                    local_files_only=True,
+                    low_cpu_mem_usage=True
+                )
+                
+                # Get labels from model config
+                raw_labels = [model.config.id2label[i] for i in range(len(model.config.id2label))]
+                print(f"[MODEL] Raw labels from model config: {raw_labels}")
+                
+                # Normalize label names to match our format (lowercase, standardize)
+                label_map = {
+                    'anger': 'angry',
+                    'disgust': 'disgust',
+                    'fear': 'fear',
+                    'happy': 'happy',
+                    'neutral': 'neutral',
+                    'sad': 'sad',
+                    'surprise': 'surprise',
+                    'contempt': 'contempt'
+                }
+                labels = [label_map.get(label.lower(), label.lower()) for label in raw_labels]
+                print(f"[MODEL] Normalized labels: {labels}")
+                
+                print(f"[MODEL] ✅ Fine-tuned ViT model loaded successfully!")
+                return {
+                    'model': model,
+                    'processor': processor,
+                    'type': 'vit'
+                }, labels, "asripa-vit-78.26%", 'vit'
+            else:
+                if force_model == 'fine-tuned':
+                    print(f"[MODEL] ⚠️  Fine-tuned model requested but not found!")
+                    raise FileNotFoundError("Fine-tuned model not found")
+                print(f"[MODEL] Fine-tuned model not found, using base model...")
+        except Exception as e:
+            if force_model == 'fine-tuned':
+                print(f"[MODEL] ⚠️  Failed to load fine-tuned model: {e}")
+                raise
+            print(f"[MODEL] ⚠️  Failed to load fine-tuned model: {e}")
+            print(f"[MODEL] Falling back to base HardlyHumans model...")
+
+    # Fall back to base HardlyHumans ViT model (best accuracy - 92.2%)
+    try:
+        from transformers import AutoImageProcessor, AutoModelForImageClassification
+        
+        model_id = "HardlyHumans/Facial-expression-detection"
+        print(f"[MODEL] Loading Base Model: {model_id}")
+        print(f"[MODEL] Accuracy: 92.2% - BASE MODEL")
+        print(f"[MODEL] Downloading from HuggingFace if not cached...")
+        
+        # Load from HuggingFace - will download and cache automatically
+        # Use low_cpu_mem_usage to reduce memory footprint during loading
+        processor = AutoImageProcessor.from_pretrained(
+            model_id, 
+            cache_dir=str(models_dir),
+            local_files_only=False  # Allow download if not cached
+        )
+        model = AutoModelForImageClassification.from_pretrained(
+            model_id, 
+            cache_dir=str(models_dir),
+            local_files_only=False,  # Allow download if not cached
+            low_cpu_mem_usage=True  # Reduce memory usage during loading
+        )
+        
+        # Get labels from model config
+        raw_labels = [model.config.id2label[i] for i in range(len(model.config.id2label))]
+        print(f"[MODEL] Raw labels from model config: {raw_labels}")
+        print(f"[MODEL] Label mapping (id2label): {model.config.id2label}")
+        
+        # Normalize label names to match our format (lowercase, standardize)
+        label_map = {
+            'anger': 'angry',
+            'disgust': 'disgust',
+            'fear': 'fear',
+            'happy': 'happy',
+            'neutral': 'neutral',
+            'sad': 'sad',
+            'surprise': 'surprise',
+            'contempt': 'contempt'  # New emotion in this model
+        }
+        labels = [label_map.get(label.lower(), label.lower()) for label in raw_labels]
+        print(f"[MODEL] Normalized labels: {labels}")
+        
+        print(f"[MODEL] ✅ ViT model loaded successfully!")
+        return {
+            'model': model,
+            'processor': processor,
+            'type': 'vit'
+        }, labels, "base-vit-92.2%", 'vit'
+    except ImportError as e:
+        print(f"[MODEL] ❌ transformers library not installed: {e}")
+        print("[MODEL] Install with: pip install transformers torch")
+        print("[MODEL] Falling back to Keras model...")
+    except Exception as e:
+        print(f"[MODEL] ❌ Failed to load ViT model: {e}")
+        print(f"[MODEL] Error type: {type(e).__name__}")
+        print(f"[MODEL] Error message: {str(e)}")
+        import traceback
+        print(f"[MODEL] Full traceback:")
+        print(traceback.format_exc())
+        print("[MODEL] ⚠️  Falling back to Keras model (lower accuracy)...")
+
+    # Fall back to Keras models
+    try:
+        from tensorflow.keras.models import load_model
+    except ImportError:
+        raise ImportError("Neither transformers nor tensorflow.keras available. Install one of them.")
+
+    candidate_names = ["emotion_model.keras", "emotion_model.h5", "emotion_model.hdf5"]
+    model_path = None
+    for name in candidate_names:
+        p = models_dir / name
+        if p.exists():
+            model_path = str(p)
+            break
+
+    if model_path is None:
+        raise FileNotFoundError(f"No model file found in {models_dir}. Please add emotion_model.keras or emotion_model.h5")
+
+    print(f"[MODEL] Loading Keras model: {model_path}")
+    model = load_model(model_path)
+
+    # Load labels if available
+    labels_path = models_dir / "labels.json"
+    labels = DEFAULT_LABELS
+    if labels_path.exists():
+        try:
+            with labels_path.open("r", encoding="utf-8") as f:
+                labels = json.load(f)
+        except Exception:
+            labels = DEFAULT_LABELS
+
+    # Model version
+    version_path = models_dir / "MODEL_VERSION.txt"
+    version = "v_unknown"
+    if os.path.exists(version_path):
+        try:
+            with open(version_path, "r", encoding="utf-8") as f:
+                version = f.read().strip()
+        except Exception:
+            pass
+
+    return model, labels, version, 'keras'

app/rate_limiter.py

@@ -0,0 +1,89 @@
+"""
+Simple in-memory rate limiter for API endpoints.
+For production, consider using Redis-based rate limiting.
+"""
+import time
+from collections import defaultdict
+from typing import Dict, Tuple
+from threading import Lock
+
+
+class RateLimiter:
+    """
+    Simple token bucket rate limiter.
+    Thread-safe for basic use cases.
+    """
+    
+    def __init__(self, max_requests: int = 100, window_seconds: int = 60):
+        """
+        Args:
+            max_requests: Maximum requests allowed in the time window
+            window_seconds: Time window in seconds
+        """
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self.requests: Dict[str, list] = defaultdict(list)
+        self.lock = Lock()
+    
+    def is_allowed(self, identifier: str) -> Tuple[bool, int]:
+        """
+        Check if a request is allowed.
+        
+        Args:
+            identifier: Unique identifier (e.g., IP address, user ID)
+        
+        Returns:
+            Tuple of (is_allowed, remaining_requests)
+        """
+        current_time = time.time()
+        
+        with self.lock:
+            # Clean old requests outside the window
+            window_start = current_time - self.window_seconds
+            self.requests[identifier] = [
+                req_time for req_time in self.requests[identifier]
+                if req_time > window_start
+            ]
+            
+            # Check if limit exceeded
+            if len(self.requests[identifier]) >= self.max_requests:
+                remaining = 0
+                return False, remaining
+            
+            # Add current request
+            self.requests[identifier].append(current_time)
+            remaining = self.max_requests - len(self.requests[identifier])
+            
+            return True, remaining
+    
+    def reset(self, identifier: str = None):
+        """Reset rate limit for an identifier or all identifiers."""
+        with self.lock:
+            if identifier:
+                self.requests.pop(identifier, None)
+            else:
+                self.requests.clear()
+
+
+# Global rate limiters for different endpoints
+detect_limiter = RateLimiter(max_requests=30, window_seconds=60)  # 30 requests per minute
+logs_limiter = RateLimiter(max_requests=100, window_seconds=60)  # 100 requests per minute
+images_limiter = RateLimiter(max_requests=200, window_seconds=60)  # 200 requests per minute
+
+
+def get_client_identifier(request) -> str:
+    """
+    Get a unique identifier for rate limiting.
+    Uses IP address by default.
+    """
+    # Try to get real IP (behind proxy)
+    forwarded_for = request.headers.get("X-Forwarded-For")
+    if forwarded_for:
+        # Take the first IP in the chain
+        return forwarded_for.split(",")[0].strip()
+    
+    real_ip = request.headers.get("X-Real-IP")
+    if real_ip:
+        return real_ip
+    
+    return request.remote_addr or "unknown"

app/utils.py

@@ -0,0 +1,180 @@
+# app/utils.py
+import os
+import cv2
+import numpy as np
+from typing import Optional, Tuple
+
+def _enhance_for_detection(gray: np.ndarray) -> np.ndarray:
+    """
+    Apply light preprocessing to improve face detection on low-contrast or slightly blurry images.
+    Uses CLAHE (adaptive histogram equalization) and a mild bilateral filter.
+    """
+    # CLAHE for contrast
+    clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
+    enhanced = clahe.apply(gray)
+
+    # Mild bilateral filtering to reduce noise while preserving edges (helps detection on some images)
+    enhanced = cv2.bilateralFilter(enhanced, d=5, sigmaColor=75, sigmaSpace=75)
+    return enhanced
+
+
+def preprocess_face(
+    image_path: str,
+    target_size: Tuple[int, int] = (48, 48),
+    detect_max_dim: int = 800,
+    pad_ratio: float = 0.25,  # Increased from 0.15 to 0.25 to preserve more context (eyes, eyebrows, mouth area)
+) -> Tuple[Optional[np.ndarray], Optional[str]]:
+    """
+    Load an image at image_path, detect a face and return a preprocessed array:
+      - shape: (1, H, W, 1)
+      - dtype: np.float32
+      - values scaled to [0,1]
+
+    If no face detected or on error, returns (None, None).
+
+    Parameters:
+    - target_size: size expected by the model (height, width).
+    - detect_max_dim: maximum size (longest side) used for the detection pass to speed up detection.
+    - pad_ratio: fraction of face box to pad on each side (helps avoid tight crops).
+
+    Returns:
+    - (face_array, used_filename)
+    """
+    try:
+        img = cv2.imread(image_path)
+        if img is None:
+            return None, None
+
+        h0, w0 = img.shape[:2]
+        # grayscale copy for detection
+        gray_full = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+
+        # Downscale for faster detection if image is huge
+        scale = 1.0
+        max_side = max(w0, h0)
+        if max_side > detect_max_dim:
+            scale = detect_max_dim / float(max_side)
+            small = cv2.resize(gray_full, (int(w0 * scale), int(h0 * scale)), interpolation=cv2.INTER_LINEAR)
+        else:
+            small = gray_full.copy()
+
+        # Try to enhance small image for better detection on blurry photos
+        small_enh = _enhance_for_detection(small)
+
+        # Try multiple cascade classifiers for better detection
+        cascade_paths = [
+            "haarcascade_frontalface_default.xml",
+            "haarcascade_frontalface_alt.xml",
+            "haarcascade_frontalface_alt2.xml",
+        ]
+        
+        faces = []
+        
+        # Try each cascade with progressively more permissive parameters
+        for cascade_name in cascade_paths:
+            if len(faces) > 0:
+                break
+                
+            try:
+                face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + cascade_name)
+                if face_cascade.empty():
+                    continue
+                
+                # Attempt 1: Standard detection
+                faces = face_cascade.detectMultiScale(
+                    small_enh,
+                    scaleFactor=1.1,
+                    minNeighbors=5,
+                    minSize=(30, 30),
+                    flags=cv2.CASCADE_SCALE_IMAGE,
+                )
+                
+                # Attempt 2: More permissive (helps blurry / odd-angle photos)
+                if len(faces) == 0:
+                    faces = face_cascade.detectMultiScale(
+                        small_enh,
+                        scaleFactor=1.05,
+                        minNeighbors=3,
+                        minSize=(20, 20),
+                        flags=cv2.CASCADE_SCALE_IMAGE,
+                    )
+                
+                # Attempt 3: Even more permissive (for challenging conditions)
+                if len(faces) == 0:
+                    faces = face_cascade.detectMultiScale(
+                        small_enh,
+                        scaleFactor=1.03,
+                        minNeighbors=2,
+                        minSize=(15, 15),
+                        flags=cv2.CASCADE_SCALE_IMAGE,
+                    )
+                    
+            except Exception:
+                continue
+        
+        # If still nothing, try on original (non-enhanced) image
+        if len(faces) == 0:
+            try:
+                face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + "haarcascade_frontalface_default.xml")
+                if not face_cascade.empty():
+                    # Sometimes enhancement hurts detection, try original
+                    faces = face_cascade.detectMultiScale(
+                        small,
+                        scaleFactor=1.05,
+                        minNeighbors=3,
+                        minSize=(20, 20),
+                        flags=cv2.CASCADE_SCALE_IMAGE,
+                    )
+            except Exception:
+                pass
+
+        if len(faces) == 0:
+            return None, None
+
+        # Choose the largest detected face (usually the main subject)
+        faces = sorted(faces, key=lambda r: r[2] * r[3], reverse=True)
+        (x_s, y_s, w_s, h_s) = faces[0]
+
+        # Map coordinates back to original image scale
+        x = int(x_s / scale)
+        y = int(y_s / scale)
+        w = int(w_s / scale)
+        h = int(h_s / scale)
+
+        # Pad bounding box slightly (pad_ratio of face size)
+        pad_w = int(w * pad_ratio)
+        pad_h = int(h * pad_ratio)
+        x1 = max(0, x - pad_w)
+        y1 = max(0, y - pad_h)
+        x2 = min(w0, x + w + pad_w)
+        y2 = min(h0, y + h + pad_h)
+
+        face_crop = gray_full[y1:y2, x1:x2]
+
+        # final resize to model input
+        # Use INTER_CUBIC for better quality when upscaling small faces (preserves more detail for emotion recognition)
+        face_resized = cv2.resize(face_crop, (target_size[1], target_size[0]), interpolation=cv2.INTER_CUBIC)
+
+        # ensure numeric ndarray and float32 dtype
+        face_arr = np.asarray(face_resized, dtype=np.float32)
+
+        # normalize
+        face_arr = face_arr / 255.0
+
+        # channel & batch dims -> (1, H, W, 1)
+        if face_arr.ndim == 2:
+            face_arr = np.expand_dims(face_arr, axis=-1)
+        face_arr = np.expand_dims(face_arr, axis=0)
+
+        # final sanity checks
+        if face_arr.dtype != np.float32:
+            face_arr = face_arr.astype(np.float32)
+        if not np.isfinite(face_arr).all():
+            return None, None
+
+        used_filename = os.path.basename(image_path) or "upload.jpg"
+        return face_arr, used_filename
+
+    except Exception:
+        # don't leak internals to caller; let app log exceptions if needed
+        return None, None

app/validators.py

@@ -0,0 +1,116 @@
+"""
+Request validation utilities.
+"""
+import os
+from typing import Tuple, Optional
+from werkzeug.utils import secure_filename
+from PIL import Image
+
+
+def validate_image_file(file, max_size: int, allowed_extensions: tuple) -> Tuple[bool, Optional[str], Optional[str]]:
+    """
+    Validate uploaded image file.
+    
+    Args:
+        file: FileStorage object from Flask
+        max_size: Maximum file size in bytes
+        allowed_extensions: Tuple of allowed extensions (e.g., (".jpg", ".png"))
+    
+    Returns:
+        Tuple of (is_valid, error_message, sanitized_filename)
+        If valid: (True, None, filename)
+        If invalid: (False, error_message, None)
+    """
+    if not file or not file.filename:
+        return False, "No file provided", None
+    
+    # Check filename
+    filename = secure_filename(file.filename)
+    if not filename:
+        return False, "Invalid filename", None
+    
+    # Check extension
+    ext = os.path.splitext(filename)[1].lower()
+    if ext not in allowed_extensions:
+        return False, f"Unsupported file type. Allowed: {', '.join(allowed_extensions)}", None
+    
+    # Check file size (if available)
+    try:
+        file.seek(0, os.SEEK_END)
+        file_size = file.tell()
+        file.seek(0)  # Reset to beginning
+        
+        if file_size > max_size:
+            max_mb = max_size / (1024 * 1024)
+            return False, f"File too large. Maximum size: {max_mb:.1f}MB", None
+        
+        if file_size == 0:
+            return False, "File is empty", None
+    except Exception:
+        # If we can't check size, continue (will be caught by MAX_CONTENT_LENGTH)
+        pass
+    
+    # Validate it's actually an image by trying to open it
+    try:
+        file.seek(0)
+        img = Image.open(file)
+        img.verify()  # Verify it's a valid image
+        file.seek(0)  # Reset after verification
+    except Exception as e:
+        return False, f"Invalid image file: {str(e)}", None
+    
+    return True, None, filename
+
+
+def validate_pagination_params(limit: Optional[str], offset: Optional[str]) -> Tuple[int, int, Optional[str]]:
+    """
+    Validate pagination parameters.
+    
+    Returns:
+        Tuple of (limit, offset, error_message)
+    """
+    try:
+        limit_val = int(limit) if limit else 20
+        limit_val = max(1, min(200, limit_val))
+    except ValueError:
+        return 20, 0, "Invalid limit parameter. Must be an integer."
+    
+    try:
+        offset_val = int(offset) if offset else 0
+        offset_val = max(0, offset_val)
+    except ValueError:
+        return limit_val, 0, "Invalid offset parameter. Must be an integer."
+    
+    return limit_val, offset_val, None
+
+
+def validate_confidence_range(min_conf: Optional[str], max_conf: Optional[str]) -> Tuple[Optional[float], Optional[float], Optional[str]]:
+    """
+    Validate confidence range parameters.
+    
+    Returns:
+        Tuple of (min_confidence, max_confidence, error_message)
+    """
+    min_val = None
+    max_val = None
+    
+    if min_conf:
+        try:
+            min_val = float(min_conf)
+            if not 0 <= min_val <= 1:
+                return None, None, "min_confidence must be between 0 and 1"
+        except ValueError:
+            return None, None, "Invalid min_confidence parameter. Must be a number."
+    
+    if max_conf:
+        try:
+            max_val = float(max_conf)
+            if not 0 <= max_val <= 1:
+                return None, None, "max_confidence must be between 0 and 1"
+        except ValueError:
+            return None, None, "Invalid max_confidence parameter. Must be a number."
+    
+    if min_val is not None and max_val is not None and min_val > max_val:
+        return None, None, "min_confidence cannot be greater than max_confidence"
+    
+    return min_val, max_val, None

app/vit_utils.py

@@ -0,0 +1,323 @@
+# app/vit_utils.py
+"""
+Utilities for Vision Transformer (ViT) model preprocessing and prediction.
+"""
+import cv2
+import numpy as np
+from PIL import Image
+from typing import Optional, Tuple, Dict, Any
+from app.utils import preprocess_face  # Reuse face detection
+
+def preprocess_face_for_vit(
+    image_path: str,
+    detect_max_dim: int = 800,
+    pad_ratio: float = 0.35,  # Increased to 0.35 to include more facial context - helps with happy detection (smile needs more context)
+) -> Tuple[Optional[Image.Image], Optional[str]]:
+    """
+    Preprocess face for Vision Transformer model.
+    ViT needs RGB images at 224x224, not grayscale 48x48.
+    
+    Returns: (PIL Image, filename) or (None, None) if no face detected
+    """
+    # First detect and crop face (reuse existing detection logic)
+    # But we'll keep it in RGB and resize to 224x224
+    try:
+        img = cv2.imread(image_path)
+        if img is None:
+            return None, None
+
+        h0, w0 = img.shape[:2]
+        # Keep RGB for ViT (not grayscale)
+        img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+        gray_full = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+
+        # Downscale for faster detection if image is huge
+        scale = 1.0
+        max_side = max(w0, h0)
+        if max_side > detect_max_dim:
+            scale = detect_max_dim / float(max_side)
+            small = cv2.resize(gray_full, (int(w0 * scale), int(h0 * scale)), interpolation=cv2.INTER_LINEAR)
+        else:
+            small = gray_full.copy()
+
+        # Enhance for detection
+        from app.utils import _enhance_for_detection
+        small_enh = _enhance_for_detection(small)
+
+        # Optimized face detection: 2 cascades × 2 param sets = 4 attempts (fast)
+        # Then fallback to 3rd cascade if needed = +2 attempts (total 6 max)
+        # This balances speed (4 attempts) with reliability (6 attempts if needed)
+        cascade_paths_primary = [
+            "haarcascade_frontalface_default.xml",  # Most reliable
+            "haarcascade_frontalface_alt.xml",      # Good fallback
+        ]
+        
+        cascade_paths_fallback = [
+            "haarcascade_frontalface_alt2.xml",     # Last resort
+        ]
+        
+        faces = []
+        
+        # Primary: Try 2 cascades with 2 param sets each (4 attempts, fast path)
+        for cascade_name in cascade_paths_primary:
+            if len(faces) > 0:
+                break
+            try:
+                face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + cascade_name)
+                if face_cascade.empty():
+                    continue
+                
+                # Attempt 1: Most common successful params (catches 90%+ of faces)
+                faces = face_cascade.detectMultiScale(
+                    small_enh,
+                    scaleFactor=1.05,
+                    minNeighbors=3,
+                    minSize=(20, 20),
+                    flags=cv2.CASCADE_SCALE_IMAGE,
+                )
+                
+                # Attempt 2: More permissive (catches challenging cases)
+                if len(faces) == 0:
+                    faces = face_cascade.detectMultiScale(
+                        small_enh,
+                        scaleFactor=1.03,
+                        minNeighbors=2,
+                        minSize=(15, 15),
+                        flags=cv2.CASCADE_SCALE_IMAGE,
+                    )
+                    
+            except Exception:
+                continue
+        
+        # Fallback: Only try 3rd cascade if primary failed (adds 2 more attempts)
+        if len(faces) == 0:
+            for cascade_name in cascade_paths_fallback:
+                if len(faces) > 0:
+                    break
+                try:
+                    face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + cascade_name)
+                    if face_cascade.empty():
+                        continue
+                    
+                    # Try with permissive params
+                    for scale_factor, min_neighbors, min_size in [
+                        (1.05, 3, (20, 20)),
+                        (1.03, 2, (15, 15)),
+                    ]:
+                        faces = face_cascade.detectMultiScale(
+                            small_enh,
+                            scaleFactor=scale_factor,
+                            minNeighbors=min_neighbors,
+                            minSize=min_size,
+                            flags=cv2.CASCADE_SCALE_IMAGE,
+                        )
+                        if len(faces) > 0:
+                            break
+                except Exception:
+                    continue
+        
+        # Fallback 1: Try on original (non-enhanced) image if enhanced failed
+        # Only try once with best params (don't waste time on multiple attempts)
+        if len(faces) == 0:
+            try:
+                face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + "haarcascade_frontalface_default.xml")
+                if not face_cascade.empty():
+                    # Single attempt with most successful params (faster than trying multiple)
+                    faces = face_cascade.detectMultiScale(
+                        small,  # Use original, not enhanced
+                        scaleFactor=1.05,
+                        minNeighbors=3,
+                        minSize=(20, 20),
+                        flags=cv2.CASCADE_SCALE_IMAGE,
+                    )
+            except Exception:
+                pass
+        
+        # Fallback 2: Try on full-size image ONLY if:
+        # 1. Still no face found
+        # 2. Image was actually downscaled (max_side > 800)
+        # 3. Scale is significantly reduced (scale < 0.5, meaning image is 2x+ larger)
+        # This prevents slow full-size detection on images that are only slightly over 800px
+        if len(faces) == 0 and max_side > detect_max_dim and scale < 0.5:
+            try:
+                face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + "haarcascade_frontalface_default.xml")
+                if not face_cascade.empty():
+                    # Single attempt with permissive params (full-size is slow, so only try once)
+                    faces = face_cascade.detectMultiScale(
+                        gray_full,
+                        scaleFactor=1.05,
+                        minNeighbors=2,
+                        minSize=(30, 30),  # Larger min size for full-res
+                        flags=cv2.CASCADE_SCALE_IMAGE,
+                    )
+            except Exception:
+                pass
+        
+        if len(faces) == 0:
+            return None, None
+
+        # Choose largest face
+        faces = sorted(faces, key=lambda r: r[2] * r[3], reverse=True)
+        (x_s, y_s, w_s, h_s) = faces[0]
+
+        # Map back to original scale (only if we used downscaled detection)
+        # If we detected on full-size image, coordinates are already correct
+        if max_side > detect_max_dim and scale < 1.0:
+            # Detection was on downscaled image
+            x = int(x_s / scale)
+            y = int(y_s / scale)
+            w = int(w_s / scale)
+            h = int(h_s / scale)
+        else:
+            # Detection was on full-size or original scale
+            x = x_s
+            y = y_s
+            w = w_s
+            h = h_s
+
+        # Pad bounding box
+        pad_w = int(w * pad_ratio)
+        pad_h = int(h * pad_ratio)
+        x1 = max(0, x - pad_w)
+        y1 = max(0, y - pad_h)
+        x2 = min(w0, x + w + pad_w)
+        y2 = min(h0, y + h + pad_h)
+
+        # Crop face from RGB image (not grayscale)
+        face_crop = img_rgb[y1:y2, x1:x2]
+        
+        # Convert to PIL Image and resize to 224x224 (ViT input size)
+        # Use BICUBIC for best quality (emotion recognition needs detail)
+        # Note: ViT processor handles normalization, so we don't apply CLAHE here
+        # CLAHE can interfere with the model's expected input distribution
+        face_pil = Image.fromarray(face_crop)
+        face_pil = face_pil.resize((224, 224), Image.Resampling.BICUBIC)
+
+        import os
+        used_filename = os.path.basename(image_path) or "upload.jpg"
+        return face_pil, used_filename
+
+    except Exception as e:
+        import logging
+        logger = logging.getLogger(__name__)
+        logger.exception(f"Exception in preprocess_face_for_vit for {image_path}: {e}")
+        return None, None
+
+def predict_with_vit(
+    model_dict: Dict[str, Any],
+    image: Image.Image,
+    labels: list
+) -> Tuple[int, float, Dict[str, float]]:
+    """
+    Run prediction using Vision Transformer model.
+    Enhanced for better accuracy with image preprocessing.
+    
+    Args:
+        model_dict: {'model': model, 'processor': processor, 'type': 'vit'}
+        image: PIL Image (224x224 RGB)
+        labels: List of emotion labels
+    
+    Returns:
+        (predicted_index, confidence, all_probabilities_dict)
+    """
+    processor = model_dict['processor']
+    model = model_dict['model']
+    
+    # Ensure image is RGB (some images might be RGBA or grayscale)
+    if image.mode != 'RGB':
+        image = image.convert('RGB')
+    
+    # Preprocess image for ViT (processor handles normalization)
+    inputs = processor(image, return_tensors="pt")
+    
+    # Run prediction - optimized for speed
+    import torch
+    import torch.nn.functional as F
+    
+    model.eval()
+    # Use inference_mode() instead of no_grad() - faster for inference-only
+    with torch.inference_mode():  # Faster than no_grad() for pure inference
+        outputs = model(**inputs)
+        logits = outputs.logits
+    
+    # Get probabilities (softmax) - optimized conversion
+    probs = F.softmax(logits, dim=-1)
+    probs_np = probs[0].cpu().numpy()  # Direct indexing, no detach needed in inference_mode
+    
+    # Get predicted class
+    predicted_idx = int(torch.argmax(logits, dim=-1).item())
+    confidence = float(probs_np[predicted_idx])
+    
+    # Create probabilities dict - use model's id2label directly to ensure correct mapping
+    all_probs = {}
+    model = model_dict['model']
+    for i, prob in enumerate(probs_np):
+        # Use model's id2label for accurate label mapping
+        if hasattr(model, 'config') and hasattr(model.config, 'id2label'):
+            raw_label = model.config.id2label.get(i, f"class_{i}")
+            # Normalize label name
+            label_map = {
+                'anger': 'angry',
+                'disgust': 'disgust',
+                'fear': 'fear',
+                'happy': 'happy',
+                'neutral': 'neutral',
+                'sad': 'sad',
+                'surprise': 'surprise',
+                'contempt': 'contempt'
+            }
+            normalized_label = label_map.get(raw_label.lower(), raw_label.lower())
+            all_probs[normalized_label] = float(prob)
+        elif i < len(labels):
+            all_probs[labels[i]] = float(prob)
+        else:
+            all_probs[f"class_{i}"] = float(prob)
+    
+    # Post-processing: If happy probability is reasonable (>0.05) but contempt/neutral is high,
+    # and happy is in top 3, boost happy probability (model has known happy/contempt confusion)
+    happy_prob = all_probs.get('happy', 0.0)
+    contempt_prob = all_probs.get('contempt', 0.0)
+    neutral_prob = all_probs.get('neutral', 0.0)
+    
+    # If happy is in top 3 probabilities and contempt/neutral is suspiciously high
+    sorted_probs = sorted(all_probs.items(), key=lambda x: x[1], reverse=True)
+    top_3_emotions = [e[0] for e in sorted_probs[:3]]
+    
+    if 'happy' in top_3_emotions and happy_prob > 0.05:
+        # If contempt or neutral is highest but happy is close, boost happy
+        if (contempt_prob > 0.4 or neutral_prob > 0.4) and happy_prob > 0.05:
+            # Boost happy by 30% (helps correct misclassifications)
+            boost_factor = 1.3
+            boosted_happy = min(1.0, happy_prob * boost_factor)
+            
+            # Reduce contempt/neutral proportionally to maintain probability sum
+            reduction = (boosted_happy - happy_prob) / 2
+            new_contempt = max(0.0, contempt_prob - reduction)
+            new_neutral = max(0.0, neutral_prob - reduction)
+            
+            # Update probabilities
+            all_probs['happy'] = boosted_happy
+            all_probs['contempt'] = new_contempt
+            all_probs['neutral'] = new_neutral
+            
+            # Re-normalize to ensure sum is ~1.0
+            total = sum(all_probs.values())
+            if total > 0:
+                all_probs = {k: v / total for k, v in all_probs.items()}
+            
+            # Recalculate predicted class after boosting - find emotion with highest prob
+            new_top_emotion = max(all_probs.items(), key=lambda x: x[1])[0]
+            
+            # Find index in labels list
+            if new_top_emotion in labels:
+                predicted_idx = labels.index(new_top_emotion)
+                confidence = all_probs[new_top_emotion]
+                print(f"[VIT] Post-processing: Boosted happy from {happy_prob:.3f} to {all_probs.get('happy', 0.0):.3f}, new prediction: {new_top_emotion}")
+            else:
+                # Fallback to original prediction if label not found
+                print(f"[VIT] Post-processing: Boosted happy but couldn't find label {new_top_emotion} in labels list")
+    
+    print(f"[VIT] Predicted index: {predicted_idx}, Raw label from model: {model.config.id2label.get(predicted_idx, 'unknown')}")
+    
+    return predicted_idx, confidence, all_probs
+

entrypoint_hf.sh

@@ -0,0 +1,79 @@
+#!/bin/sh
+set -eu
+
+# Where the app expects the model inside the container
+MODEL_PATH="/app/models/emotion_model.keras"
+
+# Public release URL (change if you host elsewhere)
+MODEL_URL="https://github.com/iyinoluwAA/Emotion-detection/releases/download/v1.0.0/emotion_model.keras"
+
+# Ensure models dir exists
+mkdir -p "$(dirname "$MODEL_PATH")"
+
+if [ ! -f "$MODEL_PATH" ]; then
+  echo "Model not found at $MODEL_PATH — attempting download from $MODEL_URL"
+  if command -v curl >/dev/null 2>&1; then
+    curl -fSL "$MODEL_URL" -o "$MODEL_PATH" || {
+      echo "curl failed to download model"; ls -la "$(dirname "$MODEL_PATH")"; exit 1;
+    }
+  elif command -v wget >/dev/null 2>&1; then
+    wget -O "$MODEL_PATH" "$MODEL_URL" || {
+      echo "wget failed to download model"; ls -la "$(dirname "$MODEL_PATH")"; exit 1;
+    }
+  else
+    echo "No curl or wget available in the image. Install one in Dockerfile."; exit 1
+  fi
+else
+  echo "Model already present at $MODEL_PATH"
+fi
+
+# ensure readable
+chmod a+r "$MODEL_PATH" || true
+
+# Download Asripa model (fine-tuned) if not present
+ASRIPA_MODEL_DIR="/app/models/fine_tuned_vit"
+ASRIPA_MODEL_ID="${ASRIPA_MODEL_ID:-HimAJ/asripa-emotion-detection}"
+
+if [ -n "$ASRIPA_MODEL_ID" ] && [ ! -f "$ASRIPA_MODEL_DIR/model.safetensors" ]; then
+  echo "📥 Downloading Asripa model from HuggingFace..."
+  echo "   Model ID: $ASRIPA_MODEL_ID"
+  mkdir -p "$ASRIPA_MODEL_DIR"
+  
+  # Use Python to download (huggingface_hub is in requirements)
+  python3 -c "
+from huggingface_hub import snapshot_download
+import os
+import sys
+try:
+    snapshot_download(
+        repo_id='$ASRIPA_MODEL_ID',
+        local_dir='$ASRIPA_MODEL_DIR',
+        local_dir_use_symlinks=False
+    )
+    print('✅ Asripa model downloaded successfully!')
+except Exception as e:
+    print(f'⚠️  Failed to download Asripa model: {e}')
+    print('   App will use base model only')
+    import shutil
+    if os.path.exists('$ASRIPA_MODEL_DIR'):
+        shutil.rmtree('$ASRIPA_MODEL_DIR')
+    sys.exit(0)  # Exit gracefully, not an error
+" || {
+    echo "⚠️  Asripa model download skipped"
+    echo "   App will use base model only"
+    rm -rf "$ASRIPA_MODEL_DIR" 2>/dev/null || true
+  }
+elif [ -f "$ASRIPA_MODEL_DIR/model.safetensors" ]; then
+  echo "✅ Asripa model already present"
+elif [ -z "$ASRIPA_MODEL_ID" ]; then
+  echo "ℹ️  ASRIPA_MODEL_ID not set - skipping Asripa model download"
+fi
+
+# Hugging Face Spaces uses port 7860 by default
+# But we'll use PORT env var if set, otherwise default to 7860
+PORT="${PORT:-7860}"
+echo "Starting gunicorn on 0.0.0.0:${PORT}"
+# Suppress protobuf warnings
+export PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python
+exec gunicorn main:app --bind 0.0.0.0:"${PORT}" --workers 1 --threads 1 --timeout 120 --worker-class gthread
+

main.py

@@ -0,0 +1,41 @@
+# main.py
+import os
+import logging
+import warnings
+
+# Suppress protobuf version warnings (they're harmless but noisy)
+warnings.filterwarnings("ignore", category=UserWarning, module="google.protobuf")
+os.environ["PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION"] = "python"
+
+# Make PROJECT_ROOT explicit so module-level code in the container works reliably
+PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
+
+# Ensure logs dir exists
+LOG_DIR = os.path.join(PROJECT_ROOT, "logs")
+os.makedirs(LOG_DIR, exist_ok=True)
+
+# Configure file logging (keeps container stdout clean and persists errors)
+logfile = os.path.join(LOG_DIR, "app.log")
+handler = logging.FileHandler(logfile)
+handler.setLevel(logging.INFO)
+formatter = logging.Formatter("%(asctime)s [%(levelname)s] %(module)s: %(message)s")
+handler.setFormatter(formatter)
+
+root_logger = logging.getLogger()
+# Add handler only if not already added (avoids duplicates in dev reload)
+if not any(isinstance(h, logging.FileHandler) and getattr(h, "baseFilename", "") == logfile for h in root_logger.handlers):
+    root_logger.addHandler(handler)
+
+# Import factory after logging and directory setup so imports don't crash during bootstrap
+from app import create_app
+
+# Create app (allow env-driven config if needed)
+app = create_app()
+
+if __name__ == "__main__":
+    # allow overriding host/port via env (useful in Docker)
+    host = os.environ.get("HOST", "0.0.0.0")
+    port = int(os.environ.get("PORT", os.environ.get("FLASK_RUN_PORT", 5000)))
+    debug = os.environ.get("FLASK_DEBUG", "0") in ("1", "true", "True")
+    app.logger.info("Starting app on %s:%s (debug=%s)", host, port, debug)
+    app.run(host=host, port=port, debug=debug)

requirements.txt

@@ -0,0 +1,18 @@
+Flask==3.1.1
+flask-cors==4.0.0
+
+# ML helpers (no TF/numpy here)
+# Note: numpy<2 required for opencv-python-headless compatibility
+numpy>=1.26.0,<2.0.0
+h5py>=3.7.0
+Pillow>=9.0.0
+opencv-python-headless==4.9.0.80
+
+# Vision Transformer support (for HardlyHumans model - 92.2% accuracy)
+transformers>=4.30.0
+torch>=2.0.0
+huggingface_hub>=0.20.0  # For downloading Asripa model
+
+# utilities & production
+requests>=2.28.0
+gunicorn>=23.0.0