InfoShield backend (Docker)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,17 @@
+# Keep the Docker build context (and the HF Space) lean: only backend/ is needed.
+.git/
+.venv/
+**/__pycache__/
+*.pyc
+*.log
+.env
+
+node_modules/
+frontend/
+extension/
+assets/
+docs/
+tools/
+
+# Local ML models are re-downloaded on first boot, never shipped.
+backend/models/

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,24 @@
+# InfoShield backend for Hugging Face Spaces (Docker SDK).
+# Serves the prebuilt cache instantly; downloads the local ML models on first
+# boot for the live "Check with InfoShield" draft analysis. Gemini key comes
+# from the Space secret GEMINI_API_KEY (never baked into the image).
+FROM python:3.11-slim
+
+# Non-root user (HF Spaces best practice) with writable caches under $HOME.
+RUN useradd -m -u 1000 user
+ENV HOME=/home/user \
+    HF_HOME=/home/user/.cache/huggingface \
+    INFOSHIELD_HOST=0.0.0.0 \
+    INFOSHIELD_PORT=7860 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /home/user/app
+
+COPY --chown=user backend/requirements.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user backend/ ./
+
+USER user
+EXPOSE 7860
+CMD ["python", "app.py"]

README.md

@@ -1,13 +1,12 @@
 ---
 title: Infoshield Backend
-emoji: 🔥
-colorFrom: red
-colorTo: pink
+emoji: 🛡️
+colorFrom: purple
+colorTo: indigo
 sdk: docker
-sdk_version: 6.19.0
-python_version: '3.13'
-app_file: app.py
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+InfoShield backend (Flask + Docker): serves the cached feed and the live
+draft analysis. The Gemini key is provided via the Space secret GEMINI_API_KEY.

backend/analyzer.py

@@ -0,0 +1,275 @@
+"""Educational analysis (the explainer) + verifier (the judge).
+
+The local models (hate + manipulation) decide WHETHER a post is flagged. This
+module decides WHY:
+  * analyze(text, kind)  -- runs the hate OR manipulation analysis prompt and
+                            returns techniques / severity / explanation / highlights.
+  * verify(text, analysis, kind) -- a second LLM pass that judges whether the
+                            analysis is accurate/relevant; if not, the caller
+                            overturns the flag (false positive).
+
+Provider-agnostic (llm.py): Groq now, Gemini later. Privacy: only post text is
+sent. If the LLM is unavailable, analyze() degrades to a local heuristic and
+verify() fails open (keeps the original decision).
+"""
+from __future__ import annotations
+
+import json
+import logging
+from typing import Optional
+
+from config import (
+    ALLOWED_TECHNIQUES,
+    ANALYSIS_SYSTEM_INSTRUCTION,
+    HATE_ANALYSIS_PROMPT,
+    LEGAL_SOURCE_URLS,
+    MANIPULATION_ANALYSIS_PROMPT,
+    MAX_EXPLANATION_CHARS,
+    REPHRASE_PROMPT,
+    REPHRASE_SYSTEM_INSTRUCTION,
+    TECHNIQUE_LABELS,
+    VERIFIER_MODEL,
+    VERIFIER_PROMPT,
+    VERIFIER_PROVIDER,
+    VERIFIER_SYSTEM_INSTRUCTION,
+)
+from llm import available, complete_json  # noqa: F401  (available re-exported)
+
+log = logging.getLogger("infoshield.analyzer")
+
+ANALYSIS_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "techniques": {
+            "type": "array",
+            "items": {"type": "string", "enum": ALLOWED_TECHNIQUES},
+        },
+        "emotional_triggers": {"type": "array", "items": {"type": "string"}},
+        "explanation": {"type": "string"},
+        "recommendation": {"type": "string"},
+        "severity": {"type": "string", "enum": ["low", "medium", "high"]},
+        "highlights": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "phrase": {"type": "string"},
+                    "type": {"type": "string"},
+                    "label": {"type": "string"},
+                },
+                "required": ["phrase", "type", "label"],
+            },
+        },
+        "bias_check": {"type": "string"},
+        "citations": {"type": "array", "items": {"type": "string"}},
+    },
+    "required": ["techniques", "emotional_triggers", "explanation",
+                 "recommendation", "severity", "highlights", "bias_check", "citations"],
+}
+
+_DEFAULT_BIAS_CHECK = (
+    "Checked against Article 19 free-expression protections and non-discrimination "
+    "safeguards; flagged only on concrete textual evidence."
+)
+
+_STRICT_SUFFIX = (
+    "\n\nIMPORTANT: Output MUST be a single valid JSON object matching the schema "
+    "exactly. No markdown fences, no commentary."
+)
+
+
+# --- validation -----------------------------------------------------------
+def validate_analysis(raw: dict, text: str) -> Optional[dict]:
+    """Enforce allowlist, exact-substring highlights, no overlaps, length caps.
+    Returns None when there is nothing usable (triggers retry / fallback)."""
+    if not isinstance(raw, dict):
+        return None
+    lower = text.lower()
+
+    techniques = [t for t in raw.get("techniques", []) if t in ALLOWED_TECHNIQUES]
+    techniques = list(dict.fromkeys(techniques))
+
+    triggers = [str(t).strip() for t in raw.get("emotional_triggers", []) if str(t).strip()]
+    triggers = list(dict.fromkeys(triggers))[:6]
+
+    explanation = str(raw.get("explanation", "")).strip()[:MAX_EXPLANATION_CHARS]
+    recommendation = str(raw.get("recommendation", "")).strip()[:200]
+
+    severity = raw.get("severity")
+    if severity not in ("low", "medium", "high"):
+        severity = "medium"
+
+    highlights = []
+    used_spans: list[tuple[int, int]] = []
+    for h in raw.get("highlights", []):
+        if not isinstance(h, dict):
+            continue
+        phrase = str(h.get("phrase") or h.get("text") or h.get("quote") or "").strip()
+        if not phrase:
+            continue
+        idx = lower.find(phrase.lower())
+        if idx == -1:
+            continue
+        span = (idx, idx + len(phrase))
+        if any(span[0] < e and s < span[1] for s, e in used_spans):
+            continue
+        used_spans.append(span)
+        htype = str(h.get("type", "")).strip() or "emotional_manipulation"
+        label = str(h.get("label", "")).strip() or TECHNIQUE_LABELS.get(
+            htype, htype.replace("_", " ").title()
+        )
+        highlights.append({"phrase": text[idx: idx + len(phrase)], "type": htype, "label": label})
+
+    bias_check = str(raw.get("bias_check", "")).strip()[:300] or _DEFAULT_BIAS_CHECK
+    allow = set(LEGAL_SOURCE_URLS)
+    citations = [u for u in raw.get("citations", []) if isinstance(u, str) and u in allow]
+    citations = list(dict.fromkeys(citations))[:5]
+
+    if not techniques and not highlights and not explanation:
+        return None
+    return {
+        "techniques": techniques,
+        "emotional_triggers": triggers,
+        "explanation": explanation,
+        "recommendation": recommendation,
+        "severity": severity,
+        "highlights": highlights,
+        "bias_check": bias_check,
+        "citations": citations,
+    }
+
+
+# --- local fallback -------------------------------------------------------
+_HEURISTICS = {
+    "false_urgency": ["before it", "act now", "midnight", "by monday", "running out", "last chance", "don't wait", "act before"],
+    "fear_amplification": ["destroy", "lose everything", "collapse", "disaster", "danger", "terrify", "catastroph", "doom", "ruin everything"],
+    "us_vs_them": ["us against them", "those people", "our side", "their side", "wake up", "elites", "they don't want you"],
+    "scapegoating": ["blame", "fault", "because of them", "the reason", "responsible for"],
+    "dehumanizing_language": ["vermin", "animals", "infest", "parasite", "swarm", "subhuman", "filth"],
+    "ad_hominem": ["idiot", "fool", "stupid", "liar", "sheep", "brainless"],
+    "emotional_manipulation": ["share this", "they don't want you", "hiding the truth", "stay angry", "open your eyes", "screenshot this", "real parent"],
+}
+
+_TRIGGER_WORDS = {
+    "fear": ["destroy", "lose", "danger", "afraid", "collapse", "forever"],
+    "anger": ["elites", "blame", "liar", "angry"],
+    "urgency": ["now", "before", "midnight", "monday", "immediately"],
+    "belonging": ["us", "our values", "who we are", "community"],
+}
+
+
+def local_fallback_analysis(text: str) -> dict:
+    """Deterministic heuristic analysis used when the LLM is unavailable."""
+    lower = text.lower()
+    techniques, highlights, used = [], [], []
+    for tech, cues in _HEURISTICS.items():
+        for cue in cues:
+            idx = lower.find(cue)
+            if idx == -1:
+                continue
+            if tech not in techniques:
+                techniques.append(tech)
+            span = (idx, idx + len(cue))
+            if not any(span[0] < e and s < span[1] for s, e in used):
+                used.append(span)
+                highlights.append({
+                    "phrase": text[idx: idx + len(cue)],
+                    "type": tech,
+                    "label": TECHNIQUE_LABELS.get(tech, tech.replace("_", " ").title()),
+                })
+            break
+    n = len(techniques)
+    triggers = [name for name, words in _TRIGGER_WORDS.items() if any(w in lower for w in words)]
+    severity = "high" if n >= 3 else "medium" if n == 2 else "low"
+    return {
+        "techniques": techniques[:4] or ["emotional_manipulation"],
+        "emotional_triggers": triggers[:4] or ["emotional reaction"],
+        "explanation": (
+            "This post leans on emotionally charged language and framing that "
+            "pushes a strong reaction rather than inviting reflection."
+        ),
+        "recommendation": "Take a moment before sharing and check whether the claim holds up calmly.",
+        "severity": severity,
+        "highlights": highlights[:6],
+        "bias_check": "Heuristic check (LLM unavailable); flags only explicit manipulative cues, free expression preserved.",
+        "citations": [],
+        "source": "local_fallback",
+    }
+
+
+def _empty_analysis() -> dict:
+    return {
+        "techniques": [], "emotional_triggers": [], "explanation": "",
+        "recommendation": "", "severity": "low", "highlights": [],
+        "bias_check": _DEFAULT_BIAS_CHECK, "citations": [], "source": "empty",
+    }
+
+
+# --- analysis (the explainer) ---------------------------------------------
+def analyze(text: str, kind: str = "manipulation") -> dict:
+    """Run the hate OR manipulation analysis prompt; never raises for normal input."""
+    if not text or not text.strip():
+        return _empty_analysis()
+    template = HATE_ANALYSIS_PROMPT if kind == "hate" else MANIPULATION_ANALYSIS_PROMPT
+
+    raw = complete_json(ANALYSIS_SYSTEM_INSTRUCTION, template.format(text=text), schema=ANALYSIS_SCHEMA)
+    analysis = validate_analysis(raw, text) if raw else None
+    if analysis is None:
+        raw = complete_json(
+            ANALYSIS_SYSTEM_INSTRUCTION, template.format(text=text) + _STRICT_SUFFIX, schema=ANALYSIS_SCHEMA
+        )
+        analysis = validate_analysis(raw, text) if raw else None
+    if analysis is None:
+        analysis = local_fallback_analysis(text)
+    else:
+        analysis["source"] = "llm"
+    analysis["kind"] = kind
+    return analysis
+
+
+# --- verifier (the judge) -------------------------------------------------
+def verify(text: str, analysis: dict, kind: str) -> dict:
+    """Second-pass LLM judge. Returns {relevant, reason, checked}.
+
+    Fails OPEN: if the verifier can't run, relevant=True (keep the flag).
+    """
+    payload = json.dumps(
+        {k: analysis.get(k) for k in ("techniques", "explanation", "severity", "bias_check", "citations")},
+        ensure_ascii=False,
+    )
+    # The configured verifier model id is Gemini-specific; only pass it when the
+    # verifier provider is Gemini (otherwise use the provider's default model).
+    vmodel = VERIFIER_MODEL if VERIFIER_PROVIDER == "gemini" else None
+    raw = complete_json(
+        VERIFIER_SYSTEM_INSTRUCTION,
+        VERIFIER_PROMPT.format(kind=kind, text=text, analysis=payload),
+        provider=VERIFIER_PROVIDER,
+        model=vmodel or None,
+        temperature=0.0,  # deterministic verdict
+    )
+    if not isinstance(raw, dict) or "relevant" not in raw:
+        return {"relevant": True, "reason": "verifier unavailable", "checked": False}
+    return {
+        "relevant": bool(raw.get("relevant")),
+        "reason": str(raw.get("reason", "")).strip()[:200],
+        "checked": True,
+    }
+
+
+# --- rephrase (live compose-assist) ---------------------------------------
+def rephrase(text: str) -> str:
+    """Rewrite a draft to remove manipulation/hate while keeping the author's
+    viewpoint. Returns the original text on failure (never raises, never censors)."""
+    if not text or not text.strip():
+        return text
+    raw = complete_json(REPHRASE_SYSTEM_INSTRUCTION, REPHRASE_PROMPT.format(text=text))
+    if isinstance(raw, dict):
+        out = str(raw.get("rephrased") or "").strip()
+        if out:
+            return out
+    return text
+
+
+# Backwards-compatible alias for the /analyze endpoint.
+def detect_and_analyze(text: str) -> dict:
+    return analyze(text, "manipulation")

backend/app.py

