feat: add diagnostic tools and configuration for timeout and memory issues in HF Spaces

DIAGNOSTIC_README.md

@@ -0,0 +1,197 @@
+# 🔍 Diagnostic Guide: Timeout vs Memory
+
+## How to identify the problem?
+
+### 1️⃣ Run the diagnostic tool
+
+In your HF Space, execute:
+
+```bash
+python hf-spaces/diagnostic_tool.py
+```
+
+This tool will tell you **exactly** if the problem is:
+- ❌ **MEMORY_ERROR**: The system ran out of RAM
+- ⏰ **TIMEOUT_ERROR**: The operation took too long
+- ❓ **OTHER_ERROR**: Another type of problem
+
+### 2️⃣ Interpret the results
+
+#### If you see "MEMORY_ERROR":
+```
+❌ PROBLEM DETECTED: OUT OF MEMORY
+Memory used at failure: 15.8 GB (98.5%)
+```
+
+**Cause**: The model is too large for the available memory in HF Spaces.
+
+**Solutions**:
+1. **Use smaller models** (1B-1.7B parameters)
+2. **Upgrade to HF Spaces PRO** (more RAM available)
+3. **Use int8 quantization** (reduces memory usage ~50%)
+4. **Load models with `low_cpu_mem_usage=True`**
+
+#### If you see "TIMEOUT_ERROR":
+```
+⏰ TIMEOUT ERROR after 298.5s
+Memory used: 8.2 GB (51.2%)
+```
+
+**Cause**: The model takes too long to load, but there is available memory.
+
+**Solutions**:
+1. **Increase timeout** from 300s to 600s or 900s
+2. **Cache pre-loaded models** at startup
+3. **Use faster models**
+
+## 🛠️ Implemented Solutions
+
+### Solution 1: Increase Timeout (Easy)
+
+Edit `hf-spaces/optipfair_frontend.py`:
+
+```python
+# Change from:
+response = requests.post(url, json=payload, timeout=300)
+
+# To:
+response = requests.post(url, json=payload, timeout=600)  # 10 minutes
+```
+
+### Solution 2: Use Quantization (For memory issues)
+
+Edit model loading code in the backend:
+
+```python
+from transformers import AutoModel, BitsAndBytesConfig
+
+# Configure int8 quantization (reduces memory usage ~50%)
+quantization_config = BitsAndBytesConfig(
+    load_in_8bit=True,
+    llm_int8_threshold=6.0,
+)
+
+model = AutoModel.from_pretrained(
+    model_name,
+    quantization_config=quantization_config,
+    device_map="auto",
+    low_cpu_mem_usage=True,
+)
+```
+
+### Solution 3: Model Cache (For timeout)
+
+Pre-load models at startup in `hf-spaces/app.py`:
+
+```python
+from transformers import AutoModel, AutoTokenizer
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Global model cache
+MODEL_CACHE = {}
+
+def preload_models():
+    """Pre-load common models at startup"""
+    common_models = [
+        "meta-llama/Llama-3.2-1B",
+        "oopere/pruned40-llama-3.2-1B",
+    ]
+    
+    logger.info("🔄 Pre-loading common models...")
+    for model_name in common_models:
+        try:
+            logger.info(f"  Loading {model_name}...")
+            MODEL_CACHE[model_name] = {
+                "model": AutoModel.from_pretrained(model_name, low_cpu_mem_usage=True),
+                "tokenizer": AutoTokenizer.from_pretrained(model_name)
+            }
+            logger.info(f"  ✓ {model_name} loaded")
+        except Exception as e:
+            logger.warning(f"  ✗ Could not pre-load {model_name}: {e}")
+    
+    logger.info("✅ Pre-loading complete")
+
+def main():
+    # Pre-load models before starting services
+    preload_models()
+    
+    # Rest of the code...
+    fastapi_thread = threading.Thread(target=run_fastapi, daemon=True)
+    fastapi_thread.start()
+    # ...
+```
+
+### Solution 4: Improved Error Messages
+
+Better error messages are already included to help you identify the problem:
+
+```python
+except requests.exceptions.Timeout:
+    return (
+        None,
+        "❌ **Timeout Error:**\nThe model took too long to load (>5min). "
+        "This is normal with large models. Options:\n"
+        "1. Try with a smaller model\n"
+        "2. Wait and try again (model may be caching)\n"
+        "3. Contact admin to increase timeout",
+        ""
+    )
+
+except MemoryError:
+    return (
+        None,
+        "❌ **Memory Error:**\nNot enough RAM for this model. Options:\n"
+        "1. Use a smaller model (1B parameters)\n"
+        "2. Model requires more memory than available in HF Spaces",
+        ""
+    )
+```
+
+## 📊 Model Size Comparison
+
+| Model | Parameters | RAM Needed* | Load Time** |
+|--------|-----------|----------------|----------------|
+| Llama-3.2-1B | 1B | ~4 GB | ~30s |
+| Llama-3.2-3B | 3B | ~12 GB | ~90s |
+| Llama-3-8B | 8B | ~32 GB | ~240s |
+| Llama-3-70B | 70B | ~280 GB | ~600s+ |
+
+*Without quantization, FP32
+**On typical HF Spaces hardware
+
+## 🎯 Recommended Action Plan
+
+1. **Run the diagnostic**:
+   ```bash
+   python hf-spaces/diagnostic_tool.py
+   ```
+
+2. **Read the results** and follow the specific recommendations
+
+3. **Apply the appropriate solution**:
+   - If timeout → Increase timeout or use cache
+   - If memory → Use small models or quantization
+
+4. **Test again** with the adjusted configuration
+
+## 📝 Useful Logs in HF Spaces
+
+Check the logs in HF Spaces for messages like:
+
+```
+🔍 MODEL LOADING DIAGNOSTIC: meta-llama/Llama-3.2-1B
+📊 INITIAL SYSTEM STATE:
+  - Available memory: 12.50 GB
+  - Used memory: 3.45 GB (21.6%)
+⏳ Starting model loading (timeout: 300s)...
+  [1/2] Loading tokenizer...
+  ✓ Tokenizer loaded in 2.31s
+  - Memory used: 3.48 GB (21.8%)
+  [2/2] Loading model...
+  ✓ Model loaded in 45.67s
+✅ LOADING SUCCESSFUL in 47.98s
+```
+
+This tells you exactly how much memory and time each step uses.

