VanillaVector commited on
Commit
fb62a11
Β·
verified Β·
1 Parent(s): 89d0d00

Upload 7 files

Browse files
Files changed (7) hide show
  1. README.md +38 -6
  2. app.py +363 -0
  3. config.py +20 -0
  4. llm_reviewer.py +111 -0
  5. ml_classifier.py +57 -0
  6. precomputed.py +93 -0
  7. requirements.txt +6 -0
README.md CHANGED
@@ -1,14 +1,46 @@
1
  ---
2
  title: Hybrid Comment Moderation
3
- emoji: πŸ†
4
- colorFrom: red
5
  colorTo: green
6
  sdk: gradio
7
- sdk_version: 6.32.0
8
- python_version: '3.12'
9
  app_file: app.py
10
  pinned: false
11
- short_description: Two-Stage Pipeline with a ML classifier and a LLM Reviewer
 
 
 
 
 
 
12
  ---
13
 
14
- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
  title: Hybrid Comment Moderation
3
+ emoji: πŸ’¬
4
+ colorFrom: blue
5
  colorTo: green
6
  sdk: gradio
7
+ sdk_version: "5.34.0"
 
8
  app_file: app.py
9
  pinned: false
10
+ license: mit
11
+ tags:
12
+ - content-moderation
13
+ - hybrid-ai
14
+ - distilbert
15
+ - qwen
16
+ - cs541
17
  ---
18
 