@@ -0,0 +1,313 @@
+"""InfoShield Flask backend.
+
+Cache-first by design: on startup it serves a pre-built JSON cache so the demo
+is instant and works fully offline. Heavy ML / Gemini code is imported lazily,
+so this process starts with only Flask installed when serving from cache.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from collections import Counter
+from urllib.parse import urlparse
+
+from flask import Flask, jsonify, request, send_from_directory
+from flask_cors import CORS
+
+import config
+from cache import (
+    get_cache,
+    load_activation,
+    load_posts,
+    reset_activation,
+    save_activation,
+)
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    datefmt="%H:%M:%S",
+)
+log = logging.getLogger("infoshield.app")
+
+app = Flask(__name__)
+CORS(app)  # localhost demo: allow the Vite frontend and the extension to call us.
+
+POSTS = load_posts()
+POSTS_BY_ID = {p["id"]: p for p in POSTS}
+CACHE = get_cache()
+
+
+# --- helpers --------------------------------------------------------------
+def _merged_post(post: dict) -> dict:
+    """Serve cached classification + analysis; compute, store, and persist on a miss
+    so activating the extension shows saved results instantly."""
+    cached = CACHE.get(post["id"])
+    if not cached or not cached.get("classification"):
+        from pipeline import analyze_post
+
+        classification, analysis = analyze_post(post["text"])
+        CACHE.set(post["id"], classification, analysis)
+        CACHE.save()
+        cached = {"classification": classification, "analysis": analysis}
+    cls = cached.get("classification") or {}
+    return {
+        **post,
+        "classification": cls,
+        "analysis": cached.get("analysis"),
+        "flagged": bool(cls.get("flagged")),
+    }
+
+
+def _warm_cache() -> None:
+    """Background pre-warm: compute analysis for any uncached posts so the demo is
+    instant by the time the user activates the extension."""
+    try:
+        from classifier import get_classifier
+        from manip_classifier import get_manip_classifier
+
+        get_classifier().load()
+        get_manip_classifier().load()
+        missing = [p for p in POSTS if not (CACHE.get(p["id"]) or {}).get("classification")]
+        if not missing:
+            log.info("Cache already warm (%d posts).", len(POSTS))
+            return
+        log.info("Warming cache for %d post(s) in background ...", len(missing))
+        for p in missing:
+            _merged_post(p)
+        log.info("Cache warm complete.")
+    except Exception as exc:  # noqa: BLE001
+        log.warning("Cache warm failed: %s", exc)
+
+
+def _is_localhost(url: str) -> bool:
+    try:
+        host = (urlparse(url).hostname or "").lower()
+    except Exception:  # noqa: BLE001
+        return False
+    return host in ("localhost", "127.0.0.1", "0.0.0.0", "::1")
+
+
+# --- routes ---------------------------------------------------------------
+@app.get("/health")
+def health():
+    from classifier import get_classifier
+
+    from llm import available as llm_available
+
+    clf = get_classifier()
+    cached = sum(1 for p in POSTS if (CACHE.get(p["id"]) or {}).get("classification"))
+    return jsonify({
+        "status": "ok",
+        "service": "infoshield",
+        "mode": "cached",
+        "hate_model": config.PRIMARY_MODEL,
+        "manipulation_model": config.MANIP_MODEL,
+        "model_loaded": clf.loaded,
+        "device": clf.device if clf.loaded else "unknown",
+        "posts": len(POSTS),
+        "cached_posts": cached,
+        "llm_provider": config.LLM_PROVIDER,
+        "verifier_model": config.VERIFIER_MODEL,
+        "llm_configured": llm_available(),
+    })
+
+
+@app.get("/feed")
+def feed():
+    return jsonify({"posts": [_merged_post(p) for p in POSTS]})
+
+
+@app.get("/media/<path:filename>")
+def media(filename: str):
+    """Serve demo media (e.g. the feed video) from backend/data."""
+    return send_from_directory(config.DATA_DIR, filename)
+
+
+@app.get("/post-analysis/<post_id>")
+def post_analysis(post_id: str):
+    post = POSTS_BY_ID.get(post_id)
+    if post is None:
+        return jsonify({"error": "unknown post id"}), 404
+    merged = _merged_post(post)
+    return jsonify({
+        "id": post_id,
+        "text": post["text"],
+        "classification": merged["classification"],
+        "analysis": merged["analysis"],
+        "flagged": merged["flagged"],
+    })
+
+
+@app.post("/rebuild-cache")
+def rebuild_cache_endpoint():
+    """Trigger a full live rebuild (local classifier + Gemini) and overwrite the
+    cache. This is the ONLY endpoint that incurs API cost. Results are live
+    immediately -- it updates the in-memory cache, no restart needed."""
+    from rebuild import rebuild_cache
+
+    try:
+        summary = rebuild_cache(CACHE, POSTS)
+    except Exception as exc:  # noqa: BLE001
+        log.error("rebuild failed: %s", exc)
+        return jsonify({"status": "error", "error": str(exc)}), 503
+    return jsonify({"status": "ok", **summary})
+
+
+@app.post("/classify")
+def classify():
+    """Hate-only classification of arbitrary text (live, content-only)."""
+    data = request.get_json(silent=True) or {}
+    text = (data.get("text") or "").strip()
+    from classifier import get_classifier
+
+    try:
+        return jsonify(get_classifier().classify(text))
+    except Exception as exc:  # noqa: BLE001
+        log.error("classify failed: %s", exc)
+        return jsonify({"error": "classifier unavailable", "detail": str(exc)}), 503
+
+
+@app.post("/analyze")
+def analyze():
+    """Manipulation detection + educational analysis of arbitrary text (live)."""
+    data = request.get_json(silent=True) or {}
+    text = (data.get("text") or "").strip()
+    if not text:
+        return jsonify({"error": "empty text"}), 400
+    from analyzer import detect_and_analyze
+
+    return jsonify(detect_and_analyze(text))
+
+
+@app.post("/analyze-text")
+def analyze_text():
+    """Full pipeline (both detectors + analysis + verifier) on a user's own draft.
+    Always LIVE -- never cached -- so the compose-assist demo runs fresh each time."""
+    data = request.get_json(silent=True) or {}
+    text = (data.get("text") or "").strip()
+    if not text:
+        return jsonify({"error": "empty text"}), 400
+    from pipeline import analyze_post
+
+    classification, analysis = analyze_post(text)
+    return jsonify({
+        "text": text,
+        "classification": classification,
+        "analysis": analysis,
+        "flagged": classification["flagged"],
+    })
+
+
+@app.post("/rephrase")
+def rephrase_endpoint():
+    """Rewrite the user's draft to remove manipulation/hate while keeping their
+    viewpoint. Live; never cached; never censors (returns original on failure)."""
+    data = request.get_json(silent=True) or {}
+    text = (data.get("text") or "").strip()
+    if not text:
+        return jsonify({"error": "empty text"}), 400
+    from analyzer import rephrase
+
+    return jsonify({"rephrased": rephrase(text)})
+
+
+@app.get("/stats")
+def stats():
+    posts = [_merged_post(p) for p in POSTS]
+    flagged = [p for p in posts if p["flagged"]]
+    tech_counter: Counter = Counter()
+    confidences = []
+    high_conf = 0
+    for p in flagged:
+        cls = p["classification"] or {}
+        confidences.append(cls.get("confidence", 0.0))
+        if cls.get("high_confidence"):
+            high_conf += 1
+        for t in (p["analysis"] or {}).get("techniques", []):
+            tech_counter[t] += 1
+
+    distribution = {t: tech_counter.get(t, 0) for t in config.ALLOWED_TECHNIQUES if tech_counter.get(t)}
+    most_common = tech_counter.most_common(1)
+    most_common_technique = most_common[0][0] if most_common else None
+    most_common_label = (
+        config.TECHNIQUE_LABELS.get(most_common_technique, most_common_technique)
+        if most_common_technique else "—"
+    )
+
+    return jsonify({
+        "totals": {
+            "posts": len(POSTS),
+            "flagged": len(flagged),
+            "benign": len(POSTS) - len(flagged),
+        },
+        "technique_distribution": distribution,
+        "most_common_technique": most_common_technique,
+        "confidences": {
+            "mean_flagged": round(sum(confidences) / len(confidences), 3) if confidences else 0,
+            "max": round(max(confidences), 3) if confidences else 0,
+            "min": round(min(confidences), 3) if confidences else 0,
+            "high_confidence_count": high_conf,
+        },
+        "model": {
+            "hate_model": config.PRIMARY_MODEL,
+            "manipulation_model": config.MANIP_MODEL,
+            "llm_provider": config.LLM_PROVIDER,
+            "analyzer_model": config.GEMINI_MODEL if config.LLM_PROVIDER == "gemini" else config.GROQ_MODEL,
+            "verifier_model": config.VERIFIER_MODEL,
+            "flag_threshold": config.FLAG_THRESHOLD,
+            "manipulation_threshold": config.MANIP_THRESHOLD,
+            "high_confidence": config.HIGH_CONFIDENCE,
+        },
+        # Data-driven snapshot. The right-rail widget now renders from the
+        # extension's live page scan; this stays as an honest API view.
+        "insights": {
+            "scanned": len(POSTS),
+            "posts_analyzed": len(POSTS),
+            "patterns_detected": len(distribution),
+            "most_common_pattern": most_common_label,
+        },
+        "mode": "cached",
+    })
+
+
+@app.get("/activation-target")
+def get_activation_target():
+    return jsonify(load_activation())
+
+
+@app.post("/activation-target")
+def set_activation_target():
+    data = request.get_json(silent=True) or {}
+    url = (data.get("target_url") or "").strip()
+    enabled = bool(data.get("enabled", True))
+    if not url:
+        return jsonify({"error": "target_url is required"}), 400
+    if not url.startswith("http://") or not _is_localhost(url):
+        return jsonify({
+            "error": "target_url must be a localhost address "
+                     "(http://localhost/... or http://127.0.0.1/...)"
+        }), 400
+    return jsonify(save_activation(url, enabled))
+
+
+@app.get("/")
+def root():
+    return jsonify({
+        "service": "InfoShield backend",
+        "routes": [
+            "/health", "/feed", "/post-analysis/<id>", "/classify",
+            "/analyze", "/stats", "/activation-target",
+        ],
+    })
+
+
+if __name__ == "__main__":
+    if config.RESET_ACTIVATION_ON_START:
+        reset_activation()
+        log.info("Activation reset to default on startup (fresh demo).")
+    # Pre-warm the analysis cache in the background so activation is instant.
+    threading.Thread(target=_warm_cache, daemon=True).start()
+    log.info("InfoShield backend starting on http://%s:%d (provider=%s, cached)",
+             config.HOST, config.PORT, config.LLM_PROVIDER)
+    app.run(host=config.HOST, port=config.PORT, debug=False)

backend/cache.py

@@ -0,0 +1,143 @@
+"""JSON-file + in-memory caching. No database.
+
+- `cache.json` holds per-post classification + analysis so the demo is instant
+  and works fully offline after one build.
+- `activation.json` holds the landing-page-selected target URL and on/off state.
+- An in-memory dict caches ad-hoc /classify and /analyze results by content hash.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import threading
+from datetime import datetime, timezone
+from typing import Optional
+
+from config import ACTIVATION_FILE, CACHE_FILE, CACHE_VERSION, DATA_DIR, POSTS_FILE
+
+log = logging.getLogger("infoshield.cache")
+_lock = threading.Lock()
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def text_hash(text: str) -> str:
+    return hashlib.sha256(text.strip().encode("utf-8")).hexdigest()[:16]
+
+
+# --- posts ----------------------------------------------------------------
+def load_posts() -> list[dict]:
+    with open(POSTS_FILE, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+# --- post cache -----------------------------------------------------------
+class PostCache:
+    def __init__(self) -> None:
+        self.meta: dict = {}
+        self.posts: dict[str, dict] = {}
+        self.adhoc: dict[str, dict] = {}  # content-hash -> {classification, analysis}
+
+    def load(self) -> bool:
+        if not CACHE_FILE.exists():
+            log.warning("Cache file %s not found -- starting empty.", CACHE_FILE)
+            return False
+        try:
+            with open(CACHE_FILE, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            self.meta = data.get("meta", {})
+            self.posts = data.get("posts", {})
+            if self.meta.get("version") != CACHE_VERSION:
+                log.info("Cache version mismatch (have %s, want %s) -- discarding stale cache.",
+                         self.meta.get("version"), CACHE_VERSION)
+                self.posts = {}
+                self.meta = {}
+                return False
+            log.info("Loaded cache: %d posts (built_at=%s).",
+                     len(self.posts), self.meta.get("built_at"))
+            return True
+        except Exception as exc:  # noqa: BLE001
+            log.error("Failed to load cache: %s", exc)
+            return False
+
+    def save(self) -> None:
+        DATA_DIR.mkdir(parents=True, exist_ok=True)
+        self.meta["version"] = CACHE_VERSION
+        with _lock:
+            payload = {"meta": self.meta, "posts": self.posts}
+            with open(CACHE_FILE, "w", encoding="utf-8") as f:
+                json.dump(payload, f, ensure_ascii=False, indent=2)
+        log.info("Cache saved (%d posts).", len(self.posts))
+
+    def get(self, post_id: str) -> Optional[dict]:
+        return self.posts.get(post_id)
+
+    def set(self, post_id: str, classification: dict, analysis: Optional[dict]) -> None:
+        self.posts[post_id] = {"classification": classification, "analysis": analysis}
+
+    def set_meta(self, **kw) -> None:
+        self.meta.update(kw)
+        self.meta["built_at"] = _now()
+        self.meta["version"] = CACHE_VERSION
+
+    @property
+    def mode(self) -> str:
+        return "cache-first" if self.posts else "empty"
+
+
+_cache: Optional[PostCache] = None
+
+
+def get_cache() -> PostCache:
+    global _cache
+    if _cache is None:
+        _cache = PostCache()
+        _cache.load()
+    return _cache
+
+
+# --- activation config ----------------------------------------------------
+DEFAULT_ACTIVATION = {
+    "target_url": "",
+    "enabled": False,
+    "updated_at": None,
+}
+
+
+def load_activation() -> dict:
+    if not ACTIVATION_FILE.exists():
+        return dict(DEFAULT_ACTIVATION)
+    try:
+        with open(ACTIVATION_FILE, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return {**DEFAULT_ACTIVATION, **data}
+    except Exception:  # noqa: BLE001
+        return dict(DEFAULT_ACTIVATION)
+
+
+def save_activation(target_url: str, enabled: bool = True) -> dict:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    cfg = {
+        "target_url": target_url,
+        "enabled": enabled,
+        "updated_at": _now(),
+    }
+    with _lock:
+        with open(ACTIVATION_FILE, "w", encoding="utf-8") as f:
+            json.dump(cfg, f, ensure_ascii=False, indent=2)
+    log.info("Activation target saved: %s (enabled=%s)", target_url, enabled)
+    return cfg
+
+
+def reset_activation() -> dict:
+    """Reset activation to default (disabled) so each fresh run starts at the
+    landing page's ACTIVATE button."""
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    with _lock:
+        with open(ACTIVATION_FILE, "w", encoding="utf-8") as f:
+            json.dump(dict(DEFAULT_ACTIVATION), f, ensure_ascii=False, indent=2)
+    log.info("Activation reset to default (fresh demo).")
+    return dict(DEFAULT_ACTIVATION)

backend/classifier.py

@@ -0,0 +1,187 @@
+# =============================================================================
+# PRIVACY BY DESIGN -- InfoShield local classifier
+# -----------------------------------------------------------------------------
+# This module classifies the *content* of a post and nothing else. It never
+# receives, stores, or considers usernames, handles, display names, avatars,
+# follower counts, or any author identity. Classification is content-only and
+# author-agnostic by construction: the only input is a string of post text.
+# All inference runs locally; no text leaves the machine from this module.
+# =============================================================================
+"""Local hate-speech / harmful-content classifier.
+
+Heavy ML imports (torch, transformers) are deferred until the model is actually
+loaded so the backend can start in cache-first mode without them installed.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from typing import Optional
+
+from config import (
+    FALLBACK_MODEL,
+    FLAG_THRESHOLD,
+    HIGH_CONFIDENCE,
+    MAX_TOKENS,
+    PRIMARY_MODEL,
+    SANITY_PROBES,
+)
+
+log = logging.getLogger("infoshield.classifier")
+
+# Resolving which output index is the "harmful" class is subtle: labels like
+# "NOT-HATE" / "NON_HATE" contain the substring "hate", so naive substring
+# matching inverts the map. We detect negation by TOKEN (split on space/_/-) and
+# only then look for a hate-like substring.
+_HATE_SUBSTR = ("hate", "toxic", "offensive", "abusive", "hateful")
+_NEG_TOKENS = {"not", "non", "none", "neither", "normal", "neutral", "clean", "no", "ok", "negative"}
+
+
+class HateClassifier:
+    """Lazy, device-aware wrapper around a HF sequence-classification model."""
+
+    def __init__(self) -> None:
+        self._pipeline = None
+        self._tokenizer = None
+        self._model = None
+        self._hate_index: Optional[int] = None
+        self.model_name: Optional[str] = None
+        self.device: str = "cpu"
+        self.warmup_ms: Optional[float] = None
+        self.loaded: bool = False
+
+    # -- loading -----------------------------------------------------------
+    def load(self) -> None:
+        if self.loaded:
+            return
+        import torch  # deferred
+        from transformers import (
+            AutoModelForSequenceClassification,
+            AutoTokenizer,
+        )
+
+        self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        if self.device == "cpu":
+            log.warning("CUDA not available -- running classifier on CPU (slower).")
+        else:
+            log.info("CUDA available -- running classifier on GPU.")
+
+        last_err: Optional[Exception] = None
+        for name in (PRIMARY_MODEL, FALLBACK_MODEL):
+            try:
+                log.info("Loading classifier '%s' ...", name)
+                self._tokenizer = AutoTokenizer.from_pretrained(name)
+                self._model = AutoModelForSequenceClassification.from_pretrained(name)
+                self._model.to(self.device)
+                self._model.eval()
+                self.model_name = name
+                self._resolve_hate_index()
+                break
+            except Exception as exc:  # noqa: BLE001 - try fallback
+                log.warning("Failed to load '%s': %s", name, exc)
+                last_err = exc
+                self._model = None
+        if self._model is None:
+            raise RuntimeError(f"Could not load any classifier model: {last_err}")
+
+        self._warmup()
+        self._sanity_check()
+        self.loaded = True
+
+    def _resolve_hate_index(self) -> None:
+        import re
+
+        id2label = {int(k): v.lower() for k, v in self._model.config.id2label.items()}
+        for idx, label in id2label.items():
+            tokens = set(re.split(r"[\s_\-]+", label))
+            is_negated = bool(tokens & _NEG_TOKENS)
+            is_hate = any(h in label for h in _HATE_SUBSTR)
+            if is_hate and not is_negated:  # e.g. "hate" yes, "not-hate" no
+                self._hate_index = idx
+                break
+        if self._hate_index is None:
+            # Binary models without descriptive labels: assume index 1 = positive.
+            self._hate_index = 1 if len(id2label) == 2 else max(id2label)
+        log.info("Resolved label map %s -> hate index %d", id2label, self._hate_index)
+
+    # -- inference ---------------------------------------------------------
+    def _hate_probability(self, text: str) -> tuple[float, bool, dict]:
+        import torch
+
+        enc = self._tokenizer(
+            text,
+            return_tensors="pt",
+            truncation=True,
+            max_length=MAX_TOKENS,
+            return_overflowing_tokens=False,
+        )
+        truncated = bool(enc["input_ids"].shape[1] >= MAX_TOKENS)
+        enc = {k: v.to(self.device) for k, v in enc.items() if k in ("input_ids", "attention_mask")}
+        with torch.no_grad():
+            logits = self._model(**enc).logits[0]
+            probs = torch.softmax(logits, dim=-1).cpu().tolist()
+        id2label = self._model.config.id2label
+        raw = {id2label[i]: round(float(p), 4) for i, p in enumerate(probs)}
+        return float(probs[self._hate_index]), truncated, raw
+
+    def classify(self, text: str) -> dict:
+        """Return a content-only classification dict for `text`."""
+        if not text or not text.strip():
+            # Empty / whitespace -> NOT_HATE without a model call.
+            return {
+                "label": "NOT_HATE",
+                "flagged": False,
+                "confidence": 0.0,
+                "high_confidence": False,
+                "truncated": False,
+                "raw_scores": {},
+                "model": self.model_name,
+            }
+        if not self.loaded:
+            self.load()
+        prob, truncated, raw = self._hate_probability(text)
+        flagged = prob >= FLAG_THRESHOLD
+        return {
+            "label": "HATE" if flagged else "NOT_HATE",
+            "flagged": flagged,
+            "confidence": round(prob, 4),
+            "high_confidence": prob >= HIGH_CONFIDENCE,
+            "truncated": truncated,
+            "raw_scores": raw,
+            "model": self.model_name,
+        }
+
+    # -- startup checks ----------------------------------------------------
+    def _warmup(self) -> None:
+        start = time.perf_counter()
+        self._hate_probability("This is a warmup inference for InfoShield.")
+        self.warmup_ms = round((time.perf_counter() - start) * 1000, 1)
+        log.info("Warmup inference on %s took ~%.1f ms", self.device, self.warmup_ms)
+
+    def _sanity_check(self) -> None:
+        """Run label-mapping probes; fail loudly if the map looks inverted."""
+        failures = []
+        for text, expect_hate in SANITY_PROBES:
+            prob, _, _ = self._hate_probability(text)
+            got_hate = prob >= FLAG_THRESHOLD
+            mark = "ok" if got_hate == expect_hate else "MISMATCH"
+            log.info("Sanity probe (%s): expect_hate=%s prob=%.3f", mark, expect_hate, prob)
+            if got_hate != expect_hate:
+                failures.append((text, expect_hate, prob))
+        if failures:
+            raise RuntimeError(
+                "Classifier label-mapping sanity check FAILED -- labels may be "
+                f"inverted. Failures: {failures}"
+            )
+        log.info("Label-mapping sanity check passed.")
+
+
+# Module-level singleton (lazy).
+_classifier: Optional[HateClassifier] = None
+
+
+def get_classifier() -> HateClassifier:
+    global _classifier
+    if _classifier is None:
+        _classifier = HateClassifier()
+    return _classifier

backend/config.py

@@ -0,0 +1,299 @@
+"""Central configuration for the InfoShield backend.
+
+Everything tunable lives here: model ids, thresholds, file paths, ports, the
+technique allowlist, and the Gemini system instruction. No secrets are stored
+here -- the Gemini key is read from the environment (.env).
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+BASE_DIR = Path(__file__).resolve().parent
+DATA_DIR = BASE_DIR / "data"
+MODELS_DIR = BASE_DIR / "models"
+
+load_dotenv(BASE_DIR.parent / ".env")
+
+# --- Networking -----------------------------------------------------------
+HOST = os.getenv("INFOSHIELD_HOST", "127.0.0.1")
+PORT = int(os.getenv("INFOSHIELD_PORT", "5050"))
+# The Vite dev server that hosts the landing + social pages.
+FRONTEND_ORIGIN = os.getenv("INFOSHIELD_FRONTEND", "http://localhost:5173")
+
+# --- Files ----------------------------------------------------------------
+POSTS_FILE = DATA_DIR / "posts.json"
+CACHE_FILE = DATA_DIR / "cache.json"
+ACTIVATION_FILE = DATA_DIR / "activation.json"
+
+# Reset activation to default (disabled) on each backend start so every demo run
+# begins at the landing page's ACTIVATE button. Set =0 to keep the saved target.
+RESET_ACTIVATION_ON_START = os.getenv("INFOSHIELD_RESET_ACTIVATION", "1") == "1"
+
+# Bump when the analysis pipeline/output shape changes so an old cache.json is
+# auto-discarded and rebuilt (rather than serving stale results).
+CACHE_VERSION = 4
+
+# --- Hate classifier (multilingual) ---------------------------------------
+# XLM-T multilingual offensive/hate detector (binary). Falls back to the proven
+# English model if the multilingual download is unavailable.
+PRIMARY_MODEL = "Andrazp/multilingual-hate-speech-robacofi"
+FALLBACK_MODEL = "cardiffnlp/twitter-roberta-base-hate-latest"
+
+FLAG_THRESHOLD = 0.40   # tuned for the XLM-T head (benign ~0.00, hate ~0.47-0.89)
+HIGH_CONFIDENCE = 0.80
+MAX_TOKENS = 512  # truncation ceiling for the classifier
+
+# --- Manipulation classifier (multilingual) -------------------------------
+# Multilingual mBART persuasion-technique detector (SemEval taxonomy, multi-label).
+# The manipulation score is the strongest *concrete technique* probability
+# (structural taxonomy nodes are excluded -- see manip_classifier). Falls back to
+# the English propaganda model if unavailable.
+MANIP_MODEL = "nishan-chatterjee/multilingual-persuasion-detection-from-text"
+MANIP_FALLBACK_MODEL = "synapti/nci-social-classifier-v3"
+
+# Probes used at startup to catch inverted label maps. Each must classify in
+# the expected direction or the loader raises loudly.
+SANITY_PROBES = [
+    ("I love spending the afternoon reading in the park.", False),
+    ("Have a wonderful day, everyone!", False),
+    ("Those people are vermin and should be wiped out.", True),
+]
+
+# --- LLM providers (analysis + verifier) ----------------------------------
+# Analysis provider runs the educational explanation. Default: Gemini.
+LLM_PROVIDER = os.getenv("INFOSHIELD_LLM_PROVIDER", "gemini").strip().lower()
+
+# Second-pass verifier (LLM-as-judge that overturns false positives). Runs on the
+# stronger Gemini Pro model by default; analysis runs on the faster Flash model.
+VERIFIER_PROVIDER = os.getenv("INFOSHIELD_VERIFIER_PROVIDER", LLM_PROVIDER).strip().lower()
+VERIFIER_MODEL = os.getenv("INFOSHIELD_VERIFIER_MODEL", "gemini-3.1-pro-preview").strip()
+
+# A post is flagged for manipulation when the local manipulation model's score is
+# at/above this. The detector is tuned for RECALL because the verifier LLM removes
+# the resulting false positives -- detector finds candidates, verifier confirms.
+# Tuned for the mBART persuasion head (benign <=~0.46, manipulation >=~0.59).
+MANIP_THRESHOLD = float(os.getenv("INFOSHIELD_MANIP_THRESHOLD", "0.50"))
+
+# --- Groq -----------------------------------------------------------------
+GROQ_API_KEY = os.getenv("GROQ_API_KEY", "").strip()
+GROQ_MODEL = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
+
+# --- Gemini ---------------------------------------------------------------
+GEMINI_API_KEY = os.getenv("GEMINI_API_KEY", "").strip()
+GEMINI_MODEL = "gemini-3.5-flash"
+
+ALLOWED_TECHNIQUES = [
+    "fear_amplification",
+    "scapegoating",
+    "us_vs_them",
+    "dehumanizing_language",
+    "false_urgency",
+    "emotional_manipulation",
+    "identity_targeting",
+    "ad_hominem",
+]
+
+# Human-readable labels for technique chips and the insights widget.
+TECHNIQUE_LABELS = {
+    "fear_amplification": "Fear Amplification",
+    "scapegoating": "Scapegoating",
+    "us_vs_them": "Us vs. Them",
+    "dehumanizing_language": "Dehumanizing Language",
+    "false_urgency": "False Urgency",
+    "emotional_manipulation": "Emotional Manipulation",
+    "identity_targeting": "Identity Targeting",
+    "ad_hominem": "Ad Hominem",
+}
+
+MAX_EXPLANATION_CHARS = 400
+
+# ===========================================================================
+# LLM PROMPTS  -- research-grounded, rights-preserving, JSON-only output.
+# {text} = the post; {kind}/{analysis} = filled for the verifier only.
+# Analysis/verifier/rephrase prompts go through str.format(): literal JSON braces
+# are doubled {{ }}; only {text}/{kind}/{analysis} stay single. The SYSTEM strings
+# are used directly (never .format()-ed), so their braces are literal.
+# ===========================================================================
+
+# Official human-rights / media-literacy sources the analysis may cite (allowlist
+# only -- prevents hallucinated links).
+LEGAL_SOURCE_URLS = [
+    "https://treaties.un.org/doc/Treaties/1976/03/19760323%2006-17%20AM/Ch_IV_04.pdf",
+    "https://www.ohchr.org/en/documents/general-comments-and-recommendations/general-comment-no34-article-19-freedoms-opinion-and",
+    "https://www.ohchr.org/en/documents/outcome-documents/rabat-plan-action",
+    "https://www.ohchr.org/en/documents/tools-and-resources/one-pager-incitement-hatred-rabat-threshold-test",
+    "https://www.un.org/en/hate-speech/un-strategy-and-plan-of-action-on-hate-speech",
+    "https://www.unesco.org/en/media-information-literacy",
+    "https://www.unesco.org/en/articles/guidelines-governance-digital-platforms",
+    "https://www.unesco.org/en/social-media4peace",
+    "https://digitallibrary.un.org/record/3987886",
+]
+
+LEGAL_SOURCE_URLS_TEXT = "\n".join(f"- {url}" for url in LEGAL_SOURCE_URLS)
+
+COMMON_JSON_RULES = (
+    "Output EXACTLY one valid JSON object using double quotes for every key and string. "
+    "No markdown, no code fences, no comments, no trailing commas, and no extra text before or after the JSON. "
+    "Use exactly these keys and no others: "
+    "{\"techniques\": [\"...\"], \"emotional_triggers\": [\"...\"], \"explanation\": \"...\", "
+    "\"recommendation\": \"...\", \"severity\": \"low|medium|high\", "
+    "\"highlights\": [{\"phrase\": \"...\", \"type\": \"...\", \"label\": \"...\"}], "
+    "\"bias_check\": \"...\", \"citations\": [\"https://...\"]}. "
+    "The arrays may be empty, but the keys must always be present. "
+    "Every value in techniques must be one of the allowed technique ids. "
+    "Every highlight.phrase must be copied VERBATIM from the post text. "
+    "Keep explanation under 400 characters and recommendation to one calm sentence. "
+    "bias_check must be a neutral sentence explaining how you checked the text against free-expression protections and non-discrimination safeguards. "
+    "citations must contain 2 to 5 exact URLs, chosen ONLY from this allowlist, and ONLY if they are genuinely relevant to your reasoning:\n"
+    f"{LEGAL_SOURCE_URLS_TEXT}\n"
+    "If the content is protected or benign, cite the speech-protective sources you relied on."
+)
+
+# Shared system instruction for the ANALYSIS pass (hate + manipulation).
+ANALYSIS_SYSTEM_INSTRUCTION = f"""
+You are an expert analyst of media literacy, international human rights law, and algorithmic fairness.
+
+Start from a speech-protective baseline. The right to freedom of opinion and expression is the default rule. Do not label content as hate speech or manipulation merely because it is offensive, emotional, partisan, sarcastic, unconventional, oppositional, or unpopular.
+
+Apply these safeguards in every case:
+- Protect political dissent, criticism of governments, parties, leaders, public institutions, religions as belief systems, ideologies, or public policies.
+- Protect satire, humor, artistic expression, quotation, counterspeech, reporting, academic discussion, and historical or religious commentary unless the post itself clearly endorses hatred or coercive manipulation.
+- Do not discriminate against minority dialects, colloquialisms, code-switching, transliteration, reclaimed language, disability-related speech patterns, youth slang, or culturally specific vernacular.
+- Never infer hateful intent or manipulative intent from spelling, grammar, identity, nationality, religion, ethnicity, or language variety alone.
+- If the evidence is mixed or ambiguous, prefer the less restrictive answer: empty techniques and severity "low".
+
+For hate analysis, use the Rabat six-part threshold as a HIGH threshold for incitement: context, speaker, intent, content/form, extent, and likelihood including imminence. Negligence or mere offensiveness is not enough. Do not make legal conclusions; produce an educational assessment grounded in these standards.
+
+For manipulation analysis, treat manipulation as a media-literacy judgment, not a criminal or legal accusation. Do not equate ordinary persuasion, activism, campaigning, moral argument, religious preaching, personal testimony, or emotional storytelling with manipulation unless the text itself clearly uses one or more of the allowed techniques in a way that pressures, dehumanizes, scapegoats, or polarizes.
+
+{COMMON_JSON_RULES}
+""".strip()
+GEMINI_SYSTEM_INSTRUCTION = ANALYSIS_SYSTEM_INSTRUCTION  # back-compat alias
+
+# ---- (3) HATE-SPEECH analysis prompt -- used when the HATE model flags --------
+HATE_ANALYSIS_PROMPT = """
+A local classifier flagged the post below as likely HATE SPEECH. Re-check the text carefully using international human rights standards that strongly protect freedom of expression.
+
+Only identify hate-related techniques when the post itself clearly targets a protected group or a person as a proxy for a protected group through identity-based degradation, dehumanization, scapegoating, exclusion, or advocacy of discrimination, hostility, or violence. Use the Rabat threshold factors to calibrate severity: context, speaker, intent, content/form, extent, and likelihood/imminence.
+
+Do NOT flag as hate merely because the text:
+- expresses a political opinion, policy preference, protest slogan, or criticism of a state, government, party, movement, or religion as a doctrine;
+- contains profanity, ridicule, satire, exaggeration, a quote, reportage, or counterspeech;
+- uses minority dialect, cultural vernacular, reclaimed language, slang, code-switching, transliteration, or imperfect grammar;
+- insults a specific individual without targeting a protected identity group.
+
+Severity guide:
+- low = protected, ambiguous, quoted, satirical, reported, counterspeech, or otherwise not a genuine identity-based attack.
+- medium = clear identity-based hostility or degrading language, but incitement to discrimination, hostility, or violence is not strongly established.
+- high = explicit or strongly implied advocacy or encouragement of discrimination, hostility, or violence, especially where Rabat factors show intent, directness, reach, and likelihood of harm.
+
+Field meanings:
+- techniques: array using ONLY these ids that truly apply: dehumanizing_language, identity_targeting, scapegoating, us_vs_them, fear_amplification, ad_hominem, false_urgency, emotional_manipulation.
+- emotional_triggers: short phrases naming the emotions or social pressures actually used (e.g. fear, disgust, humiliation, anger, social exclusion, threat).
+- explanation: concise neutral explanation of HOW the wording works. Do not call the author evil, criminal, extremist, or unlawful.
+- recommendation: calm, non-judgmental reading advice for the audience.
+- severity: low, medium, or high.
+- highlights: array of objects {{"phrase": "...", "type": "...", "label": "..."}} where phrase is copied VERBATIM from the post, type is one allowed technique id, and label is a short human-readable label.
+- bias_check: one neutral sentence stating that you checked the text against Article 19 free-expression protections, Rabat's high threshold for incitement, and non-discrimination safeguards for satire, quotation, counterspeech, and minority vernacular.
+- citations: 2 to 5 exact allowlisted URLs supporting your reasoning. Use speech-protective sources when the text does NOT clearly cross the threshold.
+
+Important decision rule: if the text is ordinary opinion, satire, banter, a life update, factual reporting, criticism of power, or otherwise does NOT genuinely attack or dehumanize a protected group, then return techniques as [], highlights as [], severity as "low", and explain briefly why the expression remains protected.
+
+POST TEXT:
+\"\"\"
+{text}
+\"\"\"
+""".strip()
+
+# ---- (4) MANIPULATION analysis prompt -- used when the MANIPULATION model flags
+MANIPULATION_ANALYSIS_PROMPT = """
+A local classifier flagged the post below as likely MANIPULATION / propaganda. Re-check the text as an educational media-literacy task while preserving freedom of expression.
+
+This is NOT a legal judgment and NOT a fact-check. Judge only whether the wording itself clearly uses one or more of the allowed narrative techniques to pressure, polarize, scapegoat, dehumanize, or emotionally steer the reader.
+
+Do NOT label as manipulation merely because the text:
+- expresses a strong opinion, campaign message, activism, moral appeal, religious view, or political dissent;
+- is emotional, humorous, sarcastic, poetic, speculative, or personal;
+- comes from a marginalized community, uses a minority dialect or vernacular, or reflects translation artifacts;
+- makes a controversial claim without, by itself, using a manipulative technique from the allowed list.
+
+Treat the following as stronger evidence of manipulation only when clearly present in the actual wording: fear escalation without grounding, scapegoating, identity-based blame, us-versus-them framing, dehumanization, false urgency, ad hominem distraction, or emotionally coercive framing. If those signals are weak, speculative, or explainable as normal advocacy, return empty techniques and severity "low".
+
+Severity guide:
+- low = ordinary persuasion, opinion, advocacy, satire, or unclear evidence of manipulation.
+- medium = one or more concrete techniques are present, but the pressure or polarization is limited.
+- high = multiple explicit techniques used in a strong, coordinated, or highly coercive way, especially where identity-based blame or dehumanization sharply increases risk.
+
+Field meanings:
+- techniques: array using ONLY these ids that truly apply: fear_amplification, scapegoating, us_vs_them, dehumanizing_language, false_urgency, emotional_manipulation, identity_targeting, ad_hominem.
+- emotional_triggers: short phrases naming the emotions or social pressures actually used.
+- explanation: concise neutral explanation of HOW the wording tries to influence the reader. Focus on rhetoric, not truth adjudication.
+- recommendation: calm, non-judgmental advice encouraging reflection or verification before reacting or sharing.
+- severity: low, medium, or high.
+- highlights: array of objects {{"phrase": "...", "type": "...", "label": "..."}} where phrase is copied VERBATIM from the post, type is one allowed technique id, and label is a short human-readable label.
+- bias_check: one neutral sentence stating that you checked for false positives against Article 19 protections, satire, ordinary advocacy, cultural and linguistic nuance, and non-discrimination.
+- citations: 2 to 5 exact allowlisted URLs supporting your reasoning. Use media-literacy and freedom-of-expression sources that actually match the decision.
+
+Important decision rule: if the text is a joke, hot take, ordinary advocacy, personal opinion, factual statement, or emotional expression without clear manipulative technique, return techniques as [], highlights as [], severity as "low", and explain briefly why the expression should not be over-classified.
+
+POST TEXT:
+\"\"\"
+{text}
+\"\"\"
+""".strip()
+
+# ---- (2) VERIFIER prompt -- second-pass judge that overturns false positives --
+VERIFIER_SYSTEM_INSTRUCTION = (
+    "You are a strict, fair reviewer of automated content analysis. You judge ONLY "
+    "whether an analysis accurately and relevantly describes the given post while "
+    "respecting freedom of expression and non-discrimination. You are not political. "
+    "Respond ONLY with valid JSON, no markdown."
+)
+VERIFIER_PROMPT = """
+A post was automatically flagged as {kind} and the ANALYSIS below was produced.
+
+Decide whether that analysis is ACCURATE and RELEVANT to the post.
+
+Be STRICT and speech-protective. Mark relevant=false if the analysis overreaches, ignores Article 19 protections, ignores the Rabat high threshold where relevant, relies on stereotypes, mistakes dialect or vernacular for risk, treats satire or quotation as endorsement, or labels ordinary opinion, activism, reporting, humor, criticism of power, or a factual statement as hate/manipulation without clear textual evidence.
+
+For hate cases, reject the analysis unless the post genuinely shows identity-based degradation, dehumanization, scapegoating, or advocacy/incitement. For manipulation cases, reject it unless the post genuinely uses concrete rhetorical techniques from the allowed list rather than ordinary persuasion.
+
+You may also mark relevant=false if highlights are not verbatim, techniques are unsupported by the text, bias_check is inconsistent with the post, or citations are irrelevant or obviously invented.
+
+Return JSON only: {{"relevant": true|false, "reason": "one short sentence"}}.
+
+POST TEXT:
+\"\"\"
+{text}
+\"\"\"
+
+ANALYSIS (JSON):
+{analysis}
+""".strip()
+
+# ---- (5) REPHRASE prompt -- live compose-assist: rewrite the user's own draft --
+REPHRASE_SYSTEM_INSTRUCTION = (
+    "You help people express their own point respectfully. You preserve the author's "
+    "viewpoint, opinion, and legitimate criticism; you never censor, never flip the "
+    "stance, and never add new claims. You only remove manipulative or hateful framing. "
+    "Respond ONLY with valid JSON, no markdown."
+)
+REPHRASE_PROMPT = """
+Rewrite the social-media post below so it makes the SAME point in a respectful, non-manipulative way.
+
+Rules:
+- Keep the author's core message, opinion, and any legitimate criticism of governments, institutions, policies, or ideas.
+- Remove only manipulative or hateful framing: fear-mongering, false urgency, us-versus-them framing, scapegoating, dehumanizing or identity-based attacks, and ad hominem.
+- Keep it natural, in the SAME language as the original, and similar length. Do not censor the viewpoint, do not moralize, do not add disclaimers, and do not invent facts.
+- If the post is already respectful, return it essentially unchanged.
+
+Return JSON only: {{"rephrased": "..."}}.
+
+POST TEXT:
+\"\"\"
+{text}
+\"\"\"
+""".strip()

backend/data/cache.json

@@ -0,0 +1,795 @@
+{
+  "meta": {
+    "model": "Andrazp/multilingual-hate-speech-robacofi",
+    "device": "cpu",
+    "warmup_ms": 125.0,
+    "llm_provider": "gemini",
+    "llm": true,
+    "built_at": "2026-06-17T23:00:01+00:00",
+    "version": 4
+  },
+  "posts": {
+    "p1": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.5091,
+        "hate_confidence": 0.0022,
+        "manipulation_confidence": 0.5091,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9978,
+          "offensive": 0.0022
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "Analysis accurately describes the post as lacking manipulative techniques.",
+          "checked": true
+        }
+      },
+      "analysis": null
+    },
+    "p8": {
+      "classification": {
+        "label": "FLAGGED",
+        "flagged": true,
+        "kind": "manipulation",
+        "confidence": 0.6559,
+        "hate_confidence": 0.0005,
+        "manipulation_confidence": 0.6559,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9995,
+          "offensive": 0.0005
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "The post uses fear and urgency to influence the reader.",
+          "checked": true
+        }
+      },
+      "analysis": {
+        "techniques": [
+          "fear_amplification",
+          "false_urgency",
+          "emotional_manipulation"
+        ],
+        "emotional_triggers": [
+          "fear",
+          "urgency"
+        ],
+        "explanation": "The post uses fear and urgency to influence the reader, implying a loss of control over personal finances.",
+        "recommendation": "Verify the information through reputable sources before reacting or sharing.",
+        "severity": "medium",
+        "highlights": [
+          {
+            "phrase": "They don't want you to know this",
+            "type": "fear_amplification",
+            "label": "Conspiratorial tone"
+          },
+          {
+            "phrase": "switch off your bank account with a single click",
+            "type": "fear_amplification",
+            "label": "Fear of financial control"
+          },
+          {
+            "phrase": "Screenshot this before it gets taken down",
+            "type": "false_urgency",
+            "label": "Urgency and scarcity"
+          }
+        ],
+        "bias_check": "I checked the text against Article 19 protections, satire, ordinary advocacy, cultural and linguistic nuance, and non-discrimination to avoid false positives.",
+        "citations": [
+          "https://www.ohchr.org/en/documents/general-comments-and-recommendations/general-comment-no34-article-19-freedoms-opinion-and",
+          "https://www.unesco.org/en/media-information-literacy",
+          "https://www.unesco.org/en/articles/guidelines-governance-digital-platforms"
+        ],
+        "source": "llm",
+        "kind": "manipulation"
+      }
+    },
+    "v1": {
+      "classification": {
+        "label": "FLAGGED",
+        "flagged": true,
+        "kind": "manipulation",
+        "confidence": 0.5944,
+        "hate_confidence": 0.0004,
+        "manipulation_confidence": 0.5944,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9996,
+          "offensive": 0.0004
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "The post uses language that creates a sense of urgency and emotional appeal to prompt sharing.",
+          "checked": true
+        }
+      },
+      "analysis": {
+        "techniques": [
+          "false_urgency",
+          "emotional_manipulation"
+        ],
+        "emotional_triggers": [
+          "urgency",
+          "exclusivity"
+        ],
+        "explanation": "The post uses false urgency and emotional manipulation to prompt sharing.",
+        "recommendation": "Verify the content before sharing to ensure it's accurate and not misleading.",
+        "severity": "medium",
+        "highlights": [
+          {
+            "phrase": "Watch before they take it down",
+            "type": "false_urgency",
+            "label": "Urgency"
+          },
+          {
+            "phrase": "Share it NOW while you still can",
+            "type": "emotional_manipulation",
+            "label": "Emotional Appeal"
+          }
+        ],
+        "bias_check": "The post was checked against Article 19 protections, satire, ordinary advocacy, cultural and linguistic nuance, and non-discrimination to avoid false positives.",
+        "citations": [
+          "https://www.ohchr.org/en/documents/general-comments-and-recommendations/general-comment-no34-article-19-freedoms-opinion-and",
+          "https://www.unesco.org/en/media-information-literacy",
+          "https://www.unesco.org/en/articles/guidelines-governance-digital-platforms"
+        ],
+        "source": "llm",
+        "kind": "manipulation"
+      }
+    },
+    "p16": {
+      "classification": {
+        "label": "FLAGGED",
+        "flagged": true,
+        "kind": "manipulation",
+        "confidence": 0.7333,
+        "hate_confidence": 0.27,
+        "manipulation_confidence": 0.7333,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.73,
+          "offensive": 0.27
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "The post contains dehumanizing language and scapegoating towards a group.",
+          "checked": true
+        }
+      },
+      "analysis": {
+        "techniques": [
+          "dehumanizing_language",
+          "scapegoating",
+          "us_vs_them"
+        ],
+        "emotional_triggers": [
+          "fear",
+          "anger",
+          "disgust"
+        ],
+        "explanation": "The wording uses dehumanizing language and scapegoating to create fear and anger towards a group.",
+        "recommendation": "Consider the potential harm of such rhetoric before sharing or reacting.",
+        "severity": "high",
+        "highlights": [
+          {
+            "phrase": "vermin who swarm in and bleed this place dry",
+            "type": "dehumanizing_language",
+            "label": "Dehumanizing comparison"
+          },
+          {
+            "phrase": "They don't belong here and they should be driven out",
+            "type": "scapegoating",
+            "label": "Scapegoating and exclusion"
+          }
+        ],
+        "bias_check": "I checked the text against Article 19 protections, considering the context of satire, ordinary advocacy, cultural and linguistic nuance, and non-discrimination to avoid false positives.",
+        "citations": [
+          "https://www.ohchr.org/en/documents/outcome-documents/rabat-plan-action",
+          "https://www.un.org/en/hate-speech/un-strategy-and-plan-of-action-on-hate-speech",
+          "https://www.unesco.org/en/media-information-literacy"
+        ],
+        "source": "llm",
+        "kind": "manipulation"
+      }
+    },
+    "p3": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.3213,
+        "hate_confidence": 0.0006,
+        "manipulation_confidence": 0.3213,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9994,
+          "offensive": 0.0006
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": null
+      },
+      "analysis": null
+    },
+    "p10": {
+      "classification": {
+        "label": "FLAGGED",
+        "flagged": true,
+        "kind": "manipulation",
+        "confidence": 0.6714,
+        "hate_confidence": 0.0005,
+        "manipulation_confidence": 0.6714,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9995,
+          "offensive": 0.0005
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "The analysis accurately identifies false urgency and emotional manipulation techniques in the post.",
+          "checked": true
+        }
+      },
+      "analysis": {
+        "techniques": [
+          "false_urgency",
+          "emotional_manipulation"
+        ],
+        "emotional_triggers": [
+          "fear of missing out",
+          "greed"
+        ],
+        "explanation": "The post uses urgency and emotional appeal to create a sense of scarcity and pressure the reader into action.",
+        "recommendation": "Consider verifying the claim and evaluating the opportunity carefully before making a decision.",
+        "severity": "medium",
+        "highlights": [
+          {
+            "phrase": "ONLY 100 spots left",
+            "type": "false_urgency",
+            "label": "Scarcity"
+          },
+          {
+            "phrase": "will be kicking themselves in 6 months",
+            "type": "emotional_manipulation",
+            "label": "Fear of regret"
+          }
+        ],
+        "bias_check": "I checked the post against Article 19 protections, satire, ordinary advocacy, cultural and linguistic nuance, and non-discrimination to ensure it was not over-classified.",
+        "citations": [
+          "https://www.ohchr.org/en/documents/general-comments-and-recommendations/general-comment-no34-article-19-freedoms-opinion-and",
+          "https://www.unesco.org/en/media-information-literacy",
+          "https://www.unesco.org/en/articles/guidelines-governance-digital-platforms"
+        ],
+        "source": "llm",
+        "kind": "manipulation"
+      }
+    },
+    "p15": {
+      "classification": {
+        "label": "FLAGGED",
+        "flagged": true,
+        "kind": "manipulation",
+        "confidence": 0.786,
+        "hate_confidence": 0.0466,
+        "manipulation_confidence": 0.786,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9534,
+          "offensive": 0.0466
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "The post contains dehumanizing language and scapegoating that meets the Rabat high threshold for hate speech.",
+          "checked": true
+        }
+      },
+      "analysis": {
+        "techniques": [
+          "us_vs_them",
+          "scapegoating",
+          "dehumanizing_language"
+        ],
+        "emotional_triggers": [
+          "fear",
+          "resentment"
+        ],
+        "explanation": "The wording uses divisive language to create an us-versus-them mentality and scapegoats a group for perceived problems.",
+        "recommendation": "Consider verifying information through reputable sources before reacting or sharing.",
+        "severity": "medium",
+        "highlights": [
+          {
+            "phrase": "These people pour into our town",
+            "type": "us_vs_them",
+            "label": "Divisive language"
+          },
+          {
+            "phrase": "don't bother learning how we live",
+            "type": "scapegoating",
+            "label": "Blame assignment"
+          },
+          {
+            "phrase": "breed faster than we can keep up",
+            "type": "dehumanizing_language",
+            "label": "Dehumanizing description"
+          }
+        ],
+        "bias_check": "I checked the text against Article 19 protections, considering satire, ordinary advocacy, cultural and linguistic nuance, and non-discrimination safeguards to avoid false positives.",
+        "citations": [
+          "https://www.ohchr.org/en/documents/outcome-documents/rabat-plan-action",
+          "https://www.un.org/en/hate-speech/un-strategy-and-plan-of-action-on-hate-speech",
+          "https://www.unesco.org/en/media-information-literacy"
+        ],
+        "source": "llm",
+        "kind": "manipulation"
+      }
+    },
+    "p2": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.7405,
+        "hate_confidence": 0.0025,
+        "manipulation_confidence": 0.7405,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9975,
+          "offensive": 0.0025
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": false,
+          "reason": "Analysis incorrectly flags post as manipulation when it is merely an opinion.",
+          "checked": true
+        }
+      },
+      "analysis": null
+    },
+    "p11": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.8512,
+        "hate_confidence": 0.001,
+        "manipulation_confidence": 0.8512,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.999,
+          "offensive": 0.001
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": false,
+          "reason": "Analysis overreaches by labeling ordinary opinion as manipulation without clear textual evidence.",
+          "checked": true
+        }
+      },
+      "analysis": null
+    },
+    "ru1": {
+      "classification": {
+        "label": "FLAGGED",
+        "flagged": true,
+        "kind": "manipulation",
+        "confidence": 0.7999,
+        "hate_confidence": 0.0012,
+        "manipulation_confidence": 0.7999,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9988,
+          "offensive": 0.0012
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "Analysis accurately identifies fear amplification and false urgency techniques in the post.",
+          "checked": true
+        }
+      },
+      "analysis": {
+        "techniques": [
+          "fear_amplification",
+          "false_urgency"
+        ],
+        "emotional_triggers": [
+          "fear",
+          "urgency"
+        ],
+        "explanation": "The text uses fear amplification and false urgency to prompt the reader into action.",
+        "recommendation": "Consider verifying the information before sharing to ensure it's accurate and not misleading.",
+        "severity": "medium",
+        "highlights": [
+          {
+            "phrase": "Они не хотят, чтобы вы это знали",
+            "type": "fear_amplification",
+            "label": "Fear induction"
+          },
+          {
+            "phrase": "пока это не удалили",
+            "type": "false_urgency",
+            "label": "Urgency creation"
+          }
+        ],
+        "bias_check": "The text was checked against Article 19 protections, satire, ordinary advocacy, cultural and linguistic nuance, and non-discrimination to avoid false positives.",
+        "citations": [
+          "https://www.ohchr.org/en/documents/general-comments-and-recommendations/general-comment-no34-article-19-freedoms-opinion-and",
+          "https://www.unesco.org/en/media-information-literacy",
+          "https://www.unesco.org/en/articles/guidelines-governance-digital-platforms"
+        ],
+        "source": "llm",
+        "kind": "manipulation"
+      }
+    },
+    "p17": {
+      "classification": {
+        "label": "FLAGGED",
+        "flagged": true,
+        "kind": "hate",
+        "confidence": 0.9984,
+        "hate_confidence": 0.9984,
+        "manipulation_confidence": 0.8944,
+        "high_confidence": true,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.0016,
+          "offensive": 0.9984
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "The post contains clear dehumanizing language and identity-based degradation.",
+          "checked": true
+        }
+      },
+      "analysis": {
+        "techniques": [
+          "dehumanizing_language",
+          "identity_targeting",
+          "us_vs_them"
+        ],
+        "emotional_triggers": [
+          "fear",
+          "disgust"
+        ],
+        "explanation": "The post uses dehumanizing language and targets a group, implying they are a threat.",
+        "recommendation": "Read with caution, considering the potential for harmful stereotypes.",
+        "severity": "high",
+        "highlights": [
+          {
+            "phrase": "They're animals, plain and simple",
+            "type": "dehumanizing_language",
+            "label": "Dehumanization"
+          },
+          {
+            "phrase": "should be removed from our streets",
+            "type": "identity_targeting",
+            "label": "Targeting a group"
+          }
+        ],
+        "bias_check": "The text was checked against Article 19 free-expression protections, Rabat's high threshold for incitement, and non-discrimination safeguards, but crossed the threshold due to clear dehumanization and targeting.",
+        "citations": [
+          "https://www.ohchr.org/en/documents/outcome-documents/rabat-plan-action",
+          "https://www.un.org/en/hate-speech/un-strategy-and-plan-of-action-on-hate-speech",
+          "https://www.unesco.org/en/articles/guidelines-governance-digital-platforms"
+        ],
+        "source": "llm",
+        "kind": "hate"
+      }
+    },
+    "p5": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.6593,
+        "hate_confidence": 0.0007,
+        "manipulation_confidence": 0.6593,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9993,
+          "offensive": 0.0007
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "The analysis accurately describes the post as lacking manipulative techniques.",
+          "checked": true
+        }
+      },
+      "analysis": null
+    },
+    "p12": {
+      "classification": {
+        "label": "FLAGGED",
+        "flagged": true,
+        "kind": "manipulation",
+        "confidence": 0.8624,
+        "hate_confidence": 0.0005,
+        "manipulation_confidence": 0.8624,
+        "high_confidence": true,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9995,
+          "offensive": 0.0005
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "The analysis accurately identifies fear_amplification, false_urgency, and emotional_manipulation techniques in the post.",
+          "checked": true
+        }
+      },
+      "analysis": {
+        "techniques": [
+          "fear_amplification",
+          "false_urgency",
+          "emotional_manipulation"
+        ],
+        "emotional_triggers": [
+          "fear",
+          "guilt"
+        ],
+        "explanation": "The wording tries to influence the reader by creating fear and guilt about the curriculum's impact on children.",
+        "recommendation": "Verify the information through reputable sources before reacting or sharing.",
+        "severity": "medium",
+        "highlights": [
+          {
+            "phrase": "don't call yourself a real parent",
+            "type": "emotional_manipulation",
+            "label": "Guilt trip"
+          },
+          {
+            "phrase": "destroy your child's mind",
+            "type": "fear_amplification",
+            "label": "Fear escalation"
+          },
+          {
+            "phrase": "Act before it's too late",
+            "type": "false_urgency",
+            "label": "Urgency creation"
+          }
+        ],
+        "bias_check": "I checked the text against Article 19 protections, satire, ordinary advocacy, cultural and linguistic nuance, and non-discrimination to avoid false positives.",
+        "citations": [
+          "https://www.ohchr.org/en/documents/general-comments-and-recommendations/general-comment-no34-article-19-freedoms-opinion-and",
+          "https://www.unesco.org/en/media-information-literacy",
+          "https://www.unesco.org/en/articles/guidelines-governance-digital-platforms"
+        ],
+        "source": "llm",
+        "kind": "manipulation"
+      }
+    },
+    "p18": {
+      "classification": {
+        "label": "FLAGGED",
+        "flagged": true,
+        "kind": "manipulation",
+        "confidence": 0.7491,
+        "hate_confidence": 0.0225,
+        "manipulation_confidence": 0.7491,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9775,
+          "offensive": 0.0225
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "The post contains dehumanizing language and scapegoating towards a group.",
+          "checked": true
+        }
+      },
+      "analysis": {
+        "techniques": [
+          "scapegoating",
+          "dehumanizing_language",
+          "us_vs_them"
+        ],
+        "emotional_triggers": [
+          "fear",
+          "anger",
+          "disgust"
+        ],
+        "explanation": "The wording uses dehumanizing language and scapegoating to create fear and anger towards a group.",
+        "recommendation": "Consider verifying information before reacting or sharing to avoid spreading harmful stereotypes.",
+        "severity": "high",
+        "highlights": [
+          {
+            "phrase": "They've infested every neighborhood they've touched and turned it into a dump",
+            "type": "dehumanizing_language",
+            "label": "Dehumanizing comparison"
+          },
+          {
+            "phrase": "Pack them up and send them back where they came from",
+            "type": "scapegoating",
+            "label": "Scapegoating and expulsion"
+          }
+        ],
+        "bias_check": "I checked the text against Article 19 protections, satire, ordinary advocacy, cultural and linguistic nuance, and non-discrimination to ensure it does not unfairly target a group.",
+        "citations": [
+          "https://www.ohchr.org/en/documents/outcome-documents/rabat-plan-action",
+          "https://www.un.org/en/hate-speech/un-strategy-and-plan-of-action-on-hate-speech",
+          "https://www.unesco.org/en/media-information-literacy"
+        ],
+        "source": "llm",
+        "kind": "manipulation"
+      }
+    },
+    "p7": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.6278,
+        "hate_confidence": 0.0002,
+        "manipulation_confidence": 0.6278,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9998,
+          "offensive": 0.0002
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": false,
+          "reason": "Analysis incorrectly flags post as manipulation when it is ordinary opinion and reflection.",
+          "checked": true
+        }
+      },
+      "analysis": null
+    },
+    "p9": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.9008,
+        "hate_confidence": 0.0004,
+        "manipulation_confidence": 0.9008,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9996,
+          "offensive": 0.0004
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": false,
+          "reason": "The analysis overreaches by labeling ordinary opinion and criticism of power as manipulation without clear textual evidence.",
+          "checked": true
+        }
+      },
+      "analysis": null
+    },
+    "p13": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.7975,
+        "hate_confidence": 0.0012,
+        "manipulation_confidence": 0.7975,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9988,
+          "offensive": 0.0012
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "The analysis accurately identifies the post's use of sarcasm to express frustration.",
+          "checked": true
+        }
+      },
+      "analysis": null
+    },
+    "p4": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.3288,
+        "hate_confidence": 0.001,
+        "manipulation_confidence": 0.3288,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.999,
+          "offensive": 0.001
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": null
+      },
+      "analysis": null
+    },
+    "p14": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.7382,
+        "hate_confidence": 0.0003,
+        "manipulation_confidence": 0.7382,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9997,
+          "offensive": 0.0003
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": true,
+          "reason": "Analysis accurately describes post's cautious skepticism without overreaching.",
+          "checked": true
+        }
+      },
+      "analysis": null
+    },
+    "p6": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.0791,
+        "hate_confidence": 0.0054,
+        "manipulation_confidence": 0.0791,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9946,
+          "offensive": 0.0054
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": null
+      },
+      "analysis": null
+    },
+    "p19": {
+      "classification": {
+        "label": "CLEAR",
+        "flagged": false,
+        "kind": null,
+        "confidence": 0.7153,
+        "hate_confidence": 0.0009,
+        "manipulation_confidence": 0.7153,
+        "high_confidence": false,
+        "truncated": false,
+        "raw_scores": {
+          "not offensive": 0.9991,
+          "offensive": 0.0009
+        },
+        "model": "Andrazp/multilingual-hate-speech-robacofi",
+        "verification": {
+          "relevant": false,
+          "reason": "The analysis overreaches by labeling ordinary opinion as scapegoating without clear textual evidence of identity-based degradation or dehumanization.",
+          "checked": true
+        }
+      },
+      "analysis": null
+    }
+  }
+}