README_DIAGNOSTICS.md

@@ -0,0 +1,257 @@
+# 🔍 Timeout vs Memory Diagnostic Tools
+
+## Overview
+
+When working with heavy models in HF Spaces, you may encounter issues that could be caused by:
+1. **Timeout**: The model takes too long to load (>5 minutes)
+2. **Memory**: The system runs out of RAM
+3. **Both**: A combination of both issues
+
+This toolkit helps you identify and fix the exact problem.
+
+## 📁 Files Added
+
+### 1. `diagnostic_tool.py`
+**Purpose**: Identify if the problem is timeout or memory
+
+**Usage**:
+```bash
+python hf-spaces/diagnostic_tool.py
+```
+
+**What it does**:
+- Monitors system memory in real-time
+- Tracks model loading time
+- Detects the exact failure point
+- Provides specific recommendations
+
+**Output**:
+```
+🔍 MODEL LOADING DIAGNOSTIC: meta-llama/Llama-3.2-1B
+📊 INITIAL SYSTEM STATE:
+  - Available memory: 12.50 GB
+  - Used memory: 3.45 GB (21.6%)
+⏳ Starting model loading (timeout: 300s)...
+  [1/2] Loading tokenizer...
+  ✓ Tokenizer loaded in 2.31s
+  [2/2] Loading model...
+  ✓ Model loaded in 45.67s
+✅ LOADING SUCCESSFUL in 47.98s
+
+💡 RECOMMENDATIONS
+✅ Model loaded successfully.
+```
+
+### 2. `config_optimized.py`
+**Purpose**: Smart configuration based on model size
+
+**Features**:
+- Auto-detects model size category (small/medium/large)
+- Provides optimized timeout settings
+- Recommends appropriate HF Spaces tier
+- Warns about memory issues before loading
+
+**Usage**:
+```python
+from config_optimized import HFSpacesConfig, get_optimized_request_config
+
+# Get optimal timeout for a model
+timeout = HFSpacesConfig.get_timeout_for_model("meta-llama/Llama-3.2-1B")
+
+# Get full request config
+config = get_optimized_request_config("meta-llama/Llama-3.2-1B")
+response = requests.post(url, json=payload, **config)
+
+# Check if model is recommended for your tier
+is_ok = HFSpacesConfig.is_model_recommended("meta-llama/Llama-3.2-1B", tier="free")
+```
+
+### 3. `DIAGNOSTIC_README.md`
+**Purpose**: Complete guide with solutions
+
+**Contents**:
+- How to identify timeout vs memory issues
+- Step-by-step solutions for each problem
+- Model size comparison table
+- Code examples for fixes
+- Best practices
+
+### 4. Improved Error Messages in `optipfair_frontend.py`
+**What changed**:
+- More informative timeout error messages
+- Explicit memory error detection
+- Actionable recommendations in errors
+- All messages in English
+
+**Example**:
+```
+❌ **Timeout Error:**
+The request exceeded 5 minutes (300s).
+
+**Possible causes:**
+1. The model is very large and takes long to load
+2. The server is processing many requests
+
+**Solutions:**
+• Use a smaller model (1B parameters)
+• Wait and try again (model may be caching)
+• If it persists, run `diagnostic_tool.py` for more information
+```
+
+## 🚀 Quick Start Guide
+
+### Step 1: Diagnose the Problem
+```bash
+cd hf-spaces
+python diagnostic_tool.py
+```
+
+### Step 2: Read the Output
+The tool will tell you:
+- ✅ **Success**: Model loads fine
+- ❌ **MEMORY_ERROR**: Need more RAM or smaller model
+- ⏰ **TIMEOUT_ERROR**: Need more time or faster model
+
+### Step 3: Apply the Solution
+
+#### For TIMEOUT problems:
+```python
+# Option 1: Increase timeout in optipfair_frontend.py
+response = requests.post(
+    url,
+    json=payload,
+    timeout=600  # Change from 300 to 600 seconds
+)
+
+# Option 2: Use config_optimized.py
+from config_optimized import get_optimized_request_config
+config = get_optimized_request_config(model_name)
+response = requests.post(url, json=payload, **config)
+```
+
+#### For MEMORY problems:
+```python
+# Option 1: Use smaller model
+AVAILABLE_MODELS = [
+    "meta-llama/Llama-3.2-1B",  # ✅ Works on free tier
+    "oopere/pruned40-llama-3.2-1B",  # ✅ Works on free tier
+]
+
+# Option 2: Use quantization (in backend)
+from transformers import AutoModel, BitsAndBytesConfig
+
+quantization_config = BitsAndBytesConfig(load_in_8bit=True)
+model = AutoModel.from_pretrained(
+    model_name,
+    quantization_config=quantization_config,
+    low_cpu_mem_usage=True,
+)
+
+# Option 3: Upgrade HF Spaces tier
+# Free: 16GB RAM → PRO: 32GB RAM → Enterprise: 64GB RAM
+```
+
+## 📊 Model Recommendations by Tier
+
+### Free Tier (16GB RAM)
+✅ **Recommended**:
+- meta-llama/Llama-3.2-1B (~4 GB, ~30s load)
+- oopere/pruned40-llama-3.2-1B (~4 GB, ~30s load)
+- google/gemma-3-1b-pt (~4 GB, ~30s load)
+- Qwen/Qwen3-1.7B (~6 GB, ~45s load)
+
+⚠️ **May work with optimization**:
+- meta-llama/Llama-3.2-3B (~12 GB, ~90s load)
+
+❌ **Won't work**:
+- meta-llama/Llama-3-8B (~32 GB)
+- meta-llama/Llama-3-70B (~280 GB)
+
+### PRO Tier (32GB RAM)
+✅ **Additional models**:
+- meta-llama/Llama-3.2-3B
+- meta-llama/Llama-3-8B (with quantization)
+
+### Enterprise Tier (64GB RAM)
+✅ **Additional models**:
+- meta-llama/Llama-3-8B (full precision)
+- Larger models with quantization
+
+## 🎯 Common Scenarios
+
+### Scenario 1: "My model times out after 5 minutes"
+**Diagnosis**: TIMEOUT_ERROR
+
+**Solution**:
+1. Check if model is too large for your tier
+2. Increase timeout to 600s (10 minutes)
+3. Consider pre-loading models at startup
+
+### Scenario 2: "Process crashes without clear error"
+**Diagnosis**: Likely MEMORY_ERROR (Out-Of-Memory kills the process)
+
+**Solution**:
+1. Run `diagnostic_tool.py` to confirm
+2. Use smaller model (1B parameters)
+3. Use int8 quantization
+4. Upgrade to PRO tier
+
+### Scenario 3: "Sometimes works, sometimes doesn't"
+**Diagnosis**: Memory pressure or concurrent requests
+
+**Solution**:
+1. Implement model caching
+2. Add memory monitoring
+3. Use smaller default model
+
+## 🛠️ Advanced: Pre-loading Models
+
+To avoid timeout on first request, pre-load models at startup:
+
+```python
+# In hf-spaces/app.py
+from transformers import AutoModel, AutoTokenizer
+
+MODEL_CACHE = {}
+
+def preload_models():
+    """Pre-load common models at startup"""
+    models = ["meta-llama/Llama-3.2-1B"]
+    
+    for model_name in models:
+        try:
+            print(f"Pre-loading {model_name}...")
+            MODEL_CACHE[model_name] = {
+                "model": AutoModel.from_pretrained(
+                    model_name,
+                    low_cpu_mem_usage=True
+                ),
+                "tokenizer": AutoTokenizer.from_pretrained(model_name)
+            }
+            print(f"✓ {model_name} ready")
+        except Exception as e:
+            print(f"✗ Could not pre-load {model_name}: {e}")
+
+def main():
+    preload_models()  # Load models before starting services
+    # ... rest of startup code
+```
+
+## 📞 Support
+
+If you still have issues after trying these solutions:
+
+1. Check the full diagnostic output
+2. Review HF Spaces logs
+3. Verify your HF Spaces tier and limits
+4. Consider using a different model architecture
+
+## 📝 Summary
+
+| Issue | Symptom | Solution |
+|-------|---------|----------|
+| **Timeout** | Request > 5 min | Increase timeout, use cache |
+| **Memory** | Process crashes/kills | Smaller model, quantization, upgrade tier |
+| **Both** | Slow + crashes | Smaller model + longer timeout |
+
+All tools are designed to help you quickly identify and fix the exact problem without guessing.

