fix: Add wait_for_model, debug endpoint, and better HF API error handling

src/app.py

@@ -53,7 +53,8 @@ HUGGINGFACE_SUMMARIZATION_REPO = os.environ.get(
 
 # When HF_API_TOKEN is set, use remote HF Inference API instead of local models.
 # This avoids loading 500MB+ models into RAM on the free tier.
-USE_HF_API = bool(os.environ.get('HF_API_TOKEN', ''))
+HF_API_TOKEN = os.environ.get('HF_API_TOKEN', '')
+USE_HF_API = bool(HF_API_TOKEN)
 
 # Configure logging
 logging.basicConfig(
@@ -172,6 +173,22 @@ def health_check():
     return jsonify(health), status_code
 
 
+@app.route('/api/debug-models', methods=['GET'])
+def debug_models():
+    """Debug endpoint: test all HF models and return actual errors."""
+    if not USE_HF_API:
+        return jsonify({'error': 'Not in HF API mode', 'mode': 'local'}), 400
+    
+    from hf_inference import debug_test_all_models
+    results = debug_test_all_models()
+    return jsonify({
+        'status': 'debug',
+        'hf_api_token_set': bool(HF_API_TOKEN),
+        'hf_api_token_prefix': HF_API_TOKEN[:10] + '...' if HF_API_TOKEN else 'NOT SET',
+        'models': results,
+    }), 200
+
+
 @app.route('/api/summarize', methods=['POST'])
 def summarize():
     """

src/hf_inference.py

@@ -25,9 +25,7 @@ HF_API_TOKEN = os.environ.get("HF_API_TOKEN", "")
 HF_API_BASE = "https://api-inference.huggingface.co/models/"
 
 # Timeout for inference calls (seconds)
-# First call may be slow (cold start = model loading on HF servers)
-HF_TIMEOUT_FIRST = 120   # 2 min for cold start
-HF_TIMEOUT_NORMAL = 60   # 1 min for warm model
+HF_TIMEOUT = 120  # 2 min — accounts for cold starts
 
 
 def _build_headers():
@@ -38,65 +36,52 @@ def _build_headers():
     return headers
 
 
-def _call_hf_api(repo_id, payload, timeout=HF_TIMEOUT_NORMAL, retries=2):
+def _call_hf_api(repo_id, payload, timeout=HF_TIMEOUT):
     """
     Call HuggingFace Inference API.
-    
-    Handles cold starts by retrying when model is loading.
+
+    Sends wait_for_model=true to handle cold starts automatically
+    (HF will wait up to ~2min for the model to load instead of 503).
     Returns parsed JSON response or raises Exception.
     """
     url = HF_API_BASE + repo_id
     headers = _build_headers()
+
+    # Tell HF to wait for the model to load instead of returning 503
+    if "options" not in payload:
+        payload["options"] = {"wait_for_model": True}
+    else:
+        payload["options"]["wait_for_model"] = True
+
     data = json.dumps(payload).encode("utf-8")
-    
     ctx = ssl.create_default_context()
-    
-    for attempt in range(retries + 1):
-        try:
-            req = urllib.request.Request(url, data=data, headers=headers, method="POST")
-            resp = urllib.request.urlopen(req, timeout=timeout, context=ctx)
-            result = json.loads(resp.read().decode("utf-8"))
-            return result
-            
-        except urllib.error.HTTPError as e:
-            body = e.read().decode("utf-8", errors="replace")
-            
-            # Model is loading (cold start) — wait and retry
-            if e.code == 503 and "loading" in body.lower():
-                try:
-                    wait_data = json.loads(body)
-                    wait_time = wait_data.get("estimated_time", 30)
-                except (json.JSONDecodeError, KeyError):
-                    wait_time = 30
-                    
-                logger.info(
-                    "Model %s is loading (attempt %d/%d), waiting %.0fs...",
-                    repo_id, attempt + 1, retries + 1, wait_time
-                )
-                time.sleep(min(wait_time, 60))
-                continue
-            
-            # Other HTTP error
-            logger.error("HF API error for %s: HTTP %d — %s", repo_id, e.code, body[:200])
-            raise RuntimeError(
-                "HF Inference API error (HTTP {}): {}".format(e.code, body[:200])
-            )
-            
-        except Exception as e:
-            if attempt < retries:
-                logger.warning("HF API call failed (attempt %d): %s", attempt + 1, str(e))
-                time.sleep(5)
-                continue
-            raise
-    
-    raise RuntimeError("HF Inference API: max retries exceeded for " + repo_id)
+
+    logger.info("Calling HF API: %s (payload keys: %s)", repo_id, list(payload.keys()))
+
+    try:
+        req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+        resp = urllib.request.urlopen(req, timeout=timeout, context=ctx)
+        body = resp.read().decode("utf-8")
+        result = json.loads(body)
+        logger.info("HF API success for %s: response type=%s", repo_id, type(result).__name__)
+        return result
+
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")
+        logger.error("HF API error for %s: HTTP %d — %s", repo_id, e.code, body[:500])
+        raise RuntimeError(
+            "HF API error for {} (HTTP {}): {}".format(repo_id, e.code, body[:300])
+        )
+
+    except Exception as e:
+        logger.error("HF API exception for %s: %s", repo_id, str(e))
+        raise
 
 
 # ============================================================
 # Model-specific wrappers
 # ============================================================
 
-# --- Repository IDs ---
 SUMMARIZATION_REPO = os.environ.get("SUMMARIZATION_REPO_ID", "bayan10/summarization-model")
 SPELLING_REPO = os.environ.get("SPELLING_REPO_ID", "bayan10/AraSpell-Model")
 PUNCTUATION_REPO = os.environ.get("PUNCTUATION_REPO_ID", "bayan10/PuncAra-v1")
@@ -104,10 +89,7 @@ AUTOCOMPLETE_REPO = os.environ.get("AUTOCOMPLETE_REPO_ID", "bayan10/AutoComplete
 
 
 def hf_summarize(text, max_length=128, min_length=30):
-    """
-    Summarize Arabic text via HF Inference API.
-    Returns the summary string.
-    """
+    """Summarize Arabic text via HF Inference API."""
     payload = {
         "inputs": text,
         "parameters": {
@@ -115,73 +97,67 @@ def hf_summarize(text, max_length=128, min_length=30):
             "min_length": min_length,
         }
     }
-    
-    result = _call_hf_api(SUMMARIZATION_REPO, payload, timeout=HF_TIMEOUT_FIRST)
-    
+
+    result = _call_hf_api(SUMMARIZATION_REPO, payload)
+
     # HF summarization returns: [{"summary_text": "..."}]
     if isinstance(result, list) and len(result) > 0:
-        return result[0].get("summary_text", "")
-    
-    # Fallback: might return {"generated_text": "..."}
+        return result[0].get("summary_text", result[0].get("generated_text", ""))
+
     if isinstance(result, dict):
         return result.get("summary_text", result.get("generated_text", str(result)))
-    
+
     return str(result)
 
 
 def hf_correct_spelling(text):
-    """
-    Correct spelling in Arabic text via HF Inference API.
-    Returns the corrected string.
-    """
+    """Correct spelling in Arabic text via HF Inference API."""
     payload = {"inputs": text}
-    
-    result = _call_hf_api(SPELLING_REPO, payload, timeout=HF_TIMEOUT_FIRST)
-    
-    # Text2text models return: [{"generated_text": "..."}]
+
+    result = _call_hf_api(SPELLING_REPO, payload)
+
+    # Text2text / seq2seq models return: [{"generated_text": "..."}]
     if isinstance(result, list) and len(result) > 0:
-        return result[0].get("generated_text", text)
-    
+        item = result[0]
+        if isinstance(item, dict):
+            return item.get("generated_text", item.get("translation_text", text))
+        return str(item)
+
     if isinstance(result, dict):
-        return result.get("generated_text", text)
-    
+        return result.get("generated_text", result.get("translation_text", text))
+
     return text
 
 
 def hf_add_punctuation(text):
-    """
-    Add punctuation to Arabic text via HF Inference API.
-    Returns the punctuated string.
-    """
+    """Add punctuation to Arabic text via HF Inference API."""
     payload = {"inputs": text}
-    
-    result = _call_hf_api(PUNCTUATION_REPO, payload, timeout=HF_TIMEOUT_FIRST)
-    
-    # Encoder-decoder models return: [{"generated_text": "..."}]
+
+    result = _call_hf_api(PUNCTUATION_REPO, payload)
+
     if isinstance(result, list) and len(result) > 0:
-        return result[0].get("generated_text", text)
-    
+        item = result[0]
+        if isinstance(item, dict):
+            return item.get("generated_text", item.get("translation_text", text))
+        return str(item)
+
     if isinstance(result, dict):
-        return result.get("generated_text", text)
-    
+        return result.get("generated_text", result.get("translation_text", text))
+
     return text
 
 
 def hf_autocomplete(text, n=5):
-    """
-    Get autocomplete suggestions for Arabic text via HF Inference API.
-    Returns a list of suggestion strings.
-    """
+    """Get autocomplete suggestions for Arabic text via HF Inference API."""
     payload = {
         "inputs": text,
         "parameters": {
-            "num_return_sequences": min(n, 5),
             "max_new_tokens": 20,
         }
     }
-    
-    result = _call_hf_api(AUTOCOMPLETE_REPO, payload, timeout=HF_TIMEOUT_FIRST)
-    
+
+    result = _call_hf_api(AUTOCOMPLETE_REPO, payload)
+
     # Text generation returns: [{"generated_text": "..."}]
     if isinstance(result, list):
         suggestions = []
@@ -194,22 +170,51 @@ def hf_autocomplete(text, n=5):
                 if gen:
                     suggestions.append(gen)
         return suggestions if suggestions else [text]
-    
+
     return [text]
 
 
 def check_hf_api_available():
-    """
-    Quick check if HF Inference API is reachable.
-    Returns True if API responds, False otherwise.
-    """
+    """Quick check if HF Inference API is reachable."""
     try:
         url = HF_API_BASE + SUMMARIZATION_REPO
         headers = _build_headers()
-        # Use GET to just check if model exists (won't trigger inference)
         req = urllib.request.Request(url, headers=headers, method="GET")
         ctx = ssl.create_default_context()
         resp = urllib.request.urlopen(req, timeout=10, context=ctx)
         return resp.status == 200
     except Exception:
         return False
+
+
+def debug_test_all_models():
+    """
+    Test all HF models and return results dict.
+    Used by /api/debug-models endpoint for troubleshooting.
+    """
+    results = {}
+    test_text = "هذا نص تجريبي للاختبار"
+
+    for name, fn, args in [
+        ("summarization", hf_summarize, (test_text + " " + test_text * 3, 30, 10)),
+        ("spelling", hf_correct_spelling, (test_text,)),
+        ("punctuation", hf_add_punctuation, (test_text,)),
+        ("autocomplete", hf_autocomplete, (test_text, 3)),
+    ]:
+        try:
+            t0 = time.time()
+            result = fn(*args)
+            elapsed = time.time() - t0
+            results[name] = {
+                "status": "ok",
+                "result": str(result)[:200],
+                "time_seconds": round(elapsed, 2),
+            }
+        except Exception as e:
+            results[name] = {
+                "status": "error",
+                "error": str(e)[:500],
+            }
+
+    return results
+