Sync card and scripts from the monorepo

README.md

@@ -4,19 +4,12 @@ emoji: 💻
 colorFrom: green
 colorTo: blue
 sdk: gradio
-sdk_version: 5.50.0
+sdk_version: 5.31.0
 python_version: "3.10"
 app_file: app.py
 pinned: false
 license: mit
 short_description: AI-powered code explanation and documentation
-tags:
-  - code
-  - education
-  - llm
-  - developer-tools
-models:
-  - mistralai/Mistral-7B-Instruct-v0.3
 ---
 
 # Code Explainer
@@ -36,10 +29,10 @@ Choose your expertise level:
 
 ### Structured Output
 Each explanation includes:
-- **Overview** - What the code does at a high level
-- **Line-by-Line Breakdown** - Detailed explanation of each part
+- **Overview** - A brief summary of what the code does
+- **Step-by-Step Breakdown** - Section-by-section explanation of the code
 - **Key Concepts** - Important programming concepts used
-- **Potential Issues** - Common pitfalls or improvements
+- **Potential Improvements** - Suggested improvements, best practices, or issues to be aware of
 
 ### Syntax Highlighting
 Code is displayed with proper syntax highlighting for readability.
@@ -55,7 +48,7 @@ Code is displayed with proper syntax highlighting for readability.
 
 | Component | Technology |
 |-----------|------------|
-| Web Framework | Gradio 5.9.1 |
+| Web Framework | Gradio 5.31.0 |
 | AI Model | Mistral-7B via HuggingFace Inference API |
 | Code Formatting | Pygments |
 
@@ -72,6 +65,10 @@ Code is displayed with proper syntax highlighting for readability.
 - Complex multi-file projects may need to be explained piece by piece
 - AI explanations should be verified for critical code
 
+## Configuration
+
+This Space calls the **HuggingFace Inference API** (Mistral-7B). It requires an `HF_TOKEN` secret — a token with inference access — set in **Space Settings → Secrets**. Without it, generation will fail.
+
 ## License
 
 MIT

app.py

@@ -2,12 +2,15 @@
 Code Explainer - AI-powered code explanation using HuggingFace Inference API.
 """
 
+import html
+
 import gradio as gr
-from huggingface_hub import InferenceClient
 from pygments import highlight
 from pygments.lexers import get_lexer_by_name, guess_lexer
 from pygments.formatters import HtmlFormatter
 
+from hf_client import InferenceError, make_client, with_retry
+
 # ---------------------------------------------------------------------------
 # Configuration
 # ---------------------------------------------------------------------------
@@ -43,7 +46,7 @@ EXPLANATION_LEVELS = {
 # Initialize client
 # ---------------------------------------------------------------------------
 
-client = InferenceClient(MODEL_ID)
+client = make_client(MODEL_ID)
 
 # ---------------------------------------------------------------------------
 # Utility functions
@@ -77,7 +80,7 @@ def format_code_html(code: str, language: str) -> str:
         formatter = HtmlFormatter(style="monokai", noclasses=True)
         return highlight(code, lexer, formatter)
     except Exception:
-        return f"<pre><code>{code}</code></pre>"
+        return f"<pre><code>{html.escape(code)}</code></pre>"
 
 
 # ---------------------------------------------------------------------------
@@ -96,12 +99,12 @@ def explain_code(code: str, language: str, level: str) -> tuple[str, str]:
 
     # Build prompt
     level_instruction = EXPLANATION_LEVELS.get(level, EXPLANATION_LEVELS["Intermediate"])
+    lexer_hint = detected_lang.split()[0].lower() if detected_lang.strip() else ""
 
-    prompt = f"""You are an expert programming tutor. {level_instruction}
+    system_prompt = f"You are an expert programming tutor. {level_instruction}"
+    user_prompt = f"""Explain the following code.
 
-Here is the code to explain:
-
-```{detected_lang.lower()}
+```{lexer_hint}
 {code}
 ```
 
@@ -122,16 +125,17 @@ Suggest any improvements, best practices, or potential issues to be aware of.
 Keep your explanation clear, accurate, and educational."""
 
     try:
-        # Call the inference API
-        response = client.text_generation(
-            prompt,
-            max_new_tokens=1500,
+        completion = with_retry(
+            client.chat_completion,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            max_tokens=1500,
             temperature=0.7,
             top_p=0.95,
-            do_sample=True,
         )
-
-        explanation = response.strip()
+        explanation = completion.choices[0].message.content.strip()
 
         # Add language badge
         explanation = f"**Detected Language:** `{detected_lang}`\n\n---\n\n{explanation}"
@@ -141,9 +145,8 @@ Keep your explanation clear, accurate, and educational."""
 
         return explanation, formatted_code
 
-    except Exception as e:
-        error_msg = f"Error generating explanation: {str(e)}"
-        return error_msg, format_code_html(code, detected_lang)
+    except InferenceError as e:
+        return f"**{e}**", format_code_html(code, detected_lang)
 
 
 # ---------------------------------------------------------------------------

hf_client.py

@@ -0,0 +1,121 @@
+"""Helpers for talking to the HuggingFace Inference API.
+
+Centralises the three things every Space here needs and previously got wrong:
+
+* **Authentication** -- reads ``HF_TOKEN`` from the environment. The serverless
+  Inference Providers backend rejects most anonymous calls (401/402), so a token
+  is effectively required. Add an ``HF_TOKEN`` secret in the Space settings.
+* **Timeouts** -- a hung provider request no longer blocks the worker forever.
+* **Retries** -- transient errors (model cold-start 503s, rate limits) are
+  retried with exponential back-off instead of failing on the first hit.
+
+The ``huggingface_hub`` import is deferred into :func:`make_client` so the pure
+helpers (:func:`friendly_error`, :func:`with_retry`) can be imported and unit
+tested without the dependency installed.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Callable, Optional, TypeVar
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT = 120  # seconds
+MAX_RETRIES = 3
+BACKOFF_BASE = 2.0  # seconds
+
+T = TypeVar("T")
+
+_TRANSIENT_MARKERS = (
+    "loading",
+    "currently loading",
+    "starting",
+    "503",
+    "rate limit",
+    "429",
+    "too many requests",
+    "quota",
+    "timeout",
+    "timed out",
+)
+
+
+class InferenceError(RuntimeError):
+    """Raised when an inference call fails after exhausting retries."""
+
+
+def get_token() -> Optional[str]:
+    """Return the HF token from the environment, if configured."""
+    return os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+
+
+def make_client(model: Optional[str] = None, timeout: int = DEFAULT_TIMEOUT):
+    """Create an :class:`InferenceClient` authenticated with the Space token."""
+    from huggingface_hub import InferenceClient  # deferred: keeps helpers dep-free
+
+    token = get_token()
+    if token is None:
+        logger.warning(
+            "No HF_TOKEN found in the environment; inference calls will likely be "
+            "rejected. Add an HF_TOKEN secret in the Space settings."
+        )
+    return InferenceClient(model=model, token=token, timeout=timeout)
+
+
+def _is_transient(exc: Exception) -> bool:
+    msg = str(exc).lower()
+    return any(marker in msg for marker in _TRANSIENT_MARKERS)
+
+
+def friendly_error(exc: Exception) -> str:
+    """Map a raw inference exception to an actionable, user-facing message."""
+    msg = str(exc).lower()
+    if any(k in msg for k in ("rate limit", "429", "too many requests", "quota")):
+        return (
+            "The model is rate-limited right now. Wait a moment and try again, or "
+            "use an HF_TOKEN that has inference credits."
+        )
+    if any(k in msg for k in ("currently loading", "loading", "503", "starting")):
+        return "The model is warming up (cold start). Please try again in ~20 seconds."
+    if any(k in msg for k in ("401", "unauthorized", "402", "authentication")):
+        return (
+            "Inference was rejected for authentication. Set a valid HF_TOKEN secret "
+            "in the Space settings."
+        )
+    if "timeout" in msg or "timed out" in msg:
+        return "The request timed out -- the model may be busy. Please try again."
+    return f"Inference failed: {exc}"
+
+
+def with_retry(
+    fn: Callable[..., T],
+    *args,
+    retries: int = MAX_RETRIES,
+    sleep: Callable[[float], None] = time.sleep,
+    **kwargs,
+) -> T:
+    """Call *fn* with exponential back-off on transient errors.
+
+    Raises :class:`InferenceError` with a friendly message if all attempts fail.
+    """
+    last_exc: Optional[Exception] = None
+    for attempt in range(retries):
+        try:
+            return fn(*args, **kwargs)
+        except Exception as exc:  # noqa: BLE001 - re-raised via InferenceError
+            last_exc = exc
+            if not _is_transient(exc) or attempt == retries - 1:
+                break
+            wait = BACKOFF_BASE * (2**attempt)
+            logger.info(
+                "Transient inference error (attempt %d/%d); retrying in %.1fs: %s",
+                attempt + 1,
+                retries,
+                wait,
+                exc,
+            )
+            sleep(wait)
+    raise InferenceError(friendly_error(last_exc)) from last_exc

requirements.txt

@@ -1,3 +1,3 @@
-gradio>=5.31.0
-huggingface_hub>=0.25.0
-pygments>=2.17.0
+gradio>=5.31.0,<6.0.0
+huggingface_hub>=0.25.0,<1.0.0
+pygments>=2.17.0,<3.0.0