config_optimized.py

@@ -0,0 +1,173 @@
+"""
+Optimized configuration for HF Spaces with intelligent handling of large models.
+This file contains recommended settings based on available hardware.
+"""
+
+import os
+from typing import Dict, Any
+
+
+class HFSpacesConfig:
+    """Optimized configuration for different HF Spaces tiers"""
+    
+    # Timeouts (in seconds)
+    TIMEOUT_SMALL_MODEL = 120    # Models <2B parameters
+    TIMEOUT_MEDIUM_MODEL = 300   # Models 2-5B parameters
+    TIMEOUT_LARGE_MODEL = 600    # Models >5B parameters
+    TIMEOUT_PING = 5             # Health checks
+    
+    # Recommended memory limits (GB) per HF Spaces tier
+    MEMORY_LIMITS = {
+        "free": 16,      # Free HF Spaces
+        "pro": 32,       # HF Spaces PRO
+        "enterprise": 64 # HF Spaces Enterprise
+    }
+    
+    # Recommended models per tier
+    RECOMMENDED_MODELS = {
+        "free": [
+            "meta-llama/Llama-3.2-1B",
+            "oopere/pruned40-llama-3.2-1B", 
+            "oopere/Fair-Llama-3.2-1B",
+            "google/gemma-3-1b-pt",
+            "Qwen/Qwen3-1.7B",
+        ],
+        "pro": [
+            "meta-llama/Llama-3.2-3B",
+            "meta-llama/Llama-3-8B",
+        ],
+        "enterprise": [
+            "meta-llama/Llama-3-70B",
+        ]
+    }
+    
+    # Model loading configuration
+    MODEL_LOAD_CONFIG = {
+        "small": {  # <2B params
+            "low_cpu_mem_usage": True,
+            "torch_dtype": "auto",
+            "device_map": "auto",
+            "timeout": TIMEOUT_SMALL_MODEL,
+        },
+        "medium": {  # 2-8B params
+            "low_cpu_mem_usage": True,
+            "torch_dtype": "float16",  # Reduces memory
+            "device_map": "auto",
+            "timeout": TIMEOUT_MEDIUM_MODEL,
+        },
+        "large": {  # >8B params
+            "low_cpu_mem_usage": True,
+            "torch_dtype": "float16",
+            "device_map": "auto",
+            "load_in_8bit": True,  # int8 quantization
+            "timeout": TIMEOUT_LARGE_MODEL,
+        }
+    }
+    
+    @classmethod
+    def get_model_size_category(cls, model_name: str) -> str:
+        """
+        Determines the model size category based on the name.
+        
+        Returns:
+            "small", "medium", or "large"
+        """
+        model_lower = model_name.lower()
+        
+        # Detect by parameters in the name
+        if any(size in model_lower for size in ["1b", "1.7b", "1.5b"]):
+            return "small"
+        elif any(size in model_lower for size in ["3b", "7b", "8b"]):
+            return "medium"
+        elif any(size in model_lower for size in ["13b", "30b", "70b"]):
+            return "large"
+        
+        # Default: small (assume the safest case)
+        return "small"
+    
+    @classmethod
+    def get_timeout_for_model(cls, model_name: str) -> int:
+        """Gets the recommended timeout for a model."""
+        size = cls.get_model_size_category(model_name)
+        return cls.MODEL_LOAD_CONFIG[size]["timeout"]
+    
+    @classmethod
+    def get_load_config(cls, model_name: str) -> Dict[str, Any]:
+        """Gets the optimized loading configuration for a model."""
+        size = cls.get_model_size_category(model_name)
+        return cls.MODEL_LOAD_CONFIG[size].copy()
+    
+    @classmethod
+    def is_model_recommended(cls, model_name: str, tier: str = "free") -> bool:
+        """Verifies if a model is recommended for the current tier."""
+        return model_name in cls.RECOMMENDED_MODELS.get(tier, [])
+    
+    @classmethod
+    def get_memory_warning(cls, model_name: str, tier: str = "free") -> str:
+        """
+        Generates a warning if the model may exceed memory limits.
+        
+        Returns:
+            String with warning, or empty string if no problem
+        """
+        if cls.is_model_recommended(model_name, tier):
+            return ""
+        
+        size = cls.get_model_size_category(model_name)
+        
+        if size == "medium" and tier == "free":
+            return (
+                "⚠️ **Warning**: This model may be too large for free HF Spaces. "
+                "Consider upgrading to HF Spaces PRO or using a smaller model."
+            )
+        elif size == "large" and tier in ["free", "pro"]:
+            return (
+                "❌ **Error**: This model is too large for your HF Spaces tier. "
+                "Use a smaller model or upgrade to Enterprise."
+            )
+        
+        return ""
+
+
+# Usage example:
+def get_optimized_request_config(model_name: str) -> dict:
+    """
+    Gets optimized configuration for HTTP requests based on the model.
+    
+    Usage:
+        config = get_optimized_request_config("meta-llama/Llama-3.2-1B")
+        response = requests.post(url, json=payload, **config)
+    """
+    return {
+        "timeout": HFSpacesConfig.get_timeout_for_model(model_name),
+    }
+
+
+# Default configuration for general use
+DEFAULT_CONFIG = {
+    "timeout": HFSpacesConfig.TIMEOUT_MEDIUM_MODEL,
+    "max_retries": 2,
+    "retry_delay": 5,  # seconds between retries
+}
+
+
+if __name__ == "__main__":
+    # Usage examples
+    print("🔧 Optimized configuration for HF Spaces\n")
+    
+    test_models = [
+        "meta-llama/Llama-3.2-1B",
+        "meta-llama/Llama-3.2-3B", 
+        "meta-llama/Llama-3-8B",
+    ]
+    
+    for model in test_models:
+        print(f"📦 Model: {model}")
+        print(f"   Category: {HFSpacesConfig.get_model_size_category(model)}")
+        print(f"   Timeout: {HFSpacesConfig.get_timeout_for_model(model)}s")
+        print(f"   Recommended (free): {HFSpacesConfig.is_model_recommended(model, 'free')}")
+        
+        warning = HFSpacesConfig.get_memory_warning(model, "free")
+        if warning:
+            print(f"   {warning}")
+        print()

