""" app.py โ€” HuggingFace Spaces entry point for Hybrid Comment Moderation. `import spaces` MUST be the first import so that ZeroGPU can patch torch before any other module loads CUDA. All subsequent imports (config, ml_classifier, llm_reviewer) inherit the patched torch. Three tabs: ๐Ÿ” Live Demo โ€” interactive classification (ML / LLM / Hybrid) ๐Ÿ“Š Evaluation โ€” pre-computed metrics and charts from Colab ๐Ÿ—๏ธ Architecture โ€” pipeline diagram and design rationale """ # โ”€โ”€ ZeroGPU patching (must precede every other import) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ try: import spaces # noqa: F401 except ImportError: pass import time import traceback import gradio as gr from config import ( CONFIDENCE_LOW, CONFIDENCE_HIGH, DECISION_BLOCK, DECISION_ALLOW, LLM_MODEL_NAME, CLASSIFIER_MODEL_NAME, ) from ml_classifier import MLClassifier from llm_reviewer import gpu_classify from precomputed import ( SYSTEM_CONFIG_MD, RESULTS_TABLE_MD, KEY_FINDINGS_MD, ) # โ”€โ”€ Constants โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ _LLM_SHORT = LLM_MODEL_NAME.split("/")[-1] # โ”€โ”€ Load ML classifier (CPU โ€” instant, always available) โ”€โ”€โ”€โ”€โ”€โ”€ ml = MLClassifier() # โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• # CLASSIFICATION LOGIC # โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• def classify_comment(comment: str, strategy: str): """Route a comment through the selected strategy.""" if not comment.strip(): return "โš ๏ธ *Please enter a comment first.*", "" try: # โ”€โ”€ ML-only (CPU, no GPU needed) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ if strategy == "ML-only (CPU, no login needed)": t0 = time.perf_counter() decision, confidence, _ = ml.classify(comment) latency = (time.perf_counter() - t0) * 1000 used_llm = False stage = "ml_classifier" reason = "ML-only baseline" # โ”€โ”€ LLM-only (GPU via ZeroGPU) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ elif strategy == "LLM-only (GPU required)": t0 = time.perf_counter() decision, confidence, reason = gpu_classify(comment) latency = (time.perf_counter() - t0) * 1000 used_llm = True stage = "llm" # โ”€โ”€ Hybrid (ML first, LLM only if uncertain) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ else: t0 = time.perf_counter() decision, confidence, is_uncertain = ml.classify(comment) if not is_uncertain: latency = (time.perf_counter() - t0) * 1000 used_llm = False stage = "ml_classifier" reason = "ML classifier is confident" else: decision, confidence, reason = gpu_classify(comment) latency = (time.perf_counter() - t0) * 1000 used_llm = True stage = "llm" # โ”€โ”€ Format output โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ is_blocked = (decision == DECISION_BLOCK) verdict = "## ๐Ÿ”ด BLOCK" if is_blocked else "## ๐ŸŸข ALLOW" details = ( "| Field | Value |\n" "|:------|:------|\n" f"| **Decision** | {decision} |\n" f"| **Confidence** | {confidence:.2%} |\n" f"| **Stage** | {stage} |\n" f"| **LLM Used** | {'Yes โœจ' if used_llm else 'No'} |\n" f"| **Latency** | {latency:.0f} ms |\n" f"| **Reason** | {reason} |\n" ) return verdict, details except Exception as e: tb = traceback.format_exc() err_type = type(e).__name__ err_msg = str(e) # โ”€โ”€ ZeroGPU wraps the real error โ†’ guide user to logs โ”€ gpu_hints = [ "gpu", "quota", "zero", "login", "sign", "unauthorized", "ZeroGPUTask", ] is_gpu_error = ( any(k.lower() in (err_type + err_msg).lower() for k in gpu_hints) or isinstance(e, RuntimeError) ) if is_gpu_error: return ( "## โš ๏ธ GPU Unavailable", "This can happen if:\n" "- You are not signed in to HuggingFace " "([sign in here](https://huggingface.co/login) โ€” free)\n" "- Your daily ZeroGPU quota is exhausted\n" "- The model is still loading on first call " "(try again in ~30 s)\n" "- The GPU timed out during model loading\n\n" "**ML-only works without GPU** โ€” select " "**ML-only (CPU, no login needed)** above.\n\n" f"
Error: {err_type}: {err_msg}" f"\n\n```\n{tb}\n```\n\n" "Check full logs: Space Settings โ†’ Logs" "\n
", ) return "## โŒ Error", f"```\n{tb}\n```" # โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• # BUILD GRADIO APP # โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• with gr.Blocks( title="Hybrid Comment Moderation", theme=gr.themes.Soft(), ) as demo: gr.Markdown( "# ๐Ÿ’ฌ Hybrid Comment Moderation\n" "**CS541 AI Final Project โ€” Stevens Institute of Technology**\n\n" f"DistilBERT (fast, cheap) โ†’ {_LLM_SHORT} (smart, expensive) โ€” " "only when needed." ) with gr.Tabs(): # โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• # TAB 1: LIVE DEMO # โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• with gr.Tab("๐Ÿ” Live Demo"): gr.Markdown( "> ๐Ÿ’ก **ML-only** works for everyone (CPU). \n" "> **Hybrid** and **LLM-only** need a free HuggingFace " "account for GPU access. \n" f"> First LLM call loads the 14B model (~30โ€“40 s); " "subsequent calls take ~1โ€“2 s.\n" ) with gr.Row(): # โ”€โ”€ Left: input โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ with gr.Column(scale=3): comment_box = gr.Textbox( label="Comment", placeholder=( "Type or paste a comment to classify โ€ฆ\n" "e.g. 'This article is a great read, " "thanks for sharing!'" ), lines=4, ) strategy_radio = gr.Radio( choices=[ "Hybrid (recommended)", "ML-only (CPU, no login needed)", "LLM-only (GPU required)", ], value="Hybrid (recommended)", label="Strategy", info=( "Hybrid: ML handles most, LLM reviews " "uncertain. ML-only: DistilBERT on every " "comment (CPU). LLM-only: " f"{_LLM_SHORT} on every comment (GPU)." ), ) classify_btn = gr.Button( "๐Ÿ” Classify", variant="primary", size="lg", ) # โ”€โ”€ Right: output โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ with gr.Column(scale=2): verdict_md = gr.Markdown( value="*Verdict will appear here โ€ฆ*" ) details_md = gr.Markdown(value="") # โ”€โ”€ Examples โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ gr.Examples( examples=[ [ "Thank you for this insightful article!", "Hybrid (recommended)", ], [ "You are an absolute idiot and should die.", "Hybrid (recommended)", ], [ "I'm not sure I agree with the second point " "about taxes.", "Hybrid (recommended)", ], [ "Kill yourself you worthless piece of garbage.", "ML-only (CPU, no login needed)", ], [ "The data seems to support a moderate position " "on this issue.", "Hybrid (recommended)", ], [ "This is the dumbest thing I've ever read, " "the author is clueless.", "LLM-only (GPU required)", ], [ "Great post!", "ML-only (CPU, no login needed)", ], ], inputs=[comment_box, strategy_radio], ) # โ”€โ”€ Wire events โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ classify_btn.click( fn=classify_comment, inputs=[comment_box, strategy_radio], outputs=[verdict_md, details_md], ) comment_box.submit( fn=classify_comment, inputs=[comment_box, strategy_radio], outputs=[verdict_md, details_md], ) # โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• # TAB 2: EVALUATION RESULTS (pre-computed in Colab) # โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• with gr.Tab("๐Ÿ“Š Evaluation Results"): gr.Markdown( "### Pre-computed on Google Colab (T4 GPU)\n" "All three strategies evaluated on the **same** 100 " "balanced samples from Civil Comments." ) gr.Markdown(SYSTEM_CONFIG_MD) gr.Markdown("---\n### Strategy Comparison") gr.Markdown(RESULTS_TABLE_MD) gr.Markdown("---\n### Visual Comparison") gr.Image( value="assets/strategy_comparison.png", label="Strategy Comparison (6-panel bar chart)", show_download_button=False, ) gr.Markdown("---\n### Hybrid Routing Distribution") gr.Image( value="assets/stage_distribution.png", label="Where decisions are made in the Hybrid pipeline", show_download_button=False, ) gr.Markdown("---\n### Key Findings") gr.Markdown(KEY_FINDINGS_MD) # โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• # TAB 3: ARCHITECTURE # โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ• with gr.Tab("๐Ÿ—๏ธ Architecture"): gr.Markdown( "### Two-Stage Pipeline\n" "\n" "```\n" "User Comment\n" " |\n" " v\n" "+----------------------------------------+\n" "| Stage 1: ML Classifier |\n" "| DistilBERT (CPU, ~7 ms per comment) |\n" "| Fine-tuned on Jigsaw toxic comments |\n" "+-------------------+--------------------+\n" " |\n" " Confident?\n" " / \\\n" " Yes No (grey zone)\n" " | |\n" " v v\n" " DONE +----------------------------------+\n" f" | Stage 2: LLM Reviewer |\n" f" | {_LLM_SHORT} (GPU, ~1-2 s) |\n" " | 14B params, NF4 quantized |\n" " +-----------------+----------------+\n" " |\n" " v\n" " DONE\n" "```\n" ) gr.Markdown( "---\n" "### Confidence Routing Logic\n" "\n" "The ML classifier outputs a toxic probability " "in [0, 1]. Two thresholds define three zones:\n" "\n" "| Toxic Probability | Zone | Action |\n" "|:------------------|:-----|:-------|\n" f"| **>= {CONFIDENCE_HIGH}** | High confidence " "toxic | BLOCK (ML decides) |\n" f"| **<= {CONFIDENCE_LOW}** | High confidence " "safe | ALLOW (ML decides) |\n" f"| **{CONFIDENCE_LOW} - {CONFIDENCE_HIGH}** | " "Grey zone | Escalate to LLM |\n" "\n" "Only grey-zone comments cost GPU time. On the " "evaluation set, **88%** of comments were handled " "by the ML classifier alone.\n" ) gr.Markdown( "---\n" "### Why Hybrid?\n" "\n" "| Property | ML-Only | LLM-Only | Hybrid |\n" "|:---------|:--------|:---------|:-------|\n" "| **Speed** | ~7 ms | ~1-2 s | ~7 ms (most) |\n" "| **Cost** | $0 (CPU) | High (every comment) " "| Low (~12% reach LLM) |\n" "| **Nuance** | Training dist. only " "| Broad world knowledge | Best of both |\n" "| **Scalability** | Excellent | Poor | Good |\n" "\n" "> The hybrid gives **LLM-quality decisions where " "they matter** at **ML-classifier cost for the " "easy cases**.\n" ) gr.Markdown( "---\n" "### Models\n" "\n" "| Component | Model | Parameters | Quantization | Serving |\n" "|:----------|:------|:-----------|:-------------|:--------|\n" f"| ML Classifier | `{CLASSIFIER_MODEL_NAME}` " "| ~67 M | None (full precision) | CPU |\n" f"| LLM Reviewer | `{LLM_MODEL_NAME}` " "| ~14 B | NF4 (~8 GB) | ZeroGPU A100 |\n" ) gr.Markdown( "---\n" "### Reference\n" "\n" "- **Course:** CS541 Artificial Intelligence, " "Stevens Institute of Technology\n" "- **Textbook:** *Understanding Deep Learning* " "by Simon J.D. Prince\n" "- **Dataset:** " "[google/civil_comments]" "(https://huggingface.co/datasets/" "google/civil_comments)\n" ) # โ”€โ”€ Footer โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ gr.Markdown( "---\n" "*CS541 AI Final Project ยท Stevens Institute of Technology ยท " f"DistilBERT + {_LLM_SHORT} ยท ZeroGPU*" ) # โ”€โ”€ Launch โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ demo.launch()