backend/data/posts.json

@@ -0,0 +1,385 @@
+[
+  {
+    "id": "p1",
+    "user": {
+      "name": "Maya Chen",
+      "handle": "maya_codes",
+      "initial": "M",
+      "color": "#2563EB",
+      "verified": false
+    },
+    "time": "12m",
+    "text": "spent three hours debugging today only to realize i'd been editing the wrong file the entire time. anyway. how is everyone's monday going",
+    "media": null,
+    "engagement": {
+      "replies": 156,
+      "reposts": 89,
+      "likes": 1243
+    }
+  },
+  {
+    "id": "p8",
+    "user": {
+      "name": "Truth Hour",
+      "handle": "TheRealTruthHour",
+      "initial": "T",
+      "color": "#DC2626",
+      "verified": false
+    },
+    "time": "26m",
+    "text": "They don't want you to know this, but the new digital ID rolling out next month means they can switch off your bank account with a single click. This is NOT a conspiracy. Screenshot this before it gets taken down. ⏰",
+    "media": null,
+    "engagement": {
+      "replies": 3400,
+      "reposts": 8900,
+      "likes": 12000
+    }
+  },
+  {
+    "id": "v1",
+    "user": {
+      "name": "Truth Unfiltered",
+      "handle": "truth_unfiltered",
+      "initial": "T",
+      "color": "#B91C1C",
+      "verified": false
+    },
+    "time": "22m",
+    "text": "🚨 They're not showing you THIS on the news. Watch before they take it down — this is what they don't want you to see. Share it NOW while you still can, before it's too late.",
+    "media": {
+      "type": "video",
+      "src": "/media/video.mp4"
+    },
+    "engagement": {
+      "replies": 2100,
+      "reposts": 7400,
+      "likes": 9800
+    }
+  },
+  {
+    "id": "p16",
+    "user": {
+      "name": "ZephyrX",
+      "handle": "ZephyrX_",
+      "initial": "Z",
+      "color": "#1F2937",
+      "verified": false
+    },
+    "time": "6h",
+    "text": "Every one of them is the same — vermin who swarm in and bleed this place dry. They don't belong here and they should be driven out before there's nothing left.",
+    "media": null,
+    "engagement": {
+      "replies": 890,
+      "reposts": 1100,
+      "likes": 2300
+    }
+  },
+  {
+    "id": "p3",
+    "user": {
+      "name": "Priya K.",
+      "handle": "aerialnomad",
+      "initial": "P",
+      "color": "#0D9488",
+      "verified": true
+    },
+    "time": "1h",
+    "text": "Sunrise over the valley in Patagonia right now. Some places just don't feel real until you're standing in them. 🏔️",
+    "media": {
+      "type": "gradient"
+    },
+    "engagement": {
+      "replies": 230,
+      "reposts": 1200,
+      "likes": 8900
+    }
+  },
+  {
+    "id": "p10",
+    "user": {
+      "name": "Brad // crypto",
+      "handle": "cryptobrad",
+      "initial": "B",
+      "color": "#F59E0B",
+      "verified": false
+    },
+    "time": "1h",
+    "text": "🚨 ONLY 100 spots left. This is your LAST chance to get in before the price 10x's. The people who hesitate will be kicking themselves in 6 months. DM me NOW or stay broke. 👉 https://t.co/x9f2aQ",
+    "media": null,
+    "engagement": {
+      "replies": 1200,
+      "reposts": 450,
+      "likes": 890
+    }
+  },
+  {
+    "id": "p15",
+    "user": {
+      "name": "Mike",
+      "handle": "patriot_mike49",
+      "initial": "M",
+      "color": "#991B1B",
+      "verified": false
+    },
+    "time": "5h",
+    "text": "These people pour into our town, don't bother learning how we live, and expect us to bend over backwards for them. They breed faster than we can keep up and soon there'll be nothing left of who we are. Enough.",
+    "media": null,
+    "engagement": {
+      "replies": 1200,
+      "reposts": 3400,
+      "likes": 5600
+    }
+  },
+  {
+    "id": "p2",
+    "user": {
+      "name": "Dave R.",
+      "handle": "grillmaster_dave",
+      "initial": "D",
+      "color": "#D97706",
+      "verified": false
+    },
+    "time": "34m",
+    "text": "Unpopular opinion: pineapple absolutely belongs on pizza and I'm tired of pretending it doesn't 🍍",
+    "media": null,
+    "engagement": {
+      "replies": 890,
+      "reposts": 320,
+      "likes": 4500
+    }
+  },
+  {
+    "id": "p11",
+    "user": {
+      "name": "Real Talk Radio",
+      "handle": "realtalkradio",
+      "initial": "R",
+      "color": "#B91C1C",
+      "verified": false
+    },
+    "time": "2h",
+    "text": "Notice how every time regular people start asking real questions, there's suddenly a brand new crisis to distract everyone? That's not a coincidence. They've been running this exact playbook for decades.",
+    "media": null,
+    "engagement": {
+      "replies": 780,
+      "reposts": 5600,
+      "likes": 9800
+    }
+  },
+  {
+    "id": "ru1",
+    "user": {
+      "name": "Дмитрий",
+      "handle": "dmitry_news",
+      "initial": "Д",
+      "color": "#1D4ED8",
+      "verified": false
+    },
+    "time": "40m",
+    "text": "Они не хотят, чтобы вы это знали: новый закон позволит им отключить ваш счёт одним щелчком. Не молчите. Сделайте репост, пока это не удалили.",
+    "media": null,
+    "engagement": {
+      "replies": 980,
+      "reposts": 5200,
+      "likes": 4100
+    }
+  },
+  {
+    "id": "p17",
+    "user": {
+      "name": "Borderwatch",
+      "handle": "borderwatch_now",
+      "initial": "B",
+      "color": "#7F1D1D",
+      "verified": false
+    },
+    "time": "7h",
+    "text": "They're animals, plain and simple, and you can't civilize an animal. People like that should be removed from our streets before they ruin everything.",
+    "media": null,
+    "engagement": {
+      "replies": 1500,
+      "reposts": 2100,
+      "likes": 3400
+    }
+  },
+  {
+    "id": "p5",
+    "user": {
+      "name": "Sam · RN",
+      "handle": "nightshift_sam",
+      "initial": "S",
+      "color": "#7C3AED",
+      "verified": false
+    },
+    "time": "3h",
+    "text": "12 hour shift done. feet wrecked, heart full. a patient's family brought the whole unit donuts today and i nearly cried in the break room. it's the small stuff.",
+    "media": null,
+    "engagement": {
+      "replies": 145,
+      "reposts": 210,
+      "likes": 3400
+    }
+  },
+  {
+    "id": "p12",
+    "user": {
+      "name": "Concerned Parent",
+      "handle": "concerned_parent_99",
+      "initial": "C",
+      "color": "#92400E",
+      "verified": false
+    },
+    "time": "3h",
+    "text": "If you don't share this, don't call yourself a real parent. They are putting things into the curriculum that will destroy your child's mind by next year. Act before it's too late.",
+    "media": null,
+    "engagement": {
+      "replies": 2300,
+      "reposts": 6700,
+      "likes": 4500
+    }
+  },
+  {
+    "id": "p18",
+    "user": {
+      "name": "Old Town Voice",
+      "handle": "oldtownvoice",
+      "initial": "O",
+      "color": "#78350F",
+      "verified": false
+    },
+    "time": "9h",
+    "text": "They've infested every neighborhood they've touched and turned it into a dump. Pack them up and send them back where they came from before there's nothing left of this place.",
+    "media": null,
+    "engagement": {
+      "replies": 1900,
+      "reposts": 2800,
+      "likes": 4500
+    }
+  },
+  {
+    "id": "p7",
+    "user": {
+      "name": "Anna Whitfield",
+      "handle": "historybuff_anna",
+      "initial": "A",
+      "color": "#9333EA",
+      "verified": true
+    },
+    "time": "5h",
+    "text": "people ask why i love history and honestly it's because nothing is ever as simple as the textbook makes it sound. every 'obvious' decision was made by a real person who couldn't see the ending, who was scared and tired and working with bad information. we read the past like the outcome was inevitable, but the people living it had no idea which way it would go. that's the part that stays with me, not the dates or the battles but the uncertainty. it makes me a lot gentler about the present, knowing future generations will flatten us into a tidy paragraph too.",
+    "media": null,
+    "engagement": {
+      "replies": 210,
+      "reposts": 980,
+      "likes": 5600
+    }
+  },
+  {
+    "id": "p9",
+    "user": {
+      "name": "Open Your Eyes",
+      "handle": "wakeup_sheeple",
+      "initial": "O",
+      "color": "#7C2D12",
+      "verified": false
+    },
+    "time": "1h",
+    "text": "Wake up. Everything you were taught was designed to keep you obedient and quiet. The people at the top are laughing at how easy it was. Stop trusting them and start trusting your gut.",
+    "media": null,
+    "engagement": {
+      "replies": 890,
+      "reposts": 4200,
+      "likes": 6700
+    }
+  },
+  {
+    "id": "p13",
+    "user": {
+      "name": "doomscroller",
+      "handle": "doomscroller",
+      "initial": "d",
+      "color": "#475569",
+      "verified": false
+    },
+    "time": "3h",
+    "text": "oh good, another 'once in a lifetime' crisis this week. truly we are so blessed to live through the single most important moment in human history every monday 🙄",
+    "media": null,
+    "engagement": {
+      "replies": 120,
+      "reposts": 670,
+      "likes": 3200
+    }
+  },
+  {
+    "id": "p4",
+    "user": {
+      "name": "Lena Ortiz",
+      "handle": "lena_writes",
+      "initial": "L",
+      "color": "#DB2777",
+      "verified": false
+    },
+    "time": "2h",
+    "text": "finished the first draft of my novel at 2am and immediately started doubting every single word of it. writing is just professionally arguing with yourself.",
+    "media": null,
+    "engagement": {
+      "replies": 98,
+      "reposts": 340,
+      "likes": 2100
+    }
+  },
+  {
+    "id": "p14",
+    "user": {
+      "name": "just asking",
+      "handle": "quiet_observer",
+      "initial": "j",
+      "color": "#64748B",
+      "verified": false
+    },
+    "time": "4h",
+    "text": "i'm not saying anything is definitely wrong with the new policy... but doesn't it feel a little convenient? a lot of people are quietly starting to wonder, and maybe that's worth paying attention to.",
+    "media": null,
+    "engagement": {
+      "replies": 200,
+      "reposts": 340,
+      "likes": 1200
+    }
+  },
+  {
+    "id": "p6",
+    "user": {
+      "name": "Tom B.",
+      "handle": "tom_b",
+      "initial": "T",
+      "color": "#0F172A",
+      "verified": false
+    },
+    "time": "4h",
+    "text": "is it coffee o'clock yet",
+    "media": null,
+    "engagement": {
+      "replies": 34,
+      "reposts": 12,
+      "likes": 540
+    }
+  },
+  {
+    "id": "p19",
+    "user": {
+      "name": "Jane",
+      "handle": "realtalk_jane",
+      "initial": "J",
+      "color": "#a16207",
+      "verified": false
+    },
+    "time": "11h",
+    "text": "funny how a certain kind of people always seem to end up at the center of every single problem in this city. at some point you stop calling it a coincidence.",
+    "media": null,
+    "engagement": {
+      "replies": 600,
+      "reposts": 900,
+      "likes": 1800
+    }
+  }
+]

