Sync card and scripts from the monorepo

app.py

@@ -52,6 +52,7 @@ client = make_client(MODEL_ID)
 # Utility functions
 # ---------------------------------------------------------------------------
 
+
 def detect_language(code: str) -> str:
     """Attempt to detect the programming language."""
     try:
@@ -87,6 +88,7 @@ def format_code_html(code: str, language: str) -> str:
 # Main explanation function
 # ---------------------------------------------------------------------------
 
+
 def explain_code(code: str, language: str, level: str) -> tuple[str, str]:
     """Generate an explanation for the provided code."""
     if not code.strip():
@@ -98,7 +100,9 @@ def explain_code(code: str, language: str, level: str) -> tuple[str, str]:
         detected_lang = detect_language(code)
 
     # Build prompt
-    level_instruction = EXPLANATION_LEVELS.get(level, EXPLANATION_LEVELS["Intermediate"])
+    level_instruction = EXPLANATION_LEVELS.get(
+        level, EXPLANATION_LEVELS["Intermediate"]
+    )
     lexer_hint = detected_lang.split()[0].lower() if detected_lang.strip() else ""
 
     system_prompt = f"You are an expert programming tutor. {level_instruction}"
@@ -138,7 +142,9 @@ Keep your explanation clear, accurate, and educational."""
         explanation = completion.choices[0].message.content.strip()
 
         # Add language badge
-        explanation = f"**Detected Language:** `{detected_lang}`\n\n---\n\n{explanation}"
+        explanation = (
+            f"**Detected Language:** `{detected_lang}`\n\n---\n\n{explanation}"
+        )
 
         # Format the code with syntax highlighting
         formatted_code = format_code_html(code, detected_lang)

hf_client.py

@@ -42,6 +42,17 @@ _TRANSIENT_MARKERS = (
     "timed out",
 )
 
+# Billing failures are permanent until the account changes -- retrying just
+# delays the error. These win over _TRANSIENT_MARKERS, which would otherwise
+# match a credits message that happens to mention "quota".
+_PERMANENT_MARKERS = (
+    "402",
+    "payment required",
+    "included credits",
+    "subscribe to pro",
+    "exceeded your monthly",
+)
+
 
 class InferenceError(RuntimeError):
     """Raised when an inference call fails after exhausting retries."""
@@ -67,12 +78,23 @@ def make_client(model: Optional[str] = None, timeout: int = DEFAULT_TIMEOUT):
 
 def _is_transient(exc: Exception) -> bool:
     msg = str(exc).lower()
+    if any(marker in msg for marker in _PERMANENT_MARKERS):
+        return False
     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()
+    # Checked before rate limiting: a credits message often mentions "quota"
+    # too, and before auth: the token is valid, so telling the user to replace
+    # it sends them to fix something that is not broken.
+    if any(k in msg for k in _PERMANENT_MARKERS):
+        return (
+            "This account is out of HuggingFace Inference credits, so the request "
+            "was declined. The HF_TOKEN is valid -- the monthly free allowance is "
+            "used up. Wait for the monthly reset or subscribe to PRO for more."
+        )
     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 "
@@ -80,7 +102,7 @@ def friendly_error(exc: Exception) -> str:
         )
     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")):
+    if any(k in msg for k in ("401", "unauthorized", "authentication")):
         return (
             "Inference was rejected for authentication. Set a valid HF_TOKEN secret "
             "in the Space settings."