add sentiment demo app

README.md

@@ -1,13 +1,20 @@
 ---
-title: Rocketml Sentiment
-emoji: 🌖
+title: RocketML Sentiment Demo
 colorFrom: blue
-colorTo: gray
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.20.0
-python_version: '3.12'
-app_file: app.py
-pinned: false
+sdk_version: 5.50.0
+app_file: main.py
+python_version: "3.12"
+short_description: TF-IDF + LogReg sentiment classifier (RocketML demo)
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# RocketML -- sentiment demo
+
+A live demo of the model served by [RocketML](https://github.com/kenzychew/RocketML):
+a TF-IDF + LogisticRegression sentiment classifier trained on IMDB reviews. Type a
+movie review and get a positive/negative label with a confidence score.
+
+The point of RocketML is the platform around the model -- containerised serving,
+CI to GHCR, Prometheus/Grafana monitoring, and a Helm chart for Kubernetes. This
+Space is just the model on its own so you can try it.

app/__init__.py

@@ -0,0 +1 @@
+"""RocketML serving application package."""

app/preprocessing.py

@@ -0,0 +1,40 @@
+"""Text preprocessing shared by training and serving.
+
+The same cleaning must run at train time and at inference time, so it lives in
+one place and is imported by both ``model/train.py`` and the serving app.
+Cleaning is regex-only (no NLTK) to keep the serving image light.
+"""
+
+import re
+
+_HTML = re.compile(r"<[^>]+>")
+_URL = re.compile(r"http\S+|www\S+|https\S+", re.MULTILINE)
+_EMAIL = re.compile(r"\S+@\S+")
+_NON_TEXT = re.compile(r"[^a-zA-Z0-9\s']")
+_DOUBLE_APOS = re.compile(r"''")
+_LONE_APOS = re.compile(r"\s'\s")
+_WHITESPACE = re.compile(r"\s+")
+
+
+def clean_text(text: str) -> str:
+    """Normalise raw review text for the sentiment model.
+
+    Strips HTML, lowercases, drops URLs/emails, keeps alphanumerics and
+    apostrophes, and collapses whitespace. Applied identically at train and
+    inference time so the model sees the same text distribution.
+
+    Args:
+        text: Raw input text.
+
+    Returns:
+        The cleaned text.
+    """
+    text = _HTML.sub(" ", text)
+    text = text.lower()
+    text = _URL.sub("", text)
+    text = _EMAIL.sub("", text)
+    text = _NON_TEXT.sub(" ", text)
+    text = _DOUBLE_APOS.sub("", text)
+    text = _LONE_APOS.sub(" ", text)
+    text = _WHITESPACE.sub(" ", text)
+    return text.strip()

main.py

@@ -0,0 +1,114 @@
+"""Gradio demo for the RocketML sentiment model (Hugging Face Space).
+
+The model is the same scikit-learn pipeline RocketML serves. Its TF-IDF step
+references app.preprocessing.clean_text, so the app/ package ships alongside
+this file for joblib.load to resolve.
+
+The endpoint is public, so two light guards keep it from being hammered: a
+per-client cooldown and a global daily prediction cap ("demo credits"). Both
+counters are in-memory and reset if the instance restarts, which is acceptable
+for a single-instance demo.
+"""
+
+import os
+import threading
+import time
+from datetime import date, datetime, timezone
+
+import gradio as gr
+import joblib
+
+MODEL = joblib.load("sentiment.joblib")
+
+DAILY_CAP = int(os.environ.get("DEMO_DAILY_CAP", "200"))
+COOLDOWN_SECONDS = 3.0
+
+EXAMPLES = [
+    "An absolute masterpiece -- beautifully acted and deeply moving.",
+    "Boring, predictable, and a complete waste of two hours.",
+    "The plot dragged, but the soundtrack was wonderful.",
+]
+
+_lock = threading.Lock()
+_day: date | None = None
+_count = 0
+_last_call: dict[str, float] = {}
+
+
+def _client_id(request: gr.Request | None) -> str:
+    """Best-effort client identifier for throttling.
+
+    Args:
+        request: The incoming Gradio request, if any.
+
+    Returns:
+        The originating client IP (first X-Forwarded-For hop behind the
+        Cloud Run proxy), or a placeholder when unavailable.
+    """
+    if request is None:
+        return "unknown"
+    forwarded = request.headers.get("x-forwarded-for")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
+def _check_limits(client: str) -> None:
+    """Enforce the per-client cooldown and the global daily cap.
+
+    Args:
+        client: Client identifier from _client_id.
+
+    Raises:
+        gr.Error: If the client is calling too fast or today's demo
+            credits are spent.
+    """
+    global _day, _count
+    with _lock:
+        today = datetime.now(timezone.utc).date()
+        if _day != today:
+            _day, _count = today, 0
+            _last_call.clear()
+        last = _last_call.get(client)
+        now = time.monotonic()
+        if last is not None and now - last < COOLDOWN_SECONDS:
+            raise gr.Error("One prediction every few seconds, please.")
+        if _count >= DAILY_CAP:
+            raise gr.Error("Sorry, out of demo credits for now -- try again tomorrow.")
+        _last_call[client] = now
+        _count += 1
+
+
+def classify(text: str, request: gr.Request) -> dict[str, float]:
+    """Return the model's class probabilities for the given text.
+
+    Args:
+        text: Raw review text from the UI.
+        request: Injected by Gradio; used for rate limiting.
+
+    Returns:
+        Mapping of class label to probability, empty for blank input.
+    """
+    if not text or not text.strip():
+        return {}
+    _check_limits(_client_id(request))
+    probs = MODEL.predict_proba([text])[0]
+    return {str(label): float(p) for label, p in zip(MODEL.classes_, probs)}
+
+
+demo = gr.Interface(
+    fn=classify,
+    inputs=gr.Textbox(lines=4, label="Text", placeholder="Type a movie review..."),
+    outputs=gr.Label(num_top_classes=2, label="Sentiment"),
+    title="RocketML -- sentiment demo",
+    description=(
+        "A TF-IDF + LogisticRegression sentiment classifier (trained on IMDB). "
+        "This is the model served by the RocketML platform: "
+        "https://github.com/kenzychew/RocketML -- the demo is lightly "
+        "rate-limited and has a daily prediction budget."
+    ),
+    examples=EXAMPLES,
+)
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=int(os.environ.get("PORT", "7860")))

requirements.txt

@@ -0,0 +1,2 @@
+scikit-learn==1.9.0
+joblib

sentiment.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c7ce940765dda1b0d9ccab79889f277dd546b6997cb69b840c37dd9d6a62d43f
+size 926260