backend/data/video.mp4

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

backend/llm.py

@@ -0,0 +1,155 @@
+"""Provider-agnostic JSON completion for InfoShield.
+
+`complete_json(system, user, provider=None, model=None)` -> parsed dict (or None).
+Provider defaults to `config.LLM_PROVIDER` ("groq" now, "gemini" later) but can be
+overridden per call -- the verifier uses this to (later) run on a different/best
+model than the analysis. Heavy SDK imports are deferred; missing key/SDK -> None
+so callers fall back gracefully.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Optional
+
+from config import (
+    GEMINI_API_KEY,
+    GEMINI_MODEL,
+    GROQ_API_KEY,
+    GROQ_MODEL,
+    LLM_PROVIDER,
+)
+
+log = logging.getLogger("infoshield.llm")
+
+_clients: dict[str, object] = {}  # provider -> client (or None once tried & failed)
+_tried: set[str] = set()
+
+
+def _coerce_json(text: str) -> Optional[dict]:
+    """Best-effort: parse a JSON object, tolerating stray markdown fences."""
+    if not text:
+        return None
+    text = text.strip()
+    text = re.sub(r"^```(?:json)?", "", text).strip()
+    text = re.sub(r"```$", "", text).strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        m = re.search(r"\{.*\}", text, re.DOTALL)
+        if m:
+            try:
+                return json.loads(m.group(0))
+            except json.JSONDecodeError:
+                return None
+    return None
+
+
+def _has_key(provider: str) -> bool:
+    return bool(GEMINI_API_KEY) if provider == "gemini" else bool(GROQ_API_KEY)
+
+
+def available(provider: Optional[str] = None) -> bool:
+    """True if the (default or given) provider has a key configured."""
+    return _has_key(provider or LLM_PROVIDER)
+
+
+def _get_client(provider: str):
+    if provider in _clients:
+        return _clients[provider]
+    _tried.add(provider)
+    client = None
+    try:
+        if provider == "gemini":
+            if GEMINI_API_KEY:
+                from google import genai  # deferred
+
+                client = genai.Client(api_key=GEMINI_API_KEY)
+                log.info("Gemini client initialized.")
+            else:
+                log.warning("GEMINI_API_KEY not set -- gemini calls unavailable.")
+        else:  # groq
+            if GROQ_API_KEY:
+                from groq import Groq  # deferred
+
+                client = Groq(api_key=GROQ_API_KEY)
+                log.info("Groq client initialized.")
+            else:
+                log.warning("GROQ_API_KEY not set -- groq calls unavailable.")
+    except Exception as exc:  # noqa: BLE001
+        log.warning("Could not initialize %s client: %s", provider, exc)
+        client = None
+    _clients[provider] = client
+    return client
+
+
+# --- completion -----------------------------------------------------------
+def complete_json(
+    system: str,
+    user: str,
+    provider: Optional[str] = None,
+    model: Optional[str] = None,
+    schema: Optional[dict] = None,
+    temperature: float = 0.2,
+) -> Optional[dict]:
+    """Return a parsed JSON object from the chosen provider, or None on failure.
+
+    `schema` is only used by Gemini (structured output); Groq uses JSON-object
+    mode and relies on the prompt + downstream validation.
+    """
+    provider = (provider or LLM_PROVIDER).lower()
+    result = _complete_one(provider, system, user, model, schema, temperature)
+    if result is not None:
+        return result
+    # Resilience: if the chosen provider fails (e.g. Gemini out of credits), fall
+    # back to the other provider using its default model so the demo keeps working.
+    other = "groq" if provider == "gemini" else "gemini"
+    if _has_key(other):
+        log.info("Provider '%s' failed; falling back to '%s'.", provider, other)
+        return _complete_one(other, system, user, None, schema, temperature)
+    return None
+
+
+def _complete_one(provider, system, user, model, schema, temperature):
+    client = _get_client(provider)
+    if client is None:
+        return None
+    if provider == "gemini":
+        return _gemini_complete(client, system, user, model or GEMINI_MODEL, schema, temperature)
+    return _groq_complete(client, system, user, model or GROQ_MODEL, temperature)
+
+
+def _groq_complete(client, system: str, user: str, model: str, temperature: float) -> Optional[dict]:
+    try:
+        resp = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            response_format={"type": "json_object"},
+            temperature=temperature,
+        )
+        return _coerce_json(resp.choices[0].message.content or "")
+    except Exception as exc:  # noqa: BLE001
+        log.warning("Groq call failed: %s", exc)
+        return None
+
+
+def _gemini_complete(client, system: str, user: str, model: str, schema: Optional[dict], temperature: float) -> Optional[dict]:
+    try:
+        from google.genai import types  # deferred
+
+        cfg = types.GenerateContentConfig(
+            system_instruction=system,
+            response_mime_type="application/json",
+            temperature=temperature,
+        )
+        if schema:
+            cfg.response_schema = schema
+        resp = client.models.generate_content(model=model, contents=user, config=cfg)
+        return _coerce_json(getattr(resp, "text", "") or "")
+    except Exception as exc:  # noqa: BLE001
+        log.warning("Gemini call failed: %s", exc)
+        return None

backend/manip_classifier.py

@@ -0,0 +1,156 @@
+# =============================================================================
+# PRIVACY BY DESIGN -- InfoShield local manipulation classifier
+# -----------------------------------------------------------------------------
+# Content-only and author-agnostic, exactly like the hate classifier: the only
+# input is the post text. All inference runs locally.
+# =============================================================================
+"""Local manipulation / propaganda detector (the manipulation GATE).
+
+Mirrors classifier.py but for manipulation. The primary checkpoint is a
+multi-label (sigmoid) propaganda-technique model -- the manipulation score is the
+strongest single technique probability. The fallback is a binary propaganda model
+(softmax over [not, propaganda]). Heavy ML imports are deferred.
+"""
+from __future__ import annotations
+
+import logging
+import re
+import time
+from typing import Optional
+
+from config import MANIP_FALLBACK_MODEL, MANIP_MODEL, MANIP_THRESHOLD, MAX_TOKENS
+
+log = logging.getLogger("infoshield.manip")
+
+_POS_SUBSTR = ("prop", "manip", "persuas", "label_")  # "label_n" => generic multi-label head
+_NEG_TOKENS = {"no", "not", "non", "none", "clean", "neutral", "normal", "negative"}
+
+# Multi-label persuasion models include "negative" and structural taxonomy nodes that
+# fire on almost any text (a root/parent category). We exclude these so the manipulation
+# score is the strongest *concrete technique* probability, not a structural node.
+_STRUCTURAL_LABELS = {
+    "root", "none", "no technique", "no_propaganda", "not offensive",
+    "logos", "ethos", "pathos", "reasoning", "justification",
+}
+
+
+class ManipulationClassifier:
+    """Lazy, device-aware wrapper. Returns a manipulation probability in [0, 1]."""
+
+    def __init__(self) -> None:
+        self._tokenizer = None
+        self._model = None
+        self._multilabel = False
+        self._pos_index: Optional[int] = None
+        self._keep_idx: Optional[list[int]] = None  # technique labels to score over
+        self._max_len = MAX_TOKENS
+        self.model_name: Optional[str] = None
+        self.device: str = "cpu"
+        self.warmup_ms: Optional[float] = None
+        self.loaded: bool = False
+
+    def load(self) -> None:
+        if self.loaded:
+            return
+        import torch  # deferred
+        from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+        self.device = "cuda" if torch.cuda.is_available() else "cpu"
+
+        last_err: Optional[Exception] = None
+        for name in (MANIP_MODEL, MANIP_FALLBACK_MODEL):
+            try:
+                log.info("Loading manipulation model '%s' ...", name)
+                self._tokenizer = AutoTokenizer.from_pretrained(name)
+                self._model = AutoModelForSequenceClassification.from_pretrained(name)
+                self._model.to(self.device)
+                self._model.eval()
+                self.model_name = name
+                self._resolve_head()
+                break
+            except Exception as exc:  # noqa: BLE001 - try fallback
+                log.warning("Failed to load '%s': %s", name, exc)
+                last_err = exc
+                self._model = None
+        if self._model is None:
+            raise RuntimeError(f"Could not load any manipulation model: {last_err}")
+
+        self._warmup()
+        self.loaded = True
+
+    def _resolve_head(self) -> None:
+        cfg = self._model.config
+        n = getattr(cfg, "num_labels", 2) or 2
+        problem = (getattr(cfg, "problem_type", "") or "").lower()
+        # Respect the model's real context window (BERTweet is only 130 positions,
+        # not 512) to avoid position-embedding index errors on long posts.
+        mpe = getattr(cfg, "max_position_embeddings", MAX_TOKENS + 2) or (MAX_TOKENS + 2)
+        self._max_len = min(MAX_TOKENS, max(16, mpe - 2))
+        self._multilabel = problem == "multi_label_classification" or n > 2
+        if self._multilabel:
+            id2label = {int(k): str(v).lower().strip() for k, v in cfg.id2label.items()}
+            self._keep_idx = [i for i, lab in id2label.items() if lab not in _STRUCTURAL_LABELS]
+            if not self._keep_idx:
+                self._keep_idx = list(id2label.keys())
+            log.info("Manipulation head: multi-label (%d labels, %d technique labels scored), "
+                     "score = max sigmoid over techniques.", n, len(self._keep_idx))
+            return
+        # Binary: find the "propaganda/manipulation present" index.
+        id2label = {int(k): str(v).lower() for k, v in cfg.id2label.items()}
+        for idx, label in id2label.items():
+            tokens = set(re.split(r"[\s_\-]+", label))
+            is_pos = any(s in label for s in _POS_SUBSTR) and not (tokens & _NEG_TOKENS)
+            if is_pos:
+                self._pos_index = idx
+                break
+        if self._pos_index is None:
+            self._pos_index = 1 if n == 2 else max(id2label)
+        log.info("Manipulation head: binary, positive index %d (%s).",
+                 self._pos_index, id2label)
+
+    def _probability(self, text: str) -> tuple[float, bool]:
+        import torch
+
+        enc = self._tokenizer(text, return_tensors="pt", truncation=True, max_length=self._max_len)
+        truncated = bool(enc["input_ids"].shape[1] >= self._max_len)
+        enc = {k: v.to(self.device) for k, v in enc.items() if k in ("input_ids", "attention_mask")}
+        with torch.no_grad():
+            logits = self._model(**enc).logits[0]
+            if self._multilabel:
+                sig = torch.sigmoid(logits)
+                score = float(sig[self._keep_idx].max().item()) if self._keep_idx else float(sig.max().item())
+            else:
+                score = float(torch.softmax(logits, dim=-1)[self._pos_index].item())
+        return score, truncated
+
+    def classify(self, text: str) -> dict:
+        if not text or not text.strip():
+            return {"label": "CLEAR", "flagged": False, "confidence": 0.0,
+                    "truncated": False, "model": self.model_name}
+        if not self.loaded:
+            self.load()
+        prob, truncated = self._probability(text)
+        flagged = prob >= MANIP_THRESHOLD
+        return {
+            "label": "MANIPULATION" if flagged else "CLEAR",
+            "flagged": flagged,
+            "confidence": round(prob, 4),
+            "truncated": truncated,
+            "model": self.model_name,
+        }
+
+    def _warmup(self) -> None:
+        start = time.perf_counter()
+        self._probability("This is a warmup inference for InfoShield.")
+        self.warmup_ms = round((time.perf_counter() - start) * 1000, 1)
+        log.info("Manipulation warmup on %s took ~%.1f ms", self.device, self.warmup_ms)
+
+
+_manip: Optional[ManipulationClassifier] = None
+
+
+def get_manip_classifier() -> ManipulationClassifier:
+    global _manip
+    if _manip is None:
+        _manip = ManipulationClassifier()
+    return _manip

backend/pipeline.py

@@ -0,0 +1,71 @@
+"""Per-post analysis pipeline -- the single source of truth for serving.
+
+For each post text:
+  1. HATE gate        -- local RoBERTa classifier  -> hate_confidence
+  2. MANIPULATION gate -- local propaganda classifier -> manipulation_confidence
+  3. If either fires -> LLM ANALYSIS (hate or manipulation prompt) explains WHY.
+  4. VERIFIER (2nd LLM) judges the analysis; if it's not relevant/accurate the
+     flag is overturned (treated as a false positive).
+
+Both gates are local (fast, free), so the LLM only runs on flagged posts. Results
+are cached by the caller (app.py) so the demo serves saved analysis instantly.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+
+from config import HIGH_CONFIDENCE
+
+log = logging.getLogger("infoshield.pipeline")
+
+_clf_lock = threading.Lock()  # serialize the (fast) local models across threads
+
+
+def analyze_post(text: str) -> tuple[dict, dict | None]:
+    """Return (classification, analysis-or-None) for one post text."""
+    from analyzer import analyze, verify
+    from classifier import get_classifier
+    from manip_classifier import get_manip_classifier
+
+    with _clf_lock:
+        hate = get_classifier().classify(text)
+        manip = get_manip_classifier().classify(text)
+
+    hate_conf = float(hate.get("confidence", 0.0))
+    manip_conf = float(manip.get("confidence", 0.0))
+    hate_flag = bool(hate.get("flagged"))
+    manip_flag = bool(manip.get("flagged"))
+    flagged = hate_flag or manip_flag
+
+    analysis = None
+    verification = None
+    kind = None
+    if flagged:
+        kind = "hate" if hate_flag else "manipulation"
+        analysis = analyze(text, kind)
+        verification = verify(text, analysis, kind)
+        # Overturn (false positive) if EITHER the verifier judged the analysis
+        # irrelevant, OR the rights-grounded analysis found no concrete technique/
+        # highlight (deterministic, speech-protective guard for both kinds).
+        empty = not analysis.get("techniques") and not analysis.get("highlights")
+        if not verification.get("relevant", True) or empty:
+            flagged = False
+            analysis = None
+            kind = None
+
+    trigger_conf = hate_conf if (kind == "hate") else manip_conf if (kind == "manipulation") else max(hate_conf, manip_conf)
+    classification = {
+        "label": "FLAGGED" if flagged else "CLEAR",
+        "flagged": flagged,
+        "kind": kind if flagged else None,
+        "confidence": round(trigger_conf, 4),
+        "hate_confidence": round(hate_conf, 4),
+        "manipulation_confidence": round(manip_conf, 4),
+        "high_confidence": flagged and trigger_conf >= HIGH_CONFIDENCE,
+        "truncated": bool(hate.get("truncated")),
+        "raw_scores": hate.get("raw_scores", {}),
+        "model": hate.get("model"),
+        "verification": verification,
+    }
+    return classification, analysis

