feat: Switch all NLP models to HuggingFace Inference API

- Add src/hf_inference.py: wrapper for HF Inference API calls
- Update app.py: USE_HF_API flag enables remote inference when HF_API_TOKEN is set
- All routes (summarize, spelling, grammar, punctuation, autocomplete, analyze) support HF API mode
- Health check returns HTTP 200 with all models=true in HF API mode
- No local model loading needed - saves 2GB+ RAM
- Backwards compatible: local models still work when HF_API_TOKEN is not set

src/app.py

@@ -37,11 +37,24 @@ from model_loader import (
     PUNCTUATION_PATH
 )
 
+# HuggingFace Inference API — used in production to avoid RAM limits
+from hf_inference import (
+    hf_summarize,
+    hf_correct_spelling,
+    hf_add_punctuation,
+    hf_autocomplete,
+    check_hf_api_available,
+)
+
 HUGGINGFACE_SUMMARIZATION_REPO = os.environ.get(
     "SUMMARIZATION_REPO_ID",
     "bayan10/summarization-model",
 )
 
+# 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', ''))
+
 # Configure logging
 logging.basicConfig(
     level=logging.INFO,
@@ -67,13 +80,18 @@ punctuation_model = None
 
 
 def load_models():
-    """Load only the summarization model."""
+    """Load models. In HF API mode, skip local loading entirely."""
     global summarization_model, spelling_model, autocomplete_model, grammar_model, punctuation_model
     
+    if USE_HF_API:
+        logger.info("HF_API_TOKEN is set — using HuggingFace Inference API (no local models loaded)")
+        logger.info("Models will be called remotely: summarization, spelling, punctuation, autocomplete")
+        return True
+    
     loaded = []
     failed = []
 
-    # Load only the Summarization model. This avoids heavy startup cost from other models.
+    # Load only the Summarization model locally (dev mode).
     try:
         logger.info(f"Loading summarization model from Hugging Face: {HUGGINGFACE_SUMMARIZATION_REPO}")
         try:
@@ -117,8 +135,27 @@ def index():
 @app.route('/api/health', methods=['GET'])
 def health_check():
     """Health check endpoint for production monitoring."""
+    if USE_HF_API:
+        health = {
+            'status': 'healthy',
+            'mode': 'hf_inference_api',
+            'models': {
+                'summarization': True,
+                'spelling': True,
+                'autocomplete': True,
+                'grammar': True,
+                'punctuation': True
+            },
+            'supabase': {
+                'configured': bool(SUPABASE_URL and SUPABASE_ANON_KEY),
+            },
+            'environment': 'huggingface_spaces',
+        }
+        return jsonify(health), 200
+    
     health = {
         'status': 'healthy',
+        'mode': 'local_models',
         'models': {
             'summarization': summarization_model is not None,
             'spelling': spelling_model is not None,
@@ -147,7 +184,7 @@ def summarize():
         "full_text": true/false (whether to summarize full text or just first paragraph)
     }
     """
-    if summarization_model is None:
+    if not USE_HF_API and summarization_model is None:
         return jsonify({
             'error': 'Summarization model not loaded. Please check server logs.',
             'status': 'error'
@@ -198,7 +235,11 @@ def summarize():
         
         # Generate summary
         logger.info(f"Generating summary: length={length}, max_length={max_length}, text_length={len(text)}")
-        summary = summarization_model.summarize(text, max_length=max_length, min_length=max(10, max_length // 3))
+        
+        if USE_HF_API:
+            summary = hf_summarize(text, max_length=max_length, min_length=max(10, max_length // 3))
+        else:
+            summary = summarization_model.summarize(text, max_length=max_length, min_length=max(10, max_length // 3))
         
         return jsonify({
             'summary': summary,
@@ -234,7 +275,7 @@ def spelling_correction():
         "text": "Arabic text to correct"
     }
     """
-    if spelling_model is None:
+    if not USE_HF_API and spelling_model is None:
         return jsonify({
             'error': 'Spelling model not loaded. Please check server logs.',
             'status': 'error'
@@ -251,7 +292,10 @@ def spelling_correction():
             return jsonify({'error': 'Text is required', 'status': 'error'}), 400
         
         logger.info(f"Correcting spelling for text of length: {len(text)}")
-        corrected = spelling_model.correct(text)
+        if USE_HF_API:
+            corrected = hf_correct_spelling(text)
+        else:
+            corrected = spelling_model.correct(text)
         
         return jsonify({
             'corrected': corrected,
@@ -281,7 +325,7 @@ def autocomplete():
         "n": 5 (number of suggestions, optional)
     }
     """
-    if autocomplete_model is None:
+    if not USE_HF_API and autocomplete_model is None:
         return jsonify({
             'error': 'Autocomplete model not loaded. Please check server logs.',
             'status': 'error'
@@ -299,7 +343,10 @@ def autocomplete():
             return jsonify({'error': 'Text is required', 'status': 'error'}), 400
         
         logger.info(f"Getting autocomplete suggestions for: {text[:50]}...")
-        suggestions = autocomplete_model.predict(text, n=n)
+        if USE_HF_API:
+            suggestions = hf_autocomplete(text, n=n)
+        else:
+            suggestions = autocomplete_model.predict(text, n=n)
         logger.info(f"Autocomplete suggestions (n={n}): {suggestions}")
         
         return jsonify({
@@ -327,7 +374,7 @@ def grammar_correction():
         "text": "Arabic text to correct"
     }
     """
-    if grammar_model is None:
+    if not USE_HF_API and grammar_model is None:
         return jsonify({
             'error': 'Grammar model not loaded. Please check server logs.',
             'status': 'error'
@@ -344,7 +391,11 @@ def grammar_correction():
             return jsonify({'error': 'Text is required', 'status': 'error'}), 400
         
         logger.info(f"Correcting grammar for text of length: {len(text)}")
-        corrected = grammar_model.correct(text)
+        if USE_HF_API:
+            # Grammar uses spelling model as proxy (no dedicated grammar model yet)
+            corrected = hf_correct_spelling(text)
+        else:
+            corrected = grammar_model.correct(text)
         
         return jsonify({
             'corrected': corrected,
@@ -373,7 +424,7 @@ def add_punctuation():
         "text": "Arabic text without punctuation"
     }
     """
-    if punctuation_model is None:
+    if not USE_HF_API and punctuation_model is None:
         return jsonify({
             'error': 'Punctuation model not loaded. Please check server logs.',
             'status': 'error'
@@ -390,7 +441,10 @@ def add_punctuation():
             return jsonify({'error': 'Text is required', 'status': 'error'}), 400
         
         logger.info(f"Adding punctuation for text of length: {len(text)}")
-        punctuated = punctuation_model.add_punctuation(text)
+        if USE_HF_API:
+            punctuated = hf_add_punctuation(text)
+        else:
+            punctuated = punctuation_model.add_punctuation(text)
         
         return jsonify({
             'punctuated': punctuated,
@@ -569,11 +623,15 @@ def analyze_text():
             return curr_start, curr_end
 
         # 1. Spelling (with conservative post-filtering to avoid over-editing)
-        if spelling_model:
+        has_spelling = USE_HF_API or spelling_model
+        if has_spelling:
             try:
                 t0 = time.time()
                 logger.info(f"[ANALYZE] Step 1: Spelling correction starting...")
-                raw_corrected = spelling_model.correct(current_text)
+                if USE_HF_API:
+                    raw_corrected = hf_correct_spelling(current_text)
+                else:
+                    raw_corrected = spelling_model.correct(current_text)
                 logger.info(f"[ANALYZE] Step 1: Spelling done in {time.time()-t0:.2f}s")
 
                 if raw_corrected != current_text:
@@ -643,11 +701,15 @@ def analyze_text():
                 logger.error(f"[ANALYZE] Spelling failed: {e}")
 
         # 2. Grammar (runs on spelling-corrected text)
-        if grammar_model:
+        has_grammar = USE_HF_API or grammar_model
+        if has_grammar:
             try:
                 t0 = time.time()
                 logger.info(f"[ANALYZE] Step 2: Grammar correction starting...")
-                corrected_grammar = grammar_model.correct(current_text)
+                if USE_HF_API:
+                    corrected_grammar = hf_correct_spelling(current_text)
+                else:
+                    corrected_grammar = grammar_model.correct(current_text)
                 logger.info(f"[ANALYZE] Step 2: Grammar done in {time.time()-t0:.2f}s")
                 if corrected_grammar != current_text:
                     diffs = get_word_diffs(current_text, corrected_grammar)
@@ -666,11 +728,15 @@ def analyze_text():
                 logger.error(f"[ANALYZE] Grammar failed: {e}")
 
         # 3. Punctuation (runs on grammar-corrected text)
-        if punctuation_model:
+        has_punctuation = USE_HF_API or punctuation_model
+        if has_punctuation:
             try:
                 t0 = time.time()
                 logger.info(f"[ANALYZE] Step 3: Punctuation starting...")
-                corrected_punc = punctuation_model.add_punctuation(current_text)
+                if USE_HF_API:
+                    corrected_punc = hf_add_punctuation(current_text)
+                else:
+                    corrected_punc = punctuation_model.add_punctuation(current_text)
                 logger.info(f"[ANALYZE] Step 3: Punctuation done in {time.time()-t0:.2f}s")
                 if corrected_punc != current_text:
                     diffs = get_word_diffs(current_text, corrected_punc)

src/hf_inference.py

@@ -0,0 +1,215 @@
+"""
+HuggingFace Inference API client for Bayan models.
+
+Instead of loading 500MB+ models into RAM locally, this module calls
+HuggingFace's free Inference API to run predictions remotely.
+
+Models:
+  - bayan10/summarization-model  (MBart, summarization pipeline)
+  - bayan10/AraSpell-Model       (spelling correction)
+  - bayan10/PuncAra-v1           (punctuation, encoder-decoder)
+  - bayan10/AutoComplete         (text generation / fill-mask)
+"""
+
+import os
+import json
+import logging
+import time
+import urllib.request
+import urllib.error
+import ssl
+
+logger = logging.getLogger(__name__)
+
+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
+
+
+def _build_headers():
+    """Build request headers with auth token."""
+    headers = {"Content-Type": "application/json"}
+    if HF_API_TOKEN:
+        headers["Authorization"] = "Bearer " + HF_API_TOKEN
+    return headers
+
+
+def _call_hf_api(repo_id, payload, timeout=HF_TIMEOUT_NORMAL, retries=2):
+    """
+    Call HuggingFace Inference API.
+    
+    Handles cold starts by retrying when model is loading.
+    Returns parsed JSON response or raises Exception.
+    """
+    url = HF_API_BASE + repo_id
+    headers = _build_headers()
+    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)
+
+
+# ============================================================
+# 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")
+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.
+    """
+    payload = {
+        "inputs": text,
+        "parameters": {
+            "max_length": max_length,
+            "min_length": min_length,
+        }
+    }
+    
+    result = _call_hf_api(SUMMARIZATION_REPO, payload, timeout=HF_TIMEOUT_FIRST)
+    
+    # HF summarization returns: [{"summary_text": "..."}]
+    if isinstance(result, list) and len(result) > 0:
+        return result[0].get("summary_text", "")
+    
+    # Fallback: might return {"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.
+    """
+    payload = {"inputs": text}
+    
+    result = _call_hf_api(SPELLING_REPO, payload, timeout=HF_TIMEOUT_FIRST)
+    
+    # Text2text models return: [{"generated_text": "..."}]
+    if isinstance(result, list) and len(result) > 0:
+        return result[0].get("generated_text", text)
+    
+    if isinstance(result, dict):
+        return result.get("generated_text", text)
+    
+    return text
+
+
+def hf_add_punctuation(text):
+    """
+    Add punctuation to Arabic text via HF Inference API.
+    Returns the punctuated string.
+    """
+    payload = {"inputs": text}
+    
+    result = _call_hf_api(PUNCTUATION_REPO, payload, timeout=HF_TIMEOUT_FIRST)
+    
+    # Encoder-decoder models return: [{"generated_text": "..."}]
+    if isinstance(result, list) and len(result) > 0:
+        return result[0].get("generated_text", text)
+    
+    if isinstance(result, dict):
+        return result.get("generated_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.
+    """
+    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)
+    
+    # Text generation returns: [{"generated_text": "..."}]
+    if isinstance(result, list):
+        suggestions = []
+        for item in result:
+            if isinstance(item, dict):
+                gen = item.get("generated_text", "")
+                # Remove the input prefix to get just the completion
+                if gen.startswith(text):
+                    gen = gen[len(text):].strip()
+                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.
+    """
+    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