diagnostic_tool.py

@@ -0,0 +1,270 @@
+"""
+Diagnostic tool to identify timeout vs memory issues in HF Spaces.
+Run this script in HF Spaces to get detailed performance information.
+"""
+
+import psutil
+import time
+import sys
+import traceback
+from datetime import datetime
+
+
+def get_memory_info():
+    """Gets detailed information about system memory usage."""
+    memory = psutil.virtual_memory()
+    return {
+        "total_gb": memory.total / (1024**3),
+        "available_gb": memory.available / (1024**3),
+        "used_gb": memory.used / (1024**3),
+        "percent_used": memory.percent,
+        "free_gb": memory.free / (1024**3),
+    }
+
+
+def get_cpu_info():
+    """Gets information about CPU usage."""
+    return {
+        "cpu_percent": psutil.cpu_percent(interval=1),
+        "cpu_count": psutil.cpu_count(),
+        "load_avg": psutil.getloadavg() if hasattr(psutil, "getloadavg") else None,
+    }
+
+
+def monitor_model_loading(model_name: str, timeout_seconds: int = 300):
+    """
+    Monitors model loading and detects if it fails due to timeout or memory.
+    
+    Args:
+        model_name: HuggingFace model name to load
+        timeout_seconds: Maximum wait time in seconds
+        
+    Returns:
+        dict with diagnostic information
+    """
+    print(f"\n{'='*60}")
+    print(f"🔍 MODEL LOADING DIAGNOSTIC: {model_name}")
+    print(f"{'='*60}\n")
+
+    # Initial system state
+    print("📊 INITIAL SYSTEM STATE:")
+    mem_before = get_memory_info()
+    cpu_before = get_cpu_info()
+    print(f"  - Available memory: {mem_before['available_gb']:.2f} GB")
+    print(f"  - Used memory: {mem_before['used_gb']:.2f} GB ({mem_before['percent_used']:.1f}%)")
+    print(f"  - Available CPUs: {cpu_before['cpu_count']} cores")
+    print(f"  - CPU usage: {cpu_before['cpu_percent']:.1f}%")
+    
+    start_time = time.time()
+    result = {
+        "model_name": model_name,
+        "success": False,
+        "error_type": None,
+        "error_message": None,
+        "elapsed_time": 0,
+        "memory_before": mem_before,
+        "memory_after": None,
+        "memory_peak": mem_before["used_gb"],
+        "timeout_seconds": timeout_seconds,
+    }
+
+    try:
+        print(f"\n⏳ Starting model loading (timeout: {timeout_seconds}s)...")
+        print(f"   Start time: {datetime.now().strftime('%H:%M:%S')}")
+        
+        # Import transformers here to measure its impact
+        from transformers import AutoModel, AutoTokenizer
+        
+        # Real-time monitoring
+        model = None
+        tokenizer = None
+        last_memory_check = time.time()
+        
+        print("\n📈 REAL-TIME MONITORING:")
+        
+        # Load tokenizer first (faster)
+        print("  [1/2] Loading tokenizer...")
+        tokenizer_start = time.time()
+        tokenizer = AutoTokenizer.from_pretrained(model_name)
+        tokenizer_time = time.time() - tokenizer_start
+        print(f"  ✓ Tokenizer loaded in {tokenizer_time:.2f}s")
+        
+        # Check memory after tokenizer
+        mem_after_tokenizer = get_memory_info()
+        print(f"  - Memory used: {mem_after_tokenizer['used_gb']:.2f} GB ({mem_after_tokenizer['percent_used']:.1f}%)")
+        
+        # Load model (can be slow)
+        print("\n  [2/2] Loading model...")
+        model_start = time.time()
+        
+        # Load with low memory usage if possible
+        model = AutoModel.from_pretrained(
+            model_name,
+            low_cpu_mem_usage=True,  # Reduces memory usage during loading
+            torch_dtype="auto",
+        )
+        
+        model_time = time.time() - model_start
+        total_time = time.time() - start_time
+        
+        print(f"  ✓ Model loaded in {model_time:.2f}s")
+        print(f"\n✅ LOADING SUCCESSFUL in {total_time:.2f}s")
+        
+        # Final system state
+        mem_after = get_memory_info()
+        cpu_after = get_cpu_info()
+        
+        print(f"\n📊 FINAL SYSTEM STATE:")
+        print(f"  - Available memory: {mem_after['available_gb']:.2f} GB")
+        print(f"  - Used memory: {mem_after['used_gb']:.2f} GB ({mem_after['percent_used']:.1f}%)")
+        print(f"  - Memory increase: {mem_after['used_gb'] - mem_before['used_gb']:.2f} GB")
+        print(f"  - CPU usage: {cpu_after['cpu_percent']:.1f}%")
+        
+        result["success"] = True
+        result["elapsed_time"] = total_time
+        result["memory_after"] = mem_after
+        result["tokenizer_time"] = tokenizer_time
+        result["model_time"] = model_time
+        
+    except MemoryError as e:
+        elapsed = time.time() - start_time
+        mem_current = get_memory_info()
+        
+        print(f"\n❌ MEMORY ERROR after {elapsed:.2f}s")
+        print(f"   Memory used at failure: {mem_current['used_gb']:.2f} GB ({mem_current['percent_used']:.1f}%)")
+        
+        result["error_type"] = "MEMORY_ERROR"
+        result["error_message"] = str(e)
+        result["elapsed_time"] = elapsed
+        result["memory_after"] = mem_current
+        
+    except TimeoutError as e:
+        elapsed = time.time() - start_time
+        mem_current = get_memory_info()
+        
+        print(f"\n⏰ TIMEOUT ERROR after {elapsed:.2f}s")
+        print(f"   Memory used: {mem_current['used_gb']:.2f} GB ({mem_current['percent_used']:.1f}%)")
+        
+        result["error_type"] = "TIMEOUT_ERROR"
+        result["error_message"] = str(e)
+        result["elapsed_time"] = elapsed
+        result["memory_after"] = mem_current
+        
+    except Exception as e:
+        elapsed = time.time() - start_time
+        mem_current = get_memory_info()
+        
+        print(f"\n❌ UNEXPECTED ERROR after {elapsed:.2f}s")
+        print(f"   Type: {type(e).__name__}")
+        print(f"   Message: {str(e)}")
+        print(f"   Memory used: {mem_current['used_gb']:.2f} GB ({mem_current['percent_used']:.1f}%)")
+        
+        # Analyze error message to detect memory issues
+        error_msg = str(e).lower()
+        if any(keyword in error_msg for keyword in ["memory", "ram", "oom", "out of memory"]):
+            result["error_type"] = "MEMORY_ERROR"
+            print("\n🔍 DIAGNOSIS: Error appears to be MEMORY related")
+        elif "timeout" in error_msg or elapsed >= timeout_seconds * 0.95:
+            result["error_type"] = "TIMEOUT_ERROR"
+            print("\n🔍 DIAGNOSIS: Error appears to be TIMEOUT related")
+        else:
+            result["error_type"] = "OTHER_ERROR"
+        
+        result["error_message"] = str(e)
+        result["elapsed_time"] = elapsed
+        result["memory_after"] = mem_current
+        result["traceback"] = traceback.format_exc()
+        
+    return result
+
+
+def print_recommendations(result: dict):
+    """Prints recommendations based on diagnostic results."""
+    print(f"\n{'='*60}")
+    print("💡 RECOMMENDATIONS")
+    print(f"{'='*60}\n")
+    
+    if result["success"]:
+        print("✅ Model loaded successfully.")
+        print(f"   Total time: {result['elapsed_time']:.2f}s")
+        
+        if result["elapsed_time"] > 240:  # > 4 minutes
+            print("\n⚠️  Warning: Load time is very high (>4min)")
+            print("   - Consider increasing timeout to 600s (10 minutes)")
+            print("   - Or use a smaller model")
+            
+    elif result["error_type"] == "MEMORY_ERROR":
+        print("❌ PROBLEM DETECTED: OUT OF MEMORY\n")
+        print("Solutions:")
+        print("  1. Use a smaller model (1B or 1.7B parameters)")
+        print("  2. Request more memory in HF Spaces (PRO plan)")
+        print("  3. Use quantization (int8 or int4) to reduce memory usage:")
+        print("     ```python")
+        print("     from transformers import BitsAndBytesConfig")
+        print("     quantization_config = BitsAndBytesConfig(load_in_8bit=True)")
+        print("     model = AutoModel.from_pretrained(model_name, quantization_config=quantization_config)")
+        print("     ```")
+        
+        if result["memory_after"]:
+            print(f"\n  Available memory: {result['memory_after']['available_gb']:.2f} GB")
+            print(f"  More memory needed for this model")
+            
+    elif result["error_type"] == "TIMEOUT_ERROR":
+        print("❌ PROBLEM DETECTED: TIMEOUT\n")
+        print("Solutions:")
+        print(f"  1. Increase timeout from {result['timeout_seconds']}s to 600s (10 minutes):")
+        print("     ```python")
+        print("     response = requests.post(url, json=payload, timeout=600)")
+        print("     ```")
+        print("  2. Implement async loading with progress updates")
+        print("  3. Cache pre-loaded models in HF Spaces")
+        print("  4. Use smaller models that load faster")
+        
+    else:
+        print("❌ PROBLEM DETECTED: UNEXPECTED ERROR\n")
+        print("Review the full traceback for more details")
+        if "traceback" in result:
+            print("\n" + result["traceback"])
+    
+    print(f"\n{'='*60}\n")
+
+
+if __name__ == "__main__":
+    # Models to test (from smallest to largest)
+    test_models = [
+        "meta-llama/Llama-3.2-1B",  # Small model
+        # "meta-llama/Llama-3.2-3B",  # Medium model (uncomment to test)
+        # "meta-llama/Llama-3-8B",     # Large model (uncomment to test)
+    ]
+    
+    # You can change the timeout here
+    TIMEOUT = 300  # 5 minutes
+    
+    results = []
+    
+    for model_name in test_models:
+        result = monitor_model_loading(model_name, timeout_seconds=TIMEOUT)
+        results.append(result)
+        print_recommendations(result)
+        
+        # If failed, don't test larger models
+        if not result["success"]:
+            print("\n⚠️  Stopping tests due to error.")
+            print("    Larger models will likely fail as well.")
+            break
+        
+        # Wait a bit between tests
+        time.sleep(2)
+    
+    # Final summary
+    print(f"\n{'='*60}")
+    print("📋 TEST SUMMARY")
+    print(f"{'='*60}\n")
+    
+    for i, result in enumerate(results, 1):
+        status = "✅" if result["success"] else "❌"
+        time_str = f"{result['elapsed_time']:.1f}s"
+        print(f"{status} Test {i}: {result['model_name']}")
+        print(f"   Time: {time_str} | Error: {result['error_type'] or 'None'}")
+        
+    print()