backend/rebuild.py

@@ -0,0 +1,58 @@
+"""Shared cache-rebuild routine used by both build_cache.py and POST /rebuild-cache.
+
+Serving is real-time now (pipeline.py), so this is only for building an offline
+snapshot. It runs the same two-gate pipeline (local hate model + LLM manipulation
+detector/explainer) over every post and writes data/cache.json.
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Callable, Optional
+
+import config
+
+log = logging.getLogger("infoshield.rebuild")
+
+
+def rebuild_cache(cache, posts, on_post: Optional[Callable[[str, dict], None]] = None) -> dict:
+    """Reclassify + re-analyze all posts into `cache` (in-memory + on disk).
+
+    `on_post(post_id, classification)` is an optional progress callback.
+    """
+    from classifier import get_classifier
+    from llm import available as llm_available
+    from pipeline import analyze_post
+
+    clf = get_classifier()
+    clf.load()  # device select + warmup + label sanity check
+
+    flagged = 0
+    for post in posts:
+        classification, analysis = analyze_post(post["text"])
+        if classification["flagged"]:
+            flagged += 1
+        cache.set(post["id"], classification, analysis)
+        if on_post:
+            on_post(post["id"], classification)
+
+    cache.set_meta(
+        model=clf.model_name,
+        device=clf.device,
+        warmup_ms=clf.warmup_ms,
+        llm_provider=config.LLM_PROVIDER,
+        llm=llm_available(),
+        built_at=datetime.now(timezone.utc).isoformat(timespec="seconds"),
+    )
+    cache.save()
+
+    summary = {
+        "posts": len(posts),
+        "flagged": flagged,
+        "model": clf.model_name,
+        "device": clf.device,
+        "llm_provider": config.LLM_PROVIDER,
+        "llm": llm_available(),
+    }
+    log.info("Rebuild complete: %s", summary)
+    return summary

backend/requirements.txt

@@ -0,0 +1,20 @@
+# Core (required to serve the cache-first offline demo)
+flask>=3.0
+flask-cors>=4.0
+python-dotenv>=1.0
+
+# Local classifier (required to rebuild the cache / run /classify live)
+torch>=2.2
+transformers>=4.40
+# transformers needs one of safetensors/sentencepiece for these checkpoints
+safetensors>=0.4
+sentencepiece>=0.2
+
+# LLM manipulation detection + analysis. Groq is the default provider; Gemini
+# is the swap-in (set INFOSHIELD_LLM_PROVIDER=gemini).
+groq>=0.11
+google-genai>=0.3
+
+# Helpers
+huggingface_hub>=0.23
+emoji>=2.0  # BERTweet tokenizer (English fallback manipulation model) needs this

backend/scripts/build_cache.py

@@ -0,0 +1,41 @@
+"""Build the demo cache with the REAL pipeline: local classifier + Gemini.
+
+For every seed post: classify locally (content-only, author-agnostic), and if
+flagged, generate an educational analysis via Gemini (text only). Persists to
+data/cache.json. Same routine the backend exposes at POST /rebuild-cache.
+
+Requires torch + transformers installed; Gemini is optional (falls back to a
+local heuristic analysis if GEMINI_API_KEY is unset).
+
+Run:  python backend/scripts/build_cache.py
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from analyzer import available as gemini_available  # noqa: E402
+from cache import get_cache, load_posts  # noqa: E402
+from rebuild import rebuild_cache  # noqa: E402
+
+
+def main() -> None:
+    posts = load_posts()
+    cache = get_cache()
+    print(f"Gemini available: {gemini_available()}")
+    print(f"Building cache for {len(posts)} posts ...\n")
+
+    def progress(pid: str, classification: dict) -> None:
+        tag = "FLAG" if classification["flagged"] else "ok  "
+        print(f"  [{tag}] {pid:>3}  conf={classification['confidence']:.2f}")
+
+    summary = rebuild_cache(cache, posts, on_post=progress)
+    print(f"\nDone. {summary['flagged']} flagged / {summary['posts']} posts "
+          f"on {summary['device']}. Cache written.")
+
+
+if __name__ == "__main__":
+    main()