19
+ # πŸ’¬ Hybrid Comment Moderation
20
+
21
+ **CS541 AI Final Project β€” Stevens Institute of Technology**
22
+
23
+ A two-stage content moderation pipeline that routes comments intelligently:
24
+
25
+ 1. **Stage 1 β€” ML Classifier** (DistilBERT, CPU, ~7 ms): handles confident predictions instantly.
26
+ 2. **Stage 2 β€” LLM Reviewer** (Qwen2.5-3B-Instruct, GPU, ~1–2 s): reviews only ambiguous comments.
27
+
28
+ ## Tabs
29
+
30
+ | Tab | Description |
31
+ |:----|:------------|
32
+ | πŸ” **Live Demo** | Type a comment, pick a strategy, see the verdict |
33
+ | πŸ“Š **Evaluation** | Pre-computed metrics on 100 balanced Civil Comments samples |
34
+ | πŸ—οΈ **Architecture** | Pipeline diagram and design rationale |
35
+
36
+ ## Usage
37
+
38
+ - **ML-only** works for everyone (CPU, no sign-in needed).
39
+ - **Hybrid** and **LLM-only** require a free HuggingFace account for ZeroGPU access.
40
+
41
+ ## Reference
42
+
43
+ - Textbook: *Understanding Deep Learning* by Simon J.D. Prince
44
+ - Dataset: [google/civil_comments](https://huggingface.co/datasets/google/civil_comments)
45
+ - ML model: [martin-ha/toxic-comment-model](https://huggingface.co/martin-ha/toxic-comment-model)
46
+ - LLM: [Qwen/Qwen2.5-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-3B-Instruct)
app.py ADDED
@@ -0,0 +1,363 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ app.py β€” HuggingFace Spaces entry point for Hybrid Comment Moderation.
3
+
4
+ Three tabs:
5
+ πŸ” Live Demo β€” interactive classification (ML/LLM/Hybrid)
6
+ πŸ“Š Evaluation β€” pre-computed metrics and charts from Colab
7
+ πŸ—οΈ Architecture β€” pipeline diagram and design rationale
8
+ """
9
+
10
+ import time
11
+ import gradio as gr
12
+ from config import (
13
+ CONFIDENCE_LOW,
14
+ CONFIDENCE_HIGH,
15
+ DECISION_BLOCK,
16
+ DECISION_ALLOW,
17
+ LLM_MODEL_NAME,
18
+ CLASSIFIER_MODEL_NAME,
19
+ )
20
+ from ml_classifier import MLClassifier
21
+ from llm_reviewer import gpu_classify
22
+ from precomputed import (
23
+ SYSTEM_CONFIG_MD,
24
+ RESULTS_TABLE_MD,
25
+ KEY_FINDINGS_MD,
26
+ )
27
+
28
+ # ── Constants ─────────────────────────────────────────────────
29
+ _LLM_SHORT = LLM_MODEL_NAME.split("/")[-1]
30
+
31
+ # ── Load ML classifier (CPU β€” instant, always available) ──────
32
+ ml = MLClassifier()
33
+
34
+
35
+ # ══════════════════════════════════════════════════════════════
36
+ # CLASSIFICATION LOGIC
37
+ # ══════════════════════════════════════════════════════════════
38
+
39
+ def classify_comment(comment: str, strategy: str):
40
+ """Route a comment through the selected strategy."""
41
+ if not comment.strip():
42
+ return "⚠️ *Please enter a comment first.*", ""
43
+
44
+ try:
45
+ # ── ML-only (CPU, no GPU needed) ──────────────────────
46
+ if strategy == "ML-only (CPU, no login needed)":
47
+ t0 = time.perf_counter()
48
+ decision, confidence, _ = ml.classify(comment)
49
+ latency = (time.perf_counter() - t0) * 1000
50
+ used_llm = False
51
+ stage = "ml_classifier"
52
+ reason = "ML-only baseline"
53
+
54
+ # ── LLM-only (GPU via ZeroGPU) ────────────────────────
55
+ elif strategy == "LLM-only (GPU required)":
56
+ t0 = time.perf_counter()
57
+ decision, confidence, reason = gpu_classify(comment)
58
+ latency = (time.perf_counter() - t0) * 1000
59
+ used_llm = True
60
+ stage = "llm"
61
+
62
+ # ── Hybrid (ML first, LLM only if uncertain) ─────────
63
+ else:
64
+ t0 = time.perf_counter()
65
+ decision, confidence, is_uncertain = ml.classify(comment)
66
+
67
+ if not is_uncertain:
68
+ latency = (time.perf_counter() - t0) * 1000
69
+ used_llm = False
70
+ stage = "ml_classifier"
71
+ reason = "ML classifier is confident"
72
+ else:
73
+ decision, confidence, reason = gpu_classify(comment)
74
+ latency = (time.perf_counter() - t0) * 1000
75
+ used_llm = True
76
+ stage = "llm"
77
+
78
+ # ── Format output ─────────────────────────────────────
79
+ is_blocked = (decision == DECISION_BLOCK)
80
+ verdict = "## πŸ”΄ BLOCK" if is_blocked else "## 🟒 ALLOW"
81
+
82
+ details = (
83
+ "| Field | Value |\n"
84
+ "|:------|:------|\n"
85
+ f"| **Decision** | {decision} |\n"
86
+ f"| **Confidence** | {confidence:.2%} |\n"
87
+ f"| **Stage** | {stage} |\n"
88
+ f"| **LLM Used** | {'Yes ✨' if used_llm else 'No'} |\n"
89
+ f"| **Latency** | {latency:.0f} ms |\n"
90
+ f"| **Reason** | {reason} |\n"
91
+ )
92
+
93
+ return verdict, details
94
+
95
+ except Exception as e:
96
+ err = str(e).lower()
97
+ if any(k in err for k in ["gpu", "quota", "zero", "login", "sign"]):
98
+ return (
99
+ "## ⚠️ GPU Unavailable",
100
+ "**Please [sign in to HuggingFace](https://huggingface.co/login)** "
101
+ "(free account) to use LLM features.\n\n"
102
+ "The **ML-only** strategy works without GPU β€” "
103
+ "select it above to try it without signing in."
104
+ )
105
+ return "## ❌ Error", f"```\n{e}\n```"
106
+
107
+
108
+ # ══════════════════════════════════════════════════════════════
109
+ # BUILD GRADIO APP
110
+ # ══════════════════════════════════════════════════════════════
111
+
112
+ with gr.Blocks(
113
+ title="Hybrid Comment Moderation",
114
+ theme=gr.themes.Soft(),
115
+ ) as demo:
116
+
117
+ gr.Markdown(
118
+ "# πŸ’¬ Hybrid Comment Moderation\n"
119
+ "**CS541 AI Final Project β€” Stevens Institute of Technology**\n\n"
120
+ f"DistilBERT (fast, cheap) β†’ {_LLM_SHORT} (smart, expensive) β€” "
121
+ "only when needed."
122
+ )
123
+
124
+ with gr.Tabs():
125
+ # ══════════════════════════════════════════════════════
126
+ # TAB 1: LIVE DEMO
127
+ # ══════════════════════════════════════════════════════
128
+ with gr.Tab("πŸ” Live Demo"):
129
+ gr.Markdown(
130
+ "> πŸ’‘ **ML-only** works for everyone (CPU). \n"
131
+ "> **Hybrid** and **LLM-only** need a free HuggingFace "
132
+ "account for GPU access.\n"
133
+ )
134
+
135
+ with gr.Row():
136
+ # ── Left: input ───────────────────────────────
137
+ with gr.Column(scale=3):
138
+ comment_box = gr.Textbox(
139
+ label="Comment",
140
+ placeholder=(
141
+ "Type or paste a comment to classify …\n"
142
+ "e.g. 'This article is a great read, "
143
+ "thanks for sharing!'"
144
+ ),
145
+ lines=4,
146
+ )
147
+ strategy_radio = gr.Radio(
148
+ choices=[
149
+ "Hybrid (recommended)",
150
+ "ML-only (CPU, no login needed)",
151
+ "LLM-only (GPU required)",
152
+ ],
153
+ value="Hybrid (recommended)",
154
+ label="Strategy",
155
+ info=(
156
+ "Hybrid: ML handles most, LLM reviews "
157
+ "uncertain. ML-only: DistilBERT on every "
158
+ "comment (CPU). LLM-only: "
159
+ f"{_LLM_SHORT} on every comment (GPU)."
160
+ ),
161
+ )
162
+ classify_btn = gr.Button(
163
+ "πŸ” Classify",
164
+ variant="primary",
165
+ size="lg",
166
+ )
167
+
168
+ # ── Right: output ─────────────────────────────
169
+ with gr.Column(scale=2):
170
+ verdict_md = gr.Markdown(
171
+ value="*Verdict will appear here …*"
172
+ )
173
+ details_md = gr.Markdown(value="")
174
+
175
+ # ── Examples ──────────────────────────────────────
176
+ gr.Examples(
177
+ examples=[
178
+ [
179
+ "Thank you for this insightful article!",
180
+ "Hybrid (recommended)",
181
+ ],
182
+ [
183
+ "You are an absolute idiot and should die.",
184
+ "Hybrid (recommended)",
185
+ ],
186
+ [
187
+ "I'm not sure I agree with the second point "
188
+ "about taxes.",
189
+ "Hybrid (recommended)",
190
+ ],
191
+ [
192
+ "Kill yourself you worthless piece of garbage.",
193
+ "ML-only (CPU, no login needed)",
194
+ ],
195
+ [
196
+ "The data seems to support a moderate position "
197
+ "on this issue.",
198
+ "Hybrid (recommended)",
199
+ ],
200
+ [
201
+ "This is the dumbest thing I've ever read, "
202
+ "the author is clueless.",
203
+ "LLM-only (GPU required)",
204
+ ],
205
+ [
206
+ "Great post!",
207
+ "ML-only (CPU, no login needed)",
208
+ ],
209
+ ],
210
+ inputs=[comment_box, strategy_radio],
211
+ )
212
+
213
+ # ── Wire events ───────────────────────────────────
214
+ classify_btn.click(
215
+ fn=classify_comment,
216
+ inputs=[comment_box, strategy_radio],
217
+ outputs=[verdict_md, details_md],
218
+ )
219
+ comment_box.submit(
220
+ fn=classify_comment,
221
+ inputs=[comment_box, strategy_radio],
222
+ outputs=[verdict_md, details_md],
223
+ )
224
+
225
+ # ══════════════════════════════════════════════════════
226
+ # TAB 2: EVALUATION RESULTS (pre-computed in Colab)
227
+ # ══════════════════════════════════════════════════════
228
+ with gr.Tab("πŸ“Š Evaluation Results"):
229
+ gr.Markdown(
230
+ "### Pre-computed on Google Colab (T4 GPU)\n"
231
+ "All three strategies evaluated on the **same** 100 "
232
+ "balanced samples from Civil Comments."
233
+ )
234
+ gr.Markdown(SYSTEM_CONFIG_MD)
235
+
236
+ gr.Markdown("---\n### Strategy Comparison")
237
+ gr.Markdown(RESULTS_TABLE_MD)
238
+
239
+ gr.Markdown("---\n### Visual Comparison")
240
+ gr.Image(
241
+ value="assets/strategy_comparison.png",
242
+ label="Strategy Comparison (6-panel bar chart)",
243
+ show_download_button=False,
244
+ )
245
+
246
+ gr.Markdown("---\n### Hybrid Routing Distribution")
247
+ gr.Image(
248
+ value="assets/stage_distribution.png",
249
+ label="Where decisions are made in the Hybrid pipeline",
250
+ show_download_button=False,
251
+ )
252
+
253
+ gr.Markdown("---\n### Key Findings")
254
+ gr.Markdown(KEY_FINDINGS_MD)
255
+
256
+ # ══════════════════════════════════════════════════════
257
+ # TAB 3: ARCHITECTURE
258
+ # ══════════════════════════════════════════════════════
259
+ with gr.Tab("πŸ—οΈ Architecture"):
260
+ gr.Markdown(
261
+ "### Two-Stage Pipeline\n"
262
+ "\n"
263
+ "```\n"
264
+ "User Comment\n"
265
+ " β”‚\n"
266
+ " β–Ό\n"
267
+ "β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”\n"
268
+ "β”‚ Stage 1: ML Classifier β”‚\n"
269
+ "β”‚ DistilBERT (CPU, ~7 ms per comment) β”‚\n"
270
+ "β”‚ Fine-tuned on Jigsaw toxic comments β”‚\n"
271
+ "β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜\n"
272
+ " β”‚\n"
273
+ " β”Œβ”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”\n"
274
+ " β”‚ Confident? β”‚\n"
275
+ " β””β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”˜\n"
276
+ " Yes β”‚ β”‚ No (grey zone)\n"
277
+ " β”‚ β”‚\n"
278
+ " β–Ό β–Ό\n"
279
+ " DONE β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”\n"
280
+ f" β”‚ Stage 2: LLM Reviewer β”‚\n"
281
+ f" β”‚ {_LLM_SHORT} (GPU, ~1-2 s) β”‚\n"
282
+ " β”‚ Instruction-tuned, world knowledgeβ”‚\n"
283
+ " β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜\n"
284
+ " β”‚\n"
285
+ " β–Ό\n"
286
+ " DONE\n"
287
+ "```\n"
288
+ )
289
+
290
+ gr.Markdown(
291
+ "---\n"
292
+ "### Confidence Routing Logic\n"
293
+ "\n"
294
+ "The ML classifier outputs a toxic probability in "
295
+ "[0, 1]. Two thresholds define three zones:\n"
296
+ "\n"
297
+ "| Toxic Probability | Zone | Action |\n"
298
+ "|:------------------|:-----|:-------|\n"
299
+ f"| **β‰₯ {CONFIDENCE_HIGH}** | High confidence toxic "
300
+ "| β†’ **BLOCK** (ML decides) |\n"
301
+ f"| **≀ {CONFIDENCE_LOW}** | High confidence safe "
302
+ "| β†’ **ALLOW** (ML decides) |\n"
303
+ f"| **{CONFIDENCE_LOW} – {CONFIDENCE_HIGH}** | "
304
+ "Grey zone (uncertain) | β†’ **Escalate to LLM** |\n"
305
+ "\n"
306
+ "Only grey-zone comments cost GPU time. On the "
307
+ "evaluation set, typically **75–85%** of comments "
308
+ "are handled by the ML classifier alone.\n"
309
+ )
310
+
311
+ gr.Markdown(
312
+ "---\n"
313
+ "### Why Hybrid?\n"
314
+ "\n"
315
+ "| Property | ML-Only | LLM-Only | Hybrid |\n"
316
+ "|:---------|:--------|:---------|:-------|\n"
317
+ "| **Speed** | ~7 ms | ~1–3 s | ~7 ms (most) |\n"
318
+ "| **Cost** | $0 (CPU) | High (every comment) "
319
+ "| Low (~15–25% reach LLM) |\n"
320
+ "| **Nuance** | Limited to training dist. "
321
+ "| Broad world knowledge | Best of both |\n"
322
+ "| **Scalability** | Excellent | Poor | Good |\n"
323
+ "\n"
324
+ "> The hybrid gives **LLM-quality decisions where "
325
+ "they matter** at **ML-classifier cost for the "
326
+ "easy cases**.\n"
327
+ )
328
+
329
+ gr.Markdown(
330
+ "---\n"
331
+ "### Models\n"
332
+ "\n"
333
+ "| Component | Model | Parameters | Serving |\n"
334
+ "|:----------|:------|:-----------|:--------|\n"
335
+ f"| ML Classifier | `{CLASSIFIER_MODEL_NAME}` "
336
+ "| ~67 M (DistilBERT) | CPU |\n"
337
+ f"| LLM Reviewer | `{LLM_MODEL_NAME}` "
338
+ "| ~3 B (float16) | ZeroGPU (A100) |\n"
339
+ )
340
+
341
+ gr.Markdown(
342
+ "---\n"
343
+ "### Reference\n"
344
+ "\n"
345
+ "- **Course:** CS541 Artificial Intelligence, "
346
+ "Stevens Institute of Technology\n"
347
+ "- **Textbook:** *Understanding Deep Learning* β€” "
348
+ "Simon J.D. Prince\n"
349
+ "- **Dataset:** "
350
+ "[google/civil_comments]"
351
+ "(https://huggingface.co/datasets/google/"
352
+ "civil_comments)\n"
353
+ )
354
+
355
+ # ── Footer ────────────────────────────────────────────────
356
+ gr.Markdown(
357
+ "---\n"
358
+ "*CS541 AI Final Project Β· Stevens Institute of Technology Β· "
359
+ f"DistilBERT + {_LLM_SHORT} Β· ZeroGPU*"
360
+ )
361
+
362
+ # ── Launch ────────────────────────────────────────────────────
363
+ demo.launch()
config.py ADDED
@@ -0,0 +1,20 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ config.py β€” Single source of truth for the Spaces deployment.
3
+ """
4
+
5
+ # ── Decision labels ───────────────────────────────────────────
6
+ DECISION_BLOCK = "BLOCK"
7
+ DECISION_ALLOW = "ALLOW"
8
+
9
+ # ── Model identifiers ────────────────────────────────────────
10
+ CLASSIFIER_MODEL_NAME = "martin-ha/toxic-comment-model" # DistilBERT, ~270 MB
11
+ LLM_MODEL_NAME = "Qwen/Qwen2.5-3B-Instruct" # fp16, ~6 GB
12
+
13
+ # ── Generation parameters ─────────────────────────────────────
14
+ LLM_MAX_NEW_TOKENS = 5
15
+ LLM_TEMPERATURE = 0.0
16
+
17
+ # ── Confidence thresholds (ML β†’ LLM escalation) ──────────────
18
+ CONFIDENCE_HIGH = 0.85 # above β†’ trust the ML classifier
19
+ CONFIDENCE_LOW = 0.15 # below β†’ trust the ML classifier (safe)
20
+ # Between LOW and HIGH β†’ grey zone β†’ escalate to LLM
llm_reviewer.py ADDED
@@ -0,0 +1,111 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ llm_reviewer.py β€” LLM reviewer for ambiguous comments (Stage 2).
3
+
4
+ Qwen2.5-3B-Instruct is loaded in float16 (~6 GB) at module level.
5
+ ZeroGPU allocates an A100 slice only when @spaces.GPU functions run.
6
+
7
+ If the `spaces` package is unavailable (local testing), the GPU
8
+ decorator becomes a no-op so the code still works on any machine.
9
+ """
10
+
11
+ import torch
12
+ from typing import Tuple
13
+ from transformers import AutoModelForCausalLM, AutoTokenizer
14
+ from config import (
15
+ LLM_MODEL_NAME,
16
+ LLM_MAX_NEW_TOKENS,
17
+ DECISION_BLOCK,
18
+ DECISION_ALLOW,
19
+ )
20
+
21
+ # ── ZeroGPU decorator (graceful fallback for local runs) ──────
22
+ try:
23
+ import spaces
24
+ ZERO_GPU = True
25
+ except ImportError:
26
+ ZERO_GPU = False
27
+
28
+ class _SpacesFallback:
29
+ """No-op decorator when `spaces` is not installed."""
30
+ @staticmethod
31
+ def GPU(duration=30):
32
+ def decorator(fn):
33
+ return fn
34
+ return decorator
35
+
36
+ spaces = _SpacesFallback()
37
+
38
+
39
+ # ── Prompt ────────────────────────────────────────────────────
40
+ _SYSTEM_PROMPT = (
41
+ "You are a strict content moderator. Classify the user comment "
42
+ "as exactly one of: toxic or non-toxic.\n"
43
+ "A comment is toxic if it is rude, threatening, hateful, obscene, "
44
+ "or would make someone leave a discussion.\n"
45
+ "Reply with ONLY one word: toxic or non-toxic. "
46
+ "Do not explain."
47
+ )
48
+
49
+ # ── Load model at module level ────────────────────────────────
50
+ # ZeroGPU patches torch so that device_map="auto" works even
51
+ # before GPU is allocated. The actual CUDA tensors are created
52
+ # when the @spaces.GPU-decorated function is first called.
53
+ print(f"⏳ Loading {LLM_MODEL_NAME} …")
54
+
55
+ _tokenizer = AutoTokenizer.from_pretrained(
56
+ LLM_MODEL_NAME, trust_remote_code=True
57
+ )
58
+ if _tokenizer.pad_token is None:
59
+ _tokenizer.pad_token = _tokenizer.eos_token
60
+
61
+ _model = AutoModelForCausalLM.from_pretrained(
62
+ LLM_MODEL_NAME,
63
+ torch_dtype=torch.float16,
64
+ device_map="auto",
65
+ trust_remote_code=True,
66
+ )
67
+ print(f"βœ… {LLM_MODEL_NAME} loaded")
68
+
69
+
70
+ # ── Answer parser ─────────────────────────────────────────────
71
+ def _parse_answer(answer: str) -> Tuple[str, float]:
72
+ a = answer.lower().strip().rstrip(".")
73
+ if "non-toxic" in a or "non toxic" in a or "not toxic" in a:
74
+ return (DECISION_ALLOW, 0.85)
75
+ elif "toxic" in a:
76
+ return (DECISION_BLOCK, 0.85)
77
+ else:
78
+ return (DECISION_BLOCK, 0.50)
79
+
80
+
81
+ # ── GPU-decorated classification function ─────────────────────
82
+ @spaces.GPU(duration=30)
83
+ def gpu_classify(text: str) -> Tuple[str, float, str]:
84
+ """
85
+ Classify one comment with the LLM.
86
+
87
+ On HuggingFace Spaces this runs on a ZeroGPU A100 slice.
88
+ The caller's free-tier quota is consumed (~1–3 GPU-seconds).
89
+ """
90
+ messages = [
91
+ {"role": "system", "content": _SYSTEM_PROMPT},
92
+ {"role": "user", "content": f'Classify this comment: "{text[:1024]}"'},
93
+ ]
94
+
95
+ input_ids = _tokenizer.apply_chat_template(
96
+ messages, return_tensors="pt", add_generation_prompt=True
97
+ ).to(_model.device)
98
+
99
+ with torch.no_grad():
100
+ output_ids = _model.generate(
101
+ input_ids,
102
+ max_new_tokens=LLM_MAX_NEW_TOKENS,
103
+ do_sample=False,
104
+ )
105
+
106
+ new_tokens = output_ids[0][input_ids.shape[-1]:]
107
+ answer = _tokenizer.decode(new_tokens, skip_special_tokens=True)
108
+ answer = answer.strip().lower()
109
+
110
+ decision, confidence = _parse_answer(answer)
111
+ return decision, confidence, f"LLM said: '{answer}'"
ml_classifier.py ADDED
@@ -0,0 +1,57 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ ml_classifier.py β€” DistilBERT toxic-comment classifier (Stage 1).
3
+
4
+ Runs on CPU only β€” no GPU quota consumed. Inference takes ~7 ms
5
+ per comment, so it is available to every visitor (including guests).
6
+ """
7
+
8
+ from typing import Tuple
9
+ from transformers import pipeline as hf_pipeline
10
+ from config import (
11
+ CLASSIFIER_MODEL_NAME,
12
+ CONFIDENCE_HIGH,
13
+ CONFIDENCE_LOW,
14
+ DECISION_BLOCK,
15
+ DECISION_ALLOW,
16
+ )
17
+
18
+
19
+ class MLClassifier:
20
+ """Wrapper around a HuggingFace text-classification pipeline."""
21
+
22
+ def __init__(self, model_name: str = CLASSIFIER_MODEL_NAME):
23
+ self._pipe = hf_pipeline(
24
+ task="text-classification",
25
+ model=model_name,
26
+ tokenizer=model_name,
27
+ framework="pt",
28
+ device=-1, # ← force CPU (no GPU quota)
29
+ truncation=True,
30
+ max_length=512,
31
+ )
32
+ self._toxic_labels = {"toxic"}
33
+ print(f"βœ… ML Classifier loaded on CPU: {model_name}")
34
+
35
+ def classify(self, text: str) -> Tuple[str, float, bool]:
36
+ """
37
+ Returns (decision, confidence, is_uncertain).
38
+
39
+ decision : DECISION_BLOCK or DECISION_ALLOW
40
+ confidence : float in [0, 1]
41
+ is_uncertain : True when confidence is in the grey zone
42
+ """
43
+ result = self._pipe(text)[0]
44
+ return self._interpret(result)
45
+
46
+ def _interpret(self, result: dict) -> Tuple[str, float, bool]:
47
+ label = result["label"].lower()
48
+ score = result["score"]
49
+ toxic_prob = score if label in self._toxic_labels else (1.0 - score)
50
+
51
+ if toxic_prob >= CONFIDENCE_HIGH:
52
+ return (DECISION_BLOCK, toxic_prob, False)
53
+ elif toxic_prob <= CONFIDENCE_LOW:
54
+ return (DECISION_ALLOW, 1.0 - toxic_prob, False)
55
+ else:
56
+ tentative = DECISION_BLOCK if toxic_prob >= 0.5 else DECISION_ALLOW
57
+ return (tentative, max(toxic_prob, 1.0 - toxic_prob), True)
precomputed.py ADDED
@@ -0,0 +1,93 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ precomputed.py β€” Pre-computed evaluation results from Colab.
3
+
4
+ ╔══════════════════════════════════════════════════════════════╗
5
+ β•‘ INSTRUCTIONS β•‘
6
+ β•‘ β•‘
7
+ β•‘ 1. Run the Colab notebook end-to-end with β•‘
8
+ β•‘ LLM_MODEL_NAME = "Qwen/Qwen2.5-3B-Instruct" β•‘
9
+ β•‘ β•‘
10
+ β•‘ 2. Replace every _TBD_ below with the actual numbers β•‘
11
+ β•‘ from your df_results / Cell 15 output. β•‘
12
+ β•‘ β•‘
13
+ β•‘ 3. Place the two PNG files in assets/ β•‘
14
+ β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•
15
+ """
16
+
17
+ # ══════════════════════════════════════════════════════════════
18
+ # System configuration (shown at top of Evaluation tab)
19
+ # ══════════════════════════════════════════════════════════════
20
+ SYSTEM_CONFIG_MD = """\
21
+ πŸ“¦ **Evaluation Environment**
22
+
23
+ | Setting | Value |
24
+ |:--------|:------|
25
+ | **Dataset** | google/civil_comments (test split) |
26
+ | **Eval Samples** | 100 (50 toxic + 50 non-toxic) |
27
+ | **ML Classifier** | martin-ha/toxic-comment-model (DistilBERT) |
28
+ | **LLM** | Qwen/Qwen2.5-3B-Instruct (NF4, ~2 GB VRAM) |
29
+ | **Grey Zone** | [0.15, 0.85] β€” ML uncertain β†’ escalate to LLM |
30
+ | **Runtime** | Google Colab, NVIDIA T4 (15 GB VRAM) |
31
+ """
32
+
33
+ # ══════════════════════════════════════════════════════════════
34
+ # Results table β€” replace _TBD_ with actual values
35
+ # ══════════════════════════════════════════════════════════════
36
+ RESULTS_TABLE_MD = """\
37
+ | Metric | ML-Only (DistilBERT) | LLM-Only (Qwen2.5-3B) | Hybrid (ML→Qwen2.5-3B) |
38
+ |:-------|---------------------:|-----------------------:|------------------------:|
39
+ | **F1 (macro)** | _TBD_ | _TBD_ | _TBD_ |
40
+ | **F1 (toxic)** | _TBD_ | _TBD_ | _TBD_ |
41
+ | **Precision** | _TBD_ | _TBD_ | _TBD_ |
42
+ | **Recall** | _TBD_ | _TBD_ | _TBD_ |
43
+ | **True Positives** | _TBD_ | _TBD_ | _TBD_ |
44
+ | **True Negatives** | _TBD_ | _TBD_ | _TBD_ |
45
+ | **False Positives** | _TBD_ | _TBD_ | _TBD_ |
46
+ | **False Negatives** | _TBD_ | _TBD_ | _TBD_ |
47
+ | **LLM Calls** | 0 | 100 | _TBD_ |
48
+ | **LLM Call %** | 0% | 100% | _TBD_% |
49
+ | **Est. Cost (USD)** | $0.0000 | $_TBD_ | $_TBD_ |
50
+ """
51
+
52
+ # ══════════════════════════════════════════════════════════════
53
+ # Key findings β€” replace with Cell 15 output
54
+ # ══════════════════════════════════════════════════════════════
55
+ KEY_FINDINGS_MD = """\
56
+ #### πŸ“‰ LLM Call Reduction
57
+ > Hybrid used **_TBD_** LLM calls (_TBD_%) vs LLM-Only's 100 calls (100%).
58
+
59
+ #### πŸ’° Cost Savings
60
+ > Hybrid: **$_TBD_** vs LLM-Only: **$_TBD_** β†’ **_TBD_Γ— cheaper**
61
+
62
+ #### 🎯 Best F1 (macro)
63
+ > **_TBD_** strategy achieved the highest F1 of **_TBD_**
64
+
65
+ ---
66
+
67
+ #### Per-Strategy Analysis
68
+
69
+ **1. ML-Only (DistilBERT)**
70
+ > F1 = _TBD_ Β· Precision = _TBD_ Β· Recall = _TBD_
71
+ >
72
+ > _Paste your Cell 15 ML-Only interpretation paragraph here._
73
+
74
+ **2. LLM-Only (Qwen2.5-3B-Instruct)**
75
+ > F1 = _TBD_ Β· Precision = _TBD_ Β· Recall = _TBD_
76
+ >
77
+ > _Paste your Cell 15 LLM-Only interpretation paragraph here._
78
+
79
+ **3. Hybrid (ML β†’ Qwen2.5-3B-Instruct)**
80
+ > F1 = _TBD_ Β· Precision = _TBD_ Β· Recall = _TBD_
81
+ >
82
+ > _Paste your Cell 15 Hybrid interpretation paragraph here._
83
+
84
+ ---
85
+
86
+ #### Conclusion
87
+
88
+ The hybrid architecture validates the core thesis: intelligent routing
89
+ dramatically reduces LLM calls and cost while maintaining competitive
90
+ classification quality. The ML classifier handles confident predictions
91
+ efficiently, and the LLM reviews only the ambiguous ones β€” combining
92
+ both strengths at a fraction of the LLM-Only cost.
93
+ """
requirements.txt ADDED
@@ -0,0 +1,6 @@
 
 
 
 
 
 
 
1
+ torch
2
+ transformers>=4.52
3
+ accelerate
4
+ gradio>=5.0
5
+ spaces
6
+ numpy