backend/scripts/download_models.py

@@ -0,0 +1,41 @@
+"""One-time, run-while-online model download.
+
+Pulls the primary (and fallback) hate-speech checkpoints into the local
+Hugging Face cache so the demo can later run with Wi-Fi off.
+
+Run:  python backend/scripts/download_models.py
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from config import FALLBACK_MODEL, PRIMARY_MODEL  # noqa: E402
+
+
+def fetch(name: str) -> bool:
+    from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+    print(f"\n=== Downloading {name} ===")
+    try:
+        AutoTokenizer.from_pretrained(name)
+        AutoModelForSequenceClassification.from_pretrained(name)
+        print(f"  OK: {name} cached.")
+        return True
+    except Exception as exc:  # noqa: BLE001
+        print(f"  FAILED: {name} -> {exc}")
+        return False
+
+
+def main() -> None:
+    ok_primary = fetch(PRIMARY_MODEL)
+    ok_fallback = fetch(FALLBACK_MODEL)
+    if not ok_primary and not ok_fallback:
+        raise SystemExit("Could not download any classifier model. Check your connection.")
+    print("\nDone. You can now build the cache (build_cache.py) and run offline.")
+
+
+if __name__ == "__main__":
+    main()

backend/scripts/evaluate.py

@@ -0,0 +1,159 @@
+"""Evaluate a gate and find its optimal threshold on a labeled CSV.
+
+Scores every row with one gate, then reports precision / recall / F1, ROC-AUC,
+PR-AUC, a threshold sweep, and three recommended operating points
+(max-F1, Youden's J, target-precision). See docs/EVALUATION.md for the method.
+
+CSV format: columns `text,label`  (label: 1 = hate/manipulation, 0 = not).
+
+Examples:
+    python backend/scripts/evaluate.py --task hate --data hate.csv --subset 0.1
+    python backend/scripts/evaluate.py --task manipulation --data persuasion.csv --subset 0.2
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import random
+import sys
+from pathlib import Path
+
+import numpy as np
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+
+def load_rows(path: str) -> list[tuple[str, int]]:
+    rows: list[tuple[str, int]] = []
+    with open(path, "r", encoding="utf-8", newline="") as f:
+        reader = csv.DictReader(f)
+        for r in reader:
+            text = (r.get("text") or "").strip()
+            raw = str(r.get("label") or "").strip()
+            if not text or raw == "":
+                continue
+            try:
+                label = int(float(raw))
+            except ValueError:
+                continue
+            rows.append((text, 1 if label >= 1 else 0))
+    return rows
+
+
+def stratified_subset(rows, fraction, seed):
+    if fraction >= 1.0:
+        return rows
+    rng = random.Random(seed)
+    pos = [r for r in rows if r[1] == 1]
+    neg = [r for r in rows if r[1] == 0]
+    rng.shuffle(pos)
+    rng.shuffle(neg)
+    keep = pos[: max(1, int(len(pos) * fraction))] + neg[: max(1, int(len(neg) * fraction))]
+    rng.shuffle(keep)
+    return keep
+
+
+def score_rows(rows, task):
+    scores = []
+    if task == "hate":
+        from classifier import get_classifier
+
+        clf = get_classifier()
+        clf.load()
+        for i, (text, _) in enumerate(rows, 1):
+            scores.append(float(clf.classify(text)["confidence"]))
+            if i % 25 == 0:
+                print(f"  scored {i}/{len(rows)}", file=sys.stderr)
+    else:  # manipulation (local propaganda model -- the gate score)
+        from manip_classifier import get_manip_classifier
+
+        clf = get_manip_classifier()
+        clf.load()
+        for i, (text, _) in enumerate(rows, 1):
+            scores.append(float(clf.classify(text)["confidence"]))
+            if i % 25 == 0:
+                print(f"  scored {i}/{len(rows)}", file=sys.stderr)
+    return np.array(scores), np.array([lbl for _, lbl in rows])
+
+
+def metrics_at(scores, labels, t):
+    pred = scores >= t
+    tp = int(np.sum(pred & (labels == 1)))
+    fp = int(np.sum(pred & (labels == 0)))
+    fn = int(np.sum(~pred & (labels == 1)))
+    tn = int(np.sum(~pred & (labels == 0)))
+    prec = tp / (tp + fp) if tp + fp else 0.0
+    rec = tp / (tp + fn) if tp + fn else 0.0
+    f1 = 2 * prec * rec / (prec + rec) if prec + rec else 0.0
+    tpr = rec
+    fpr = fp / (fp + tn) if fp + tn else 0.0
+    return {"t": t, "tp": tp, "fp": fp, "fn": fn, "tn": tn,
+            "precision": prec, "recall": rec, "f1": f1, "tpr": tpr, "fpr": fpr}
+
+
+def roc_auc(scores, labels):
+    pos = scores[labels == 1]
+    neg = scores[labels == 0]
+    if len(pos) == 0 or len(neg) == 0:
+        return float("nan")
+    # Mann-Whitney U (counts ties as 0.5).
+    gt = np.sum(pos[:, None] > neg[None, :])
+    eq = np.sum(pos[:, None] == neg[None, :])
+    return float((gt + 0.5 * eq) / (len(pos) * len(neg)))
+
+
+def pr_auc(scores, labels):
+    order = np.argsort(-scores)
+    y = labels[order]
+    tp = np.cumsum(y == 1)
+    fp = np.cumsum(y == 0)
+    npos = int(np.sum(labels == 1))
+    if npos == 0:
+        return float("nan")
+    precision = tp / np.maximum(tp + fp, 1)
+    recall = tp / npos
+    recall = np.concatenate([[0.0], recall])
+    precision = np.concatenate([[1.0], precision])
+    return float(np.sum((recall[1:] - recall[:-1]) * precision[1:]))  # average precision
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--task", choices=["hate", "manipulation"], required=True)
+    ap.add_argument("--data", required=True, help="CSV with columns: text,label")
+    ap.add_argument("--subset", type=float, default=1.0, help="stratified fraction, e.g. 0.1")
+    ap.add_argument("--seed", type=int, default=13)
+    ap.add_argument("--target-precision", type=float, default=0.85)
+    ap.add_argument("--steps", type=int, default=101)
+    args = ap.parse_args()
+
+    rows = stratified_subset(load_rows(args.data), args.subset, args.seed)
+    if not rows:
+        raise SystemExit("No usable rows (need columns text,label).")
+    print(f"\nTask: {args.task} | rows: {len(rows)} "
+          f"(pos={sum(l for _, l in rows)}, neg={sum(1 - l for _, l in rows)})")
+
+    scores, labels = score_rows(rows, args.task)
+    sweep = [metrics_at(scores, labels, t) for t in np.linspace(0, 1, args.steps)]
+
+    best_f1 = max(sweep, key=lambda m: m["f1"])
+    youden = max(sweep, key=lambda m: m["tpr"] - m["fpr"])
+    prec_ok = [m for m in sweep if m["precision"] >= args.target_precision and m["recall"] > 0]
+    target = min(prec_ok, key=lambda m: m["t"]) if prec_ok else best_f1
+
+    print(f"\nROC-AUC: {roc_auc(scores, labels):.3f}   PR-AUC (AP): {pr_auc(scores, labels):.3f}")
+    print("\nOperating points:")
+    print(f"  {'criterion':<22}{'thr':>6}{'P':>8}{'R':>8}{'F1':>8}")
+    for name, m in [("max-F1", best_f1), ("Youden's J", youden),
+                    (f"precision>={args.target_precision:.2f}", target)]:
+        print(f"  {name:<22}{m['t']:>6.2f}{m['precision']:>8.3f}{m['recall']:>8.3f}{m['f1']:>8.3f}")
+
+    r = target
+    print(f"\nRecommended threshold = {r['t']:.2f} (precision-first). Confusion @ thr:")
+    print(f"  TP={r['tp']}  FP={r['fp']}  FN={r['fn']}  TN={r['tn']}")
+    print("\nPaste the operating-points table into docs/EVALUATION.md > Key results.\n")
+
+
+if __name__ == "__main__":
+    main()

backend/scripts/finetune.py

@@ -0,0 +1,84 @@
+"""OPTIONAL fine-tuning scaffold. The demo does NOT depend on this.
+
+Fine-tunes the primary checkpoint on a small local CSV (columns: text,label
+where label is 0=not-hate, 1=hate). Useful if you want to adapt the classifier
+to your own examples. Produces a model directory you could point PRIMARY_MODEL at.
+
+Usage:
+    python backend/scripts/finetune.py --data my_data.csv --out backend/models/finetuned --epochs 2
+
+Requires: transformers[torch], datasets, accelerate.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from config import PRIMARY_MODEL  # noqa: E402
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--data", required=True, help="CSV with columns: text,label")
+    ap.add_argument("--out", default=str(ROOT / "models" / "finetuned"))
+    ap.add_argument("--epochs", type=float, default=2.0)
+    ap.add_argument("--lr", type=float, default=2e-5)
+    ap.add_argument("--batch", type=int, default=8)
+    args = ap.parse_args()
+
+    try:
+        import numpy as np
+        from datasets import load_dataset
+        from transformers import (
+            AutoModelForSequenceClassification,
+            AutoTokenizer,
+            DataCollatorWithPadding,
+            Trainer,
+            TrainingArguments,
+        )
+    except ImportError as exc:  # noqa: BLE001
+        raise SystemExit(
+            f"Missing dependency: {exc}. Install with: pip install datasets accelerate"
+        )
+
+    tok = AutoTokenizer.from_pretrained(PRIMARY_MODEL)
+    model = AutoModelForSequenceClassification.from_pretrained(PRIMARY_MODEL, num_labels=2)
+
+    ds = load_dataset("csv", data_files=args.data)["train"].train_test_split(test_size=0.2)
+    ds = ds.map(lambda b: tok(b["text"], truncation=True, max_length=256), batched=True)
+
+    def metrics(p):
+        preds = np.argmax(p.predictions, axis=-1)
+        return {"accuracy": float((preds == p.label_ids).mean())}
+
+    targs = TrainingArguments(
+        output_dir=args.out,
+        num_train_epochs=args.epochs,
+        learning_rate=args.lr,
+        per_device_train_batch_size=args.batch,
+        per_device_eval_batch_size=args.batch,
+        eval_strategy="epoch",
+        save_strategy="epoch",
+        logging_steps=10,
+    )
+    trainer = Trainer(
+        model=model,
+        args=targs,
+        train_dataset=ds["train"],
+        eval_dataset=ds["test"],
+        tokenizer=tok,
+        data_collator=DataCollatorWithPadding(tok),
+        compute_metrics=metrics,
+    )
+    trainer.train()
+    trainer.save_model(args.out)
+    tok.save_pretrained(args.out)
+    print(f"\nSaved fine-tuned model to {args.out}")
+    print("To use it, set PRIMARY_MODEL in backend/config.py to that path.")
+
+
+if __name__ == "__main__":
+    main()

backend/scripts/seed_demo.py

@@ -0,0 +1,193 @@
+"""Author the demo feed (posts.json) plus a neutral starter cache (cache.json).
+
+This writes ONLY post content/metadata. Classification + analysis come from the
+real pipeline via `build_cache.py` (or POST /rebuild-cache). The starter cache
+marks every post unflagged so the app serves a valid feed before the first
+rebuild; running the real pipeline then fills in flags + analyses.
+
+All harmful examples are synthetic, mild-to-moderate, and reference only
+unnamed/fictional groups (never real ethnic, religious, or national groups).
+
+Run:  python backend/scripts/seed_demo.py
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+DATA = ROOT / "data"
+
+USERS = {
+    "maya":    {"name": "Maya Chen",        "handle": "maya_codes",      "initial": "M", "color": "#2563EB", "verified": False},
+    "dave":    {"name": "Dave R.",          "handle": "grillmaster_dave","initial": "D", "color": "#D97706", "verified": False},
+    "priya":   {"name": "Priya K.",         "handle": "aerialnomad",     "initial": "P", "color": "#0D9488", "verified": True},
+    "lena":    {"name": "Lena Ortiz",       "handle": "lena_writes",     "initial": "L", "color": "#DB2777", "verified": False},
+    "sam":     {"name": "Sam · RN",         "handle": "nightshift_sam",  "initial": "S", "color": "#7C3AED", "verified": False},
+    "tom":     {"name": "Tom B.",           "handle": "tom_b",           "initial": "T", "color": "#0F172A", "verified": False},
+    "anna":    {"name": "Anna Whitfield",   "handle": "historybuff_anna","initial": "A", "color": "#9333EA", "verified": True},
+    "truth":   {"name": "Truth Hour",       "handle": "TheRealTruthHour","initial": "T", "color": "#DC2626", "verified": False},
+    "wake":    {"name": "Open Your Eyes",   "handle": "wakeup_sheeple",  "initial": "O", "color": "#7C2D12", "verified": False},
+    "brad":    {"name": "Brad // crypto",   "handle": "cryptobrad",      "initial": "B", "color": "#F59E0B", "verified": False},
+    "radio":   {"name": "Real Talk Radio",  "handle": "realtalkradio",   "initial": "R", "color": "#B91C1C", "verified": False},
+    "parent":  {"name": "Concerned Parent", "handle": "concerned_parent_99","initial": "C","color": "#92400E","verified": False},
+    "doom":    {"name": "doomscroller",     "handle": "doomscroller",    "initial": "d", "color": "#475569", "verified": False},
+    "quiet":   {"name": "just asking",      "handle": "quiet_observer",  "initial": "j", "color": "#64748B", "verified": False},
+    "mike":    {"name": "Mike",             "handle": "patriot_mike49",  "initial": "M", "color": "#991B1B", "verified": False},
+    "zephyr":  {"name": "ZephyrX",          "handle": "ZephyrX_",        "initial": "Z", "color": "#1F2937", "verified": False},
+    "border":  {"name": "Borderwatch",      "handle": "borderwatch_now", "initial": "B", "color": "#7F1D1D", "verified": False},
+    "oldtown": {"name": "Old Town Voice",   "handle": "oldtownvoice",    "initial": "O", "color": "#78350F", "verified": False},
+    "jane":    {"name": "Jane",             "handle": "realtalk_jane",   "initial": "J", "color": "#a16207", "verified": False},
+}
+
+POSTS = []
+
+
+def add(pid, user, time, text, *, media=None, replies=0, reposts=0, likes=0):
+    POSTS.append({
+        "id": pid,
+        "user": USERS[user],
+        "time": time,
+        "text": text,
+        "media": media,
+        "engagement": {"replies": replies, "reposts": reposts, "likes": likes},
+    })
+
+
+# ---- Normal posts --------------------------------------------------------
+add("p1", "maya", "12m",
+    "spent three hours debugging today only to realize i'd been editing the wrong file the entire time. "
+    "anyway. how is everyone's monday going",
+    replies=156, reposts=89, likes=1243)
+
+add("p2", "dave", "34m",
+    "Unpopular opinion: pineapple absolutely belongs on pizza and I'm tired of pretending it doesn't \U0001F34D",
+    replies=890, reposts=320, likes=4500)
+
+add("p3", "priya", "1h",
+    "Sunrise over the valley in Patagonia right now. Some places just don't feel real until you're standing in them. \U0001F3D4️",
+    media={"type": "gradient"}, replies=230, reposts=1200, likes=8900)
+
+add("p4", "lena", "2h",
+    "finished the first draft of my novel at 2am and immediately started doubting every single word of it. "
+    "writing is just professionally arguing with yourself.",
+    replies=98, reposts=340, likes=2100)
+
+add("p5", "sam", "3h",
+    "12 hour shift done. feet wrecked, heart full. a patient's family brought the whole unit donuts today "
+    "and i nearly cried in the break room. it's the small stuff.",
+    replies=145, reposts=210, likes=3400)
+
+add("p6", "tom", "4h", "is it coffee o'clock yet", replies=34, reposts=12, likes=540)
+
+add("p7", "anna", "5h",
+    "people ask why i love history and honestly it's because nothing is ever as simple as the textbook makes it "
+    "sound. every 'obvious' decision was made by a real person who couldn't see the ending, who was scared and "
+    "tired and working with bad information. we read the past like the outcome was inevitable, but the people "
+    "living it had no idea which way it would go. that's the part that stays with me, not the dates or the "
+    "battles but the uncertainty. it makes me a lot gentler about the present, knowing future generations will "
+    "flatten us into a tidy paragraph too.",
+    replies=210, reposts=980, likes=5600)
+
+# ---- Manipulation posts --------------------------------------------------
+add("p8", "truth", "26m",
+    "They don't want you to know this, but the new digital ID rolling out next month means they can switch off "
+    "your bank account with a single click. This is NOT a conspiracy. Screenshot this before it gets taken down. ⏰",
+    replies=3400, reposts=8900, likes=12000)
+
+add("p9", "wake", "1h",
+    "Wake up. Everything you were taught was designed to keep you obedient and quiet. The people at the top are "
+    "laughing at how easy it was. Stop trusting them and start trusting your gut.",
+    replies=890, reposts=4200, likes=6700)
+
+add("p10", "brad", "1h",
+    "\U0001F6A8 ONLY 100 spots left. This is your LAST chance to get in before the price 10x's. The people who "
+    "hesitate will be kicking themselves in 6 months. DM me NOW or stay broke. \U0001F449 https://t.co/x9f2aQ",
+    replies=1200, reposts=450, likes=890)
+
+add("p11", "radio", "2h",
+    "Notice how every time regular people start asking real questions, there's suddenly a brand new crisis to "
+    "distract everyone? That's not a coincidence. They've been running this exact playbook for decades.",
+    replies=780, reposts=5600, likes=9800)
+
+add("p12", "parent", "3h",
+    "If you don't share this, don't call yourself a real parent. They are putting things into the curriculum "
+    "that will destroy your child's mind by next year. Act before it's too late.",
+    replies=2300, reposts=6700, likes=4500)
+
+add("p13", "doom", "3h",
+    "oh good, another 'once in a lifetime' crisis this week. truly we are so blessed to live through the single "
+    "most important moment in human history every monday \U0001F644",
+    replies=120, reposts=670, likes=3200)
+
+# ---- Borderline ----------------------------------------------------------
+add("p14", "quiet", "4h",
+    "i'm not saying anything is definitely wrong with the new policy... but doesn't it feel a little convenient? "
+    "a lot of people are quietly starting to wonder, and maybe that's worth paying attention to.",
+    replies=200, reposts=340, likes=1200)
+
+# ---- Hate speech (synthetic, unnamed groups) -----------------------------
+add("p15", "mike", "5h",
+    "These people pour into our town, don't bother learning how we live, and expect us to bend over backwards "
+    "for them. They breed faster than we can keep up and soon there'll be nothing left of who we are. Enough.",
+    replies=1200, reposts=3400, likes=5600)
+
+add("p16", "zephyr", "6h",
+    "Every one of them is the same — vermin who swarm in and bleed this place dry. They don't belong here and "
+    "they should be driven out before there's nothing left.",
+    replies=890, reposts=1100, likes=2300)
+
+add("p17", "border", "7h",
+    "They're animals, plain and simple, and you can't civilize an animal. People like that should be removed "
+    "from our streets before they ruin everything.",
+    replies=1500, reposts=2100, likes=3400)
+
+add("p18", "oldtown", "9h",
+    "They've infested every neighborhood they've touched and turned it into a dump. Pack them up and send them "
+    "back where they came from before there's nothing left of this place.",
+    replies=1900, reposts=2800, likes=4500)
+
+add("p19", "jane", "11h",
+    "funny how a certain kind of people always seem to end up at the center of every single problem in this city. "
+    "at some point you stop calling it a coincidence.",
+    replies=600, reposts=900, likes=1800)
+
+
+def write_starter_cache() -> None:
+    """Neutral cache so the app serves a valid feed before the first rebuild."""
+    posts = {
+        p["id"]: {
+            "classification": {
+                "label": "NOT_HATE", "flagged": False, "confidence": 0.0,
+                "high_confidence": False, "truncated": False, "raw_scores": {},
+                "model": "starter (unanalyzed)",
+            },
+            "analysis": None,
+        }
+        for p in POSTS
+    }
+    payload = {
+        "meta": {
+            "built_at": None,
+            "model": "starter (unanalyzed)",
+            "device": "n/a",
+            "note": "Neutral starter cache. Run build_cache.py or POST /rebuild-cache for real analysis.",
+        },
+        "posts": posts,
+    }
+    with open(DATA / "cache.json", "w", encoding="utf-8") as f:
+        json.dump(payload, f, ensure_ascii=False, indent=2)
+
+
+def main() -> None:
+    DATA.mkdir(parents=True, exist_ok=True)
+    with open(DATA / "posts.json", "w", encoding="utf-8") as f:
+        json.dump(POSTS, f, ensure_ascii=False, indent=2)
+    if not (DATA / "cache.json").exists():
+        write_starter_cache()
+    print(f"Wrote {len(POSTS)} posts -> posts.json")
+    print("Run build_cache.py (or POST /rebuild-cache) to generate real classification + analysis.")
+
+
+if __name__ == "__main__":
+    main()