Upload 33 files

.dockerignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+.git/
+.gitignore
+data/
+.venv/
+venv/
+*.db
+*.db-wal
+*.db-shm
+.DS_Store

.gitattributes

@@ -1,35 +1,35 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz 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
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz 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

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+data/
+.venv/
+venv/

Dockerfile

@@ -1,27 +1,48 @@
-# Use the official Python 3.9 image
-FROM python:3.9
+# Hugging Face Space (SDK: docker) -- listens on 7860.
+#
+# NOTE: python:3.9 from the stock HF template does NOT work for this app.
+# FastAPI/Pydantic evaluate annotations like `str | None` at runtime, which
+# requires Python 3.10+. 3.11 matches the development environment.
+FROM python:3.11-slim
 
-# Set the working directory to /code
 WORKDIR /code
 
-# Copy the current directory contents into the container at /code
-COPY ./requirements.txt /code/requirements.txt
+# Install CPU-only torch first -- the default PyPI wheel pulls ~2.5GB of CUDA
+# libraries that a CPU Space can never use.
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
 
-# Install requirements.txt 
+COPY ./requirements.txt /code/requirements.txt
 RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
 
 # Set up a new user named "user" with user ID 1000
 RUN useradd -m -u 1000 user
-# Switch to the "user" user
 USER user
-# Set home to the user's home directory
 ENV HOME=/home/user \
-	PATH=/home/user/.local/bin:$PATH
+    PATH=/home/user/.local/bin:$PATH
+
+# Model + SQLite both need writable paths. On a Space, $HOME is the only one.
+ENV HF_HOME=/home/user/.cache/huggingface \
+    DATA_DIR=/home/user/app/data \
+    MODEL_NAME=typeform/distilbert-base-uncased-mnli \
+    PRELOAD_MODEL=1 \
+    PYTHONUNBUFFERED=1
 
-# Set the working directory to the user's home directory
 WORKDIR $HOME/app
 
-# Copy the current directory contents into the container at $HOME/app setting the owner to the user
+# Bake the model into the image so the Space answers the first request fast
+# instead of downloading ~250MB on cold start.
+RUN python -c "\
+from transformers import pipeline; \
+import os; \
+pipeline('zero-shot-classification', model=os.environ['MODEL_NAME'], device=-1)" \
+    && echo "model cached"
+
 COPY --chown=user . $HOME/app
 
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]
+RUN mkdir -p $HOME/app/data
+
+EXPOSE 7860
+
+# app.main:app -- the FastAPI instance lives in the `app` package, not main.py
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,296 @@
----
-title: curfox_kpi_api
-emoji: 🐠
-colorFrom: red
-colorTo: red
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: Complaint Classifier
+emoji: 📝
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+short_description: Multilingual complaint classifier with runtime labels
+---
+
+# Complaint Classifier
+
+A FastAPI app with a web UI that takes a public complaint **in any language**,
+detects the language, translates it to English with Google Translate, and
+classifies it into a problem type (Water Supply, Electricity, Road, Waste, …)
+using a **small pretrained zero-shot model**.
+
+The labels are **not baked into the model**. You edit them in the UI and the very
+next classification uses them — no retraining, no restart.
+
+---
+
+## Why zero-shot
+
+A normal fine-tuned text classifier has its labels frozen at training time; adding
+"Street Lighting" would mean collecting data and retraining.
+
+This app uses a **zero-shot NLI classifier** instead. The candidate labels are an
+*input* to every inference call. The model checks "does this complaint entail the
+hypothesis *This complaint is about broken street lights*?" for each label and
+ranks them. That is what makes runtime-editable labels possible.
+
+Default model: [`typeform/distilbert-base-uncased-mnli`](https://huggingface.co/typeform/distilbert-base-uncased-mnli)
+— ~250 MB, CPU-friendly, ~100–400 ms per complaint on a laptop.
+
+---
+
+## Pipeline
+
+```
+complaint (any language)
+        │
+        ▼
+  langdetect            → ISO code + confidence (offline, instant)
+        │
+        ▼
+  deep-translator       → Google Translate → English
+  (skipped when already confidently English)
+        │
+        ▼
+  zero-shot NLI model   → score every ACTIVE label from the database
+        │
+        ▼
+  top label + confidence + full score breakdown  → saved to SQLite
+```
+
+---
+
+## Install & run
+
+```bash
+pip install -r requirements.txt
+
+# Windows
+run.bat
+# macOS / Linux
+./run.sh
+# or directly
+python -m uvicorn app.main:app --reload
+```
+
+Then open **http://127.0.0.1:8000**.
+
+The first start downloads the model (~250 MB) in a background thread, so the UI is
+usable immediately — the dot in the top-right shows `loading model…` → `model ready`.
+
+---
+
+## Pages
+
+| Page | What it does |
+| --- | --- |
+| `/` | Submit a complaint, see the predicted category, detected language, English translation and a score bar for **every** label. |
+| `/labels` | Add / rename / describe / activate / delete labels. Changes are live instantly. |
+| `/history` | Every classified complaint with per-category counts, plus a text filter. |
+| `/docs` | Auto-generated OpenAPI docs (Swagger UI). |
+
+---
+
+## API
+
+### `POST /api/classify`
+
+```json
+{
+  "text": "අපේ ගමේ දින තුනක් තිස්සේ වතුර නැහැ",
+  "translate": true,
+  "multi_label": false,
+  "threshold": 0.35,
+  "save": true,
+  "labels": null
+}
+```
+
+Response:
+
+```json
+{
+  "id": 12,
+  "predicted_label": "Water Supply",
+  "confidence": 0.8421,
+  "confident": true,
+  "threshold": 0.35,
+  "scores": [
+    {"label": "Water Supply", "score": 0.8421},
+    {"label": "Public Health", "score": 0.0612}
+  ],
+  "translation": {
+    "source_lang": "si",
+    "source_lang_name": "Sinhala",
+    "detection_confidence": 0.9999,
+    "was_translated": true,
+    "original_text": "අපේ ගමේ දින තුනක් තිස්සේ වතුර නැහැ",
+    "translated_text": "There is no water in our village for three days",
+    "note": ""
+  },
+  "engine": "zero-shot:typeform/distilbert-base-uncased-mnli",
+  "multi_label": false,
+  "took_ms": 187
+}
+```
+
+Pass `"labels": ["Water", "Electricity"]` to classify against an ad-hoc set for one
+request only, without touching the saved labels.
+
+### Labels
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/api/labels?active_only=true` | List labels |
+| `POST` | `/api/labels` | Add `{name, description, active}` |
+| `PATCH` | `/api/labels/{id}` | Update any subset of fields |
+| `DELETE` | `/api/labels/{id}` | Remove a label |
+
+### Other
+
+`GET /api/history` · `GET /api/stats` · `DELETE /api/history` ·
+`GET /api/health` · `POST /api/model/reload`
+
+---
+
+## Configuration
+
+All optional, via environment variables:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `MODEL_NAME` | `typeform/distilbert-base-uncased-mnli` | Any HF zero-shot/NLI model |
+| `HYPOTHESIS_TEMPLATE` | `This complaint is about {}.` | Steers the NLI model |
+| `LEXICAL_WEIGHT` | `0.6` | Weight of the description keyword prior (0 = pure model) |
+| `CONFIDENCE_THRESHOLD` | `0.35` | Below this the result is flagged low-confidence |
+| `PRELOAD_MODEL` | `1` | Load at startup instead of first request |
+| `TRANSLATE_ENABLED` | `1` | Set `0` to skip Google Translate entirely |
+| `DATA_DIR` | `./data` | Where `complaints.db` lives |
+| `DISABLE_XET` | `0` | Set `1` if model downloads hang at 0 bytes (see below) |
+| `MODEL_OFFLINE` | `0` | Set `1` to use only the local HF cache, never the network |
+| `MODEL_DOWNLOAD_TIMEOUT` | `30` | Seconds a download chunk may stall before failing |
+
+Alternatives for `MODEL_NAME` — **benchmark before switching**:
+
+- `MoritzLaurer/deberta-v3-xsmall-zeroshot-v1.1-all-33` (~146 MB). Far more
+  confident (0.80 vs 0.24 on the same complaint) but measured at **~41 s per
+  inference** on the development CPU against distilbert's **~0.4 s**. That is
+  100× slower and unusable for real-time intake, so it is not the default
+  despite the better scores. Needs `sentencepiece` + `protobuf`.
+- `valhalla/distilbart-mnli-12-1` (~890 MB)
+- `facebook/bart-large-mnli` (~1.6 GB, the reference model)
+
+Run `python scripts/bench.py <model>` to check both accuracy and latency on your
+own hardware — the latency gap above may be specific to this CPU/torch build.
+
+---
+
+## Getting good accuracy
+
+**Keep label names short and plain; put the vocabulary in the description.**
+
+The label *name* is the model's hypothesis ("This complaint is about **Electricity**.")
+— NLI models want a clean noun phrase there, so `Electricity` beats
+`Electricity / power / outages etc`.
+
+The *description* is a separate keyword prior blended into the score
+(`LEXICAL_WEIGHT`, default `0.6`). This is where the domain vocabulary belongs:
+
+> `Electricity` → *"power cut, outage, voltage fluctuation, broken street light,
+> damaged electric pole or hanging wire"*
+
+This split matters. Measured on the bundled 18-case benchmark:
+
+| candidates | accuracy |
+| --- | --- |
+| descriptions as the hypothesis (the obvious-looking choice) | 0/18 |
+| label names, no blend (`LEXICAL_WEIGHT=0`) | 10/18 |
+| label names + description prior at `0.6` | **16/18 (89%)** |
+
+Reproduce with `python scripts/bench.py`.
+
+Other levers: raise `CONFIDENCE_THRESHOLD` if you would rather route ambiguous
+complaints to a human than mislabel them; keep an `Other` label active so
+off-topic complaints have somewhere to land; use `multi_label` when a single
+complaint can legitimately belong to two categories.
+
+---
+
+## Troubleshooting
+
+**The model download hangs at 0 bytes.** Some corporate and ISP networks block
+Hugging Face's Xet storage backend while ordinary HTTPS to `huggingface.co` still
+works, so the download never starts and never errors. Force the classic CDN path:
+
+```bash
+# Windows
+set DISABLE_XET=1
+# macOS / Linux
+export DISABLE_XET=1
+```
+
+This was hit on the development machine — 0 bytes after 15 minutes with Xet, normal
+throughput immediately after disabling it.
+
+**The status dot says `keyword fallback`.** The model failed to load. `GET /api/health`
+returns the full error under `model.error`. The app keeps working on the keyword
+scorer until you fix it and call `POST /api/model/reload`.
+
+---
+
+## Behaviour when things are offline
+
+- **No network for Google Translate** → the complaint is classified in its original
+  language and the response carries a `note` explaining why. Nothing is lost.
+- **Model can't be downloaded** → a keyword-overlap fallback scorer keeps the app
+  working, and `engine` reports `keyword-fallback` so you always know which path
+  produced a result.
+
+---
+
+## Deploying to Hugging Face Spaces
+
+The repo ships a `Dockerfile` for a Space with `sdk: docker` (set in the README
+frontmatter above, together with `app_port: 7860`).
+
+```bash
+git clone https://huggingface.co/spaces/Arafath10/textclsy
+cd textclsy
+# copy this project in, then
+git add -A && git commit -m "Complaint classifier" && git push
+```
+
+Pushing needs an HF token with **write** access:
+
+```bash
+huggingface-cli login          # or:
+git remote set-url origin https://<user>:<hf_token>@huggingface.co/spaces/Arafath10/textclsy
+```
+
+Three things differ from the stock HF Docker template, all deliberate:
+
+1. **`python:3.11-slim`, not `python:3.9`.** FastAPI and Pydantic evaluate
+   annotations such as `str | None` at runtime; that syntax is a `TypeError` on 3.9.
+2. **CPU-only torch.** The default PyPI wheel drags in ~2.5 GB of CUDA libraries a
+   CPU Space can never use, so torch is installed from the PyTorch CPU index first.
+3. **The model is baked into the image** at build time, so a cold start serves the
+   first request immediately instead of downloading ~250 MB.
+
+Note that a Space's filesystem is ephemeral — `data/complaints.db` resets when the
+Space restarts or rebuilds. Attach a persistent volume, or point `DATA_DIR` at one,
+if the complaint history has to survive.
+
+---
+
+## Layout
+
+```
+app/
+  main.py         FastAPI routes (pages + JSON API)
+  classifier.py   zero-shot pipeline, keyword fallback, model state
+  translator.py   langdetect + Google Translate, degrades gracefully
+  store.py        SQLite: labels + complaint history
+  config.py       env-var configuration and seed labels
+  schemas.py      Pydantic request/response models
+  templates/      Jinja2 pages
+  static/         CSS + vanilla JS (no build step)
+data/
+  complaints.db   created on first run
+```

app/classifier.py

@@ -0,0 +1,251 @@
+"""Zero-shot complaint classifier.
+
+Zero-shot (NLI) is what makes runtime labels possible: the candidate labels are
+an *input* to every inference call, so adding "Street Lighting" in the UI takes
+effect on the very next complaint -- no retraining, no restart.
+
+If transformers/torch are unavailable or the model cannot be downloaded, a
+keyword-overlap fallback keeps the app usable; every response reports which
+engine produced it.
+"""
+from __future__ import annotations
+
+import logging
+import math
+import re
+import threading
+import time
+from typing import Any
+
+from .config import (
+    CONFIDENCE_THRESHOLD,
+    HYPOTHESIS_TEMPLATE,
+    LEXICAL_WEIGHT,
+    MODEL_NAME,
+)
+
+log = logging.getLogger("classifier")
+
+# Two locks on purpose: _load_lock is held for the whole (possibly very slow)
+# model download, so inference must not wait on it -- a reload would otherwise
+# stall every live request. _infer_lock only guards the pipeline call itself.
+_load_lock = threading.Lock()
+_infer_lock = threading.Lock()
+_pipe: Any = None
+_state: dict[str, Any] = {
+    "status": "not_loaded",   # not_loaded | loading | ready | failed
+    "engine": "none",
+    "model": MODEL_NAME,
+    "error": "",
+    "load_seconds": 0.0,
+}
+
+# Candidate phrases longer than this are trimmed -- NLI hypotheses work best short.
+MAX_CANDIDATE_WORDS = 16
+_WORD_RE = re.compile(r"[a-z0-9']+")
+_STOPWORDS = {
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being", "to", "of",
+    "in", "on", "at", "for", "with", "and", "or", "not", "no", "my", "our", "i", "we",
+    "it", "this", "that", "there", "here", "from", "by", "as", "has", "have", "had",
+    "do", "does", "did", "but", "so", "very", "please", "sir", "madam", "any", "some",
+}
+
+
+def state() -> dict[str, Any]:
+    return dict(_state)
+
+
+def is_ready() -> bool:
+    return _state["status"] == "ready"
+
+
+def load_model(force: bool = False) -> dict[str, Any]:
+    """Load the zero-shot pipeline. Safe to call repeatedly and concurrently."""
+    global _pipe
+    with _load_lock:
+        if _pipe is not None and not force:
+            return state()
+        _state.update(status="loading", error="")
+        started = time.perf_counter()
+        try:
+            from transformers import pipeline as hf_pipeline
+
+            try:
+                import torch
+
+                torch.set_num_threads(max(1, (torch.get_num_threads() or 2) - 1))
+            except Exception:
+                pass
+
+            _pipe = hf_pipeline(
+                "zero-shot-classification",
+                model=MODEL_NAME,
+                device=-1,  # CPU; small model, fine for real-time single requests
+            )
+            _state.update(
+                status="ready",
+                engine=f"zero-shot:{MODEL_NAME}",
+                load_seconds=round(time.perf_counter() - started, 2),
+                error="",
+            )
+            log.info("Loaded %s in %.2fs", MODEL_NAME, _state["load_seconds"])
+        except Exception as exc:
+            _pipe = None
+            _state.update(
+                status="failed",
+                engine="keyword-fallback",
+                error=f"{type(exc).__name__}: {exc}",
+                load_seconds=round(time.perf_counter() - started, 2),
+            )
+            log.warning("Model load failed (%s); using keyword fallback.", exc)
+        return state()
+
+
+def _candidate_for(label: dict[str, Any]) -> str:
+    """The NLI hypothesis phrase for a label -- the label NAME, kept short.
+
+    Feeding the description in here instead was measurably worse: on a 6-case
+    benchmark, descriptions as candidates scored 0/6 against 3/6 for bare names.
+    An NLI hypothesis wants a clean noun phrase ("Water Supply"), not a
+    comma-separated keyword dump. Descriptions are still used -- as a lexical
+    prior blended into the scores, see _blend().
+    """
+    name = (label.get("name") or "").strip()
+    words = name.split()
+    if len(words) > MAX_CANDIDATE_WORDS:
+        name = " ".join(words[:MAX_CANDIDATE_WORDS])
+    return name
+
+
+def _blend(
+    model_scores: list[tuple[str, float]],
+    text: str,
+    labels: list[dict[str, Any]],
+    weight: float,
+    multi_label: bool = False,
+) -> list[tuple[str, float]]:
+    """Mix the model scores with a keyword prior built from label descriptions.
+
+    The descriptions carry real domain signal ("burst pipe", "lamp post") that a
+    small NLI model does not get from the label name alone. Blending keeps the
+    model in charge while letting those hints break ties.
+
+    Skipped entirely in multi-label mode: there each score is an INDEPENDENT
+    probability, while the lexical prior is a distribution summing to 1 across
+    labels. Mixing the two would systematically depress every score and the
+    renormalisation below would destroy the independence the caller asked for.
+    """
+    if weight <= 0 or multi_label:
+        return model_scores
+
+    lexical = dict(_keyword_scores(text, labels))
+    # A flat prior means no keyword matched -- blending it would only dilute.
+    if max(lexical.values(), default=0.0) - min(lexical.values(), default=0.0) < 1e-6:
+        return model_scores
+
+    blended = [
+        (name, (1.0 - weight) * score + weight * lexical.get(name, 0.0))
+        for name, score in model_scores
+    ]
+    total = sum(s for _, s in blended)
+    if total > 0:
+        blended = [(n, s / total) for n, s in blended]
+    return blended
+
+
+def _tokens(text: str) -> set[str]:
+    return {w for w in _WORD_RE.findall(text.lower()) if w not in _STOPWORDS and len(w) > 2}
+
+
+def _keyword_scores(text: str, labels: list[dict[str, Any]]) -> list[tuple[str, float]]:
+    """Fallback scorer: overlap between complaint tokens and label tokens."""
+    text_tokens = _tokens(text)
+    raw = []
+    for label in labels:
+        label_tokens = _tokens(f"{label.get('name','')} {label.get('description','')}")
+        if not label_tokens:
+            raw.append(0.0)
+            continue
+        hits = sum(1 for t in label_tokens if t in text_tokens)
+        # partial credit for stem-ish prefix matches ("leaking" vs "leak")
+        near = sum(
+            1 for t in label_tokens
+            if t not in text_tokens and any(t.startswith(u[:4]) or u.startswith(t[:4])
+                                            for u in text_tokens if len(u) > 3)
+        )
+        raw.append(hits + 0.35 * near)
+
+    if max(raw, default=0.0) <= 0:
+        even = 1.0 / len(labels) if labels else 0.0
+        return [(l["name"], even) for l in labels]
+
+    exps = [math.exp(s) for s in raw]
+    total = sum(exps)
+    return sorted(
+        ((l["name"], e / total) for l, e in zip(labels, exps)),
+        key=lambda p: p[1],
+        reverse=True,
+    )
+
+
+def classify(
+    text: str,
+    labels: list[dict[str, Any]],
+    multi_label: bool = False,
+    threshold: float | None = None,
+) -> dict[str, Any]:
+    """Classify `text` against `labels` (list of {name, description}).
+
+    Returns predicted label, per-label scores, engine used and latency.
+    """
+    threshold = CONFIDENCE_THRESHOLD if threshold is None else threshold
+    text = (text or "").strip()
+    started = time.perf_counter()
+
+    if not text:
+        raise ValueError("Complaint text is empty.")
+    if not labels:
+        raise ValueError("No active labels configured. Add at least one label first.")
+
+    if _pipe is None and _state["status"] == "not_loaded":
+        load_model()
+
+    pipe = _pipe  # local ref: a concurrent reload must not swap this mid-call
+    if pipe is not None:
+        # Candidates are label names. Stored names are UNIQUE, but an ad-hoc
+        # label list from the API may repeat, and the pipeline dislikes dupes.
+        candidates = list(dict.fromkeys(_candidate_for(l) for l in labels if _candidate_for(l)))
+        try:
+            with _infer_lock:
+                out = pipe(
+                    text,
+                    candidate_labels=candidates,
+                    hypothesis_template=HYPOTHESIS_TEMPLATE,
+                    multi_label=multi_label,
+                )
+            scored = [(lbl, float(score))
+                      for lbl, score in zip(out["labels"], out["scores"])]
+            scored = _blend(scored, text, labels, LEXICAL_WEIGHT, multi_label)
+            engine = _state["engine"]
+        except Exception as exc:
+            log.warning("Inference failed (%s); falling back to keywords.", exc)
+            scored = _keyword_scores(text, labels)
+            engine = "keyword-fallback (inference error)"
+    else:
+        scored = _keyword_scores(text, labels)
+        engine = "keyword-fallback"
+
+    scored.sort(key=lambda p: p[1], reverse=True)
+    top_label, top_score = scored[0]
+    took_ms = int((time.perf_counter() - started) * 1000)
+
+    return {
+        "predicted_label": top_label,
+        "confidence": round(top_score, 4),
+        "confident": top_score >= threshold,
+        "threshold": threshold,
+        "scores": [{"label": n, "score": round(s, 4)} for n, s in scored],
+        "engine": engine,
+        "multi_label": multi_label,
+        "took_ms": took_ms,
+    }

app/config.py

@@ -0,0 +1,67 @@
+"""Runtime configuration. Override any value with an environment variable."""
+import os
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+DATA_DIR = Path(os.getenv("DATA_DIR", BASE_DIR / "data"))
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+DB_PATH = DATA_DIR / "complaints.db"
+
+# Small NLI model used for zero-shot classification (~250MB).
+# Alternatives:
+#   valhalla/distilbart-mnli-12-1                (~890MB, more accurate)
+#   MoritzLaurer/deberta-v3-xsmall-zeroshot-v1.1-all-33  (~146MB, far more
+#     confident -- 0.80 vs 0.24 on a sample complaint -- but measured at
+#     ~41s per inference on this CPU against distilbert's ~0.4s. Unusable for
+#     real-time intake here; benchmark it yourself before switching.)
+MODEL_NAME = os.getenv("MODEL_NAME", "typeform/distilbert-base-uncased-mnli")
+
+# Seconds a single chunk of the model download may stall before giving up.
+# Without this a flaky/blocked network leaves the loader thread hanging forever
+# instead of cleanly falling back. Applied to huggingface_hub at import time.
+os.environ.setdefault("HF_HUB_DOWNLOAD_TIMEOUT", os.getenv("MODEL_DOWNLOAD_TIMEOUT", "30"))
+os.environ.setdefault("HF_HUB_ETAG_TIMEOUT", "15")
+
+# Some corporate/ISP networks block Hugging Face's Xet storage backend, which
+# makes model downloads hang at 0 bytes forever while ordinary HTTPS to
+# huggingface.co works fine. DISABLE_XET=1 forces the classic CDN path.
+if os.getenv("DISABLE_XET", "0") not in ("0", "false", "False"):
+    os.environ["HF_HUB_DISABLE_XET"] = "1"
+
+# Set MODEL_OFFLINE=1 to never hit the network (uses the local HF cache only).
+if os.getenv("MODEL_OFFLINE", "0") not in ("0", "false", "False"):
+    os.environ["HF_HUB_OFFLINE"] = "1"
+
+# "This complaint is about {}." -- steers the NLI model towards the domain.
+HYPOTHESIS_TEMPLATE = os.getenv(
+    "HYPOTHESIS_TEMPLATE", "This complaint is about {}."
+)
+
+# Below this top score the complaint is reported as "unclassified" instead of
+# being forced into the closest label.
+CONFIDENCE_THRESHOLD = float(os.getenv("CONFIDENCE_THRESHOLD", "0.35"))
+
+# How much the keyword prior built from label descriptions counts against the
+# model's own score (0 = pure model, 1 = pure keywords). Small NLI models only
+# see the label NAME as their hypothesis, so this is how the example phrases in
+# a description actually influence the outcome.
+LEXICAL_WEIGHT = float(os.getenv("LEXICAL_WEIGHT", "0.6"))
+
+# Load the model at startup instead of on the first request.
+PRELOAD_MODEL = os.getenv("PRELOAD_MODEL", "1") not in ("0", "false", "False")
+
+TRANSLATE_ENABLED = os.getenv("TRANSLATE_ENABLED", "1") not in ("0", "false", "False")
+TRANSLATE_TIMEOUT = float(os.getenv("TRANSLATE_TIMEOUT", "8"))
+
+# Seed labels, only inserted when the label table is empty.
+DEFAULT_LABELS = [
+    ("Water Supply", "No water, low pressure, dirty or contaminated water, burst pipe, leaking main"),
+    ("Electricity", "Power cut, outage, voltage fluctuation, broken street light, damaged electric pole or wire"),
+    ("Road & Transport", "Potholes, damaged road, blocked street, broken pavement, traffic signal not working"),
+    ("Waste & Sanitation", "Garbage not collected, overflowing bin, blocked drain, sewage overflow, bad smell"),
+    ("Public Health", "Mosquito breeding, stray animals, food safety, dengue, unhygienic public place"),
+    ("Noise & Pollution", "Loud noise, construction sound, air pollution, smoke, illegal dumping"),
+    ("Building & Property", "Illegal construction, unsafe building, encroachment, permit issue"),
+    ("Other", "Anything that does not fit the other categories"),
+]

app/main.py

@@ -0,0 +1,239 @@
+"""FastAPI app: multilingual complaint classification with runtime labels."""
+from __future__ import annotations
+
+import logging
+import threading
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException, Query, Request
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from starlette.concurrency import run_in_threadpool
+
+from . import classifier, store
+from .config import CONFIDENCE_THRESHOLD, MODEL_NAME, PRELOAD_MODEL
+from .schemas import ClassifyRequest, ClassifyResponse, LabelIn, LabelOut, LabelPatch
+from .translator import TranslationResult, detect_language, language_name, to_english
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-7s %(name)s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+log = logging.getLogger("app")
+
+BASE_DIR = Path(__file__).resolve().parent
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    store.init_db()
+    log.info("Database ready at %s", store.DB_PATH)
+    if PRELOAD_MODEL:
+        # Load in the background so the UI is reachable during the first download.
+        threading.Thread(target=classifier.load_model, name="model-loader",
+                         daemon=True).start()
+        log.info("Loading %s in the background...", MODEL_NAME)
+    yield
+
+
+app = FastAPI(
+    title="Complaint Classifier",
+    description=(
+        "Multilingual complaint intake. Detects the language, translates to English "
+        "with Google Translate, then classifies against labels you can edit at "
+        "runtime using a small zero-shot NLI model."
+    ),
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+app.mount("/static", StaticFiles(directory=BASE_DIR / "static"), name="static")
+templates = Jinja2Templates(directory=str(BASE_DIR / "templates"))
+
+
+def label_hue(name: str) -> int:
+    """Stable colour for a label name. Mirrored by hueOf() in app.js so
+    server-rendered and client-rendered pills always match."""
+    h = 0
+    for ch in str(name):
+        h = (h * 31 + ord(ch)) & 0xFFFFFFFF
+    return h % 360
+
+
+templates.env.filters["hue"] = label_hue
+
+
+@app.exception_handler(ValueError)
+async def value_error_handler(_: Request, exc: ValueError):
+    return JSONResponse(status_code=400, content={"detail": str(exc)})
+
+
+def _label_out(row: dict) -> dict:
+    return {**row, "active": bool(row["active"])}
+
+
+# ------------------------------------------------------------------ pages ---
+
+@app.get("/", include_in_schema=False)
+async def page_classify(request: Request):
+    return templates.TemplateResponse(
+        "index.html",
+        {"request": request, "page": "classify",
+         "labels": store.list_labels(active_only=True),
+         "threshold": CONFIDENCE_THRESHOLD},
+    )
+
+
+@app.get("/labels", include_in_schema=False)
+async def page_labels(request: Request):
+    return templates.TemplateResponse(
+        "labels.html",
+        {"request": request, "page": "labels", "labels": store.list_labels()},
+    )
+
+
+@app.get("/history", include_in_schema=False)
+async def page_history(request: Request):
+    return templates.TemplateResponse(
+        "history.html",
+        {"request": request, "page": "history",
+         "complaints": store.list_complaints(limit=200),
+         "counts": store.label_counts()},
+    )
+
+
+# -------------------------------------------------------------- classify ----
+
+@app.post("/api/classify", response_model=ClassifyResponse, tags=["classify"])
+async def api_classify(req: ClassifyRequest):
+    """Detect language -> translate to English -> zero-shot classify."""
+    text = req.text.strip()
+    if not text:
+        raise HTTPException(400, "Complaint text is empty.")
+
+    # 1. language detection + translation (network I/O -> threadpool)
+    if req.translate:
+        tr = await run_in_threadpool(to_english, text)
+    else:
+        lang, conf = await run_in_threadpool(detect_language, text)
+        tr = TranslationResult(text, text, lang, language_name(lang), conf, False,
+                               "Translation skipped by request.")
+
+    # 2. resolve the label set for this request
+    if req.labels:
+        labels = [{"name": n.strip(), "description": ""} for n in req.labels if n.strip()]
+    else:
+        labels = store.list_labels(active_only=True)
+    if not labels:
+        raise HTTPException(400, "No active labels configured. Add labels on the Labels page.")
+
+    # 3. classify (CPU bound -> threadpool)
+    try:
+        result = await run_in_threadpool(
+            classifier.classify, tr.text or text, labels, req.multi_label, req.threshold
+        )
+    except ValueError as exc:
+        raise HTTPException(400, str(exc)) from exc
+
+    # 4. persist
+    complaint_id = None
+    if req.save:
+        complaint_id = await run_in_threadpool(
+            store.save_complaint,
+            {
+                "original_text": tr.original_text,
+                "translated_text": tr.text,
+                "source_lang": tr.source_lang,
+                "was_translated": tr.was_translated,
+                "predicted_label": result["predicted_label"],
+                "confidence": result["confidence"],
+                "scores": result["scores"],
+                "engine": result["engine"],
+                "took_ms": result["took_ms"],
+            },
+        )
+
+    return {
+        "id": complaint_id,
+        **result,
+        "translation": {
+            "source_lang": tr.source_lang,
+            "source_lang_name": tr.source_lang_name,
+            "detection_confidence": round(tr.confidence, 4),
+            "was_translated": tr.was_translated,
+            "original_text": tr.original_text,
+            "translated_text": tr.text,
+            "note": tr.note,
+        },
+    }
+
+
+# ---------------------------------------------------------------- labels ----
+
+@app.get("/api/labels", response_model=list[LabelOut], tags=["labels"])
+async def api_list_labels(active_only: bool = Query(False)):
+    return [_label_out(l) for l in store.list_labels(active_only=active_only)]
+
+
+@app.post("/api/labels", response_model=LabelOut, status_code=201, tags=["labels"])
+async def api_add_label(body: LabelIn):
+    try:
+        return _label_out(store.add_label(body.name, body.description, body.active))
+    except ValueError as exc:
+        raise HTTPException(409, str(exc)) from exc
+
+
+@app.patch("/api/labels/{label_id}", response_model=LabelOut, tags=["labels"])
+async def api_update_label(label_id: int, body: LabelPatch):
+    try:
+        row = store.update_label(label_id, body.name, body.description, body.active)
+    except ValueError as exc:
+        raise HTTPException(409, str(exc)) from exc
+    if row is None:
+        raise HTTPException(404, "Label not found.")
+    return _label_out(row)
+
+
+@app.delete("/api/labels/{label_id}", status_code=204, tags=["labels"])
+async def api_delete_label(label_id: int):
+    if not store.delete_label(label_id):
+        raise HTTPException(404, "Label not found.")
+
+
+# --------------------------------------------------------------- history ----
+
+@app.get("/api/history", tags=["history"])
+async def api_history(limit: int = Query(100, ge=1, le=1000), label: str | None = None):
+    return store.list_complaints(limit=limit, label=label)
+
+
+@app.get("/api/stats", tags=["history"])
+async def api_stats():
+    counts = store.label_counts()
+    return {"total": sum(c["count"] for c in counts), "by_label": counts}
+
+
+@app.delete("/api/history", tags=["history"])
+async def api_clear_history():
+    return {"deleted": store.clear_complaints()}
+
+
+# ---------------------------------------------------------------- system ----
+
+@app.get("/api/health", tags=["system"])
+async def api_health():
+    st = classifier.state()
+    return {
+        "status": "ok",
+        "model": st,
+        "labels_active": len(store.list_labels(active_only=True)),
+        "threshold": CONFIDENCE_THRESHOLD,
+    }
+
+
+@app.post("/api/model/reload", tags=["system"])
+async def api_reload_model():
+    return await run_in_threadpool(classifier.load_model, True)

app/schemas.py

@@ -0,0 +1,66 @@
+"""Request/response models for the JSON API."""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ClassifyRequest(BaseModel):
+    text: str = Field(..., min_length=1, max_length=8000,
+                      description="Complaint in any language.")
+    translate: bool = Field(True, description="Detect language and translate to English first.")
+    multi_label: bool = Field(False, description="Score labels independently instead of softmax.")
+    threshold: float | None = Field(None, ge=0.0, le=1.0,
+                                    description="Override the confidence threshold.")
+    save: bool = Field(True, description="Store the result in the complaint history.")
+    labels: list[str] | None = Field(
+        None, description="Ad-hoc label names for this request only; omit to use the saved labels."
+    )
+
+
+class LabelScore(BaseModel):
+    label: str
+    score: float
+
+
+class TranslationInfo(BaseModel):
+    source_lang: str
+    source_lang_name: str
+    detection_confidence: float
+    was_translated: bool
+    original_text: str
+    translated_text: str
+    note: str = ""
+
+
+class ClassifyResponse(BaseModel):
+    id: int | None = None
+    predicted_label: str
+    confidence: float
+    confident: bool
+    threshold: float
+    scores: list[LabelScore]
+    translation: TranslationInfo
+    engine: str
+    multi_label: bool
+    took_ms: int
+
+
+class LabelIn(BaseModel):
+    name: str = Field(..., min_length=1, max_length=80)
+    description: str = Field("", max_length=500,
+                             description="Example phrases; strongly improves zero-shot accuracy.")
+    active: bool = True
+
+
+class LabelPatch(BaseModel):
+    name: str | None = Field(None, min_length=1, max_length=80)
+    description: str | None = Field(None, max_length=500)
+    active: bool | None = None
+
+
+class LabelOut(BaseModel):
+    id: int
+    name: str
+    description: str
+    active: bool
+    created_at: str

app/static/css/style.css

@@ -0,0 +1,596 @@
+/* ==========================================================================
+   Complaint Classifier — design system
+   Indigo/violet accent, soft elevated surfaces, full light+dark support.
+   ========================================================================== */
+
+:root {
+  /* surfaces */
+  --bg: #f4f6fb;
+  --bg-tint: #eceffa;
+  --surface: #ffffff;
+  --surface-2: #f8f9fd;
+  --line: #e4e8f4;
+  --line-strong: #d3d9ea;
+
+  /* text */
+  --ink: #171a26;
+  --ink-2: #414a63;
+  --muted: #6d7793;
+  --faint: #98a1b8;
+
+  /* brand */
+  --accent: #5b5bd6;
+  --accent-2: #8b5cf6;
+  --accent-ink: #4a45c4;
+  --accent-soft: #ecebfd;
+  --accent-line: #d5d3fa;
+  --grad: linear-gradient(135deg, #6366f1 0%, #8b5cf6 55%, #a855f7 100%);
+  --grad-soft: linear-gradient(135deg, #eef2ff 0%, #f5f0ff 100%);
+
+  /* semantic */
+  --good: #0d9f6e;
+  --good-soft: #e3f7ef;
+  --warn: #b45309;
+  --warn-soft: #fdf3e3;
+  --danger: #dc2626;
+  --danger-soft: #fdeced;
+
+  /* shape */
+  --r-sm: 8px;
+  --r: 14px;
+  --r-lg: 20px;
+  --shadow-sm: 0 1px 2px rgba(23, 26, 38, .06);
+  --shadow: 0 1px 3px rgba(23, 26, 38, .06), 0 8px 24px -8px rgba(23, 26, 38, .10);
+  --shadow-lg: 0 2px 8px rgba(23, 26, 38, .06), 0 24px 48px -16px rgba(23, 26, 38, .18);
+  --ring: 0 0 0 3px var(--accent-soft);
+
+  --font: "Inter", ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto,
+          "Noto Sans", "Noto Sans Sinhala", "Noto Sans Tamil", sans-serif;
+  --mono: "JetBrains Mono", ui-monospace, "SF Mono", "Cascadia Code", Consolas, monospace;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0a0c13;
+    --bg-tint: #0f1220;
+    --surface: #141824;
+    --surface-2: #1a1f2e;
+    --line: #242a3b;
+    --line-strong: #333a50;
+
+    --ink: #e9ecf5;
+    --ink-2: #b9c0d4;
+    --muted: #8790a8;
+    --faint: #646d85;
+
+    --accent: #818cf8;
+    --accent-2: #a78bfa;
+    --accent-ink: #a5b0ff;
+    --accent-soft: #1e2340;
+    --accent-line: #2f3660;
+    --grad: linear-gradient(135deg, #818cf8 0%, #a78bfa 55%, #c084fc 100%);
+    --grad-soft: linear-gradient(135deg, #171b2e 0%, #1d1830 100%);
+
+    --good: #34d399;
+    --good-soft: #10241d;
+    --warn: #fbbf24;
+    --warn-soft: #241d10;
+    --danger: #f87171;
+    --danger-soft: #2a1418;
+
+    --shadow-sm: 0 1px 2px rgba(0, 0, 0, .5);
+    --shadow: 0 1px 3px rgba(0, 0, 0, .5), 0 8px 24px -8px rgba(0, 0, 0, .6);
+    --shadow-lg: 0 2px 8px rgba(0, 0, 0, .5), 0 24px 48px -16px rgba(0, 0, 0, .7);
+    --ring: 0 0 0 3px rgba(129, 140, 248, .25);
+  }
+}
+
+* { box-sizing: border-box; }
+
+html { -webkit-text-size-adjust: 100%; }
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background: var(--bg);
+  background-image:
+    radial-gradient(900px 400px at 12% -8%, var(--bg-tint), transparent 70%),
+    radial-gradient(700px 360px at 100% 0%, var(--accent-soft), transparent 65%);
+  background-attachment: fixed;
+  color: var(--ink);
+  font-family: var(--font);
+  font-size: 15px;
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+}
+
+.wrap { max-width: 1240px; margin: 0 auto; padding: 0 24px; }
+
+/* ============================================================== topbar === */
+
+.topbar {
+  position: sticky; top: 0; z-index: 40;
+  background: color-mix(in srgb, var(--surface) 78%, transparent);
+  backdrop-filter: saturate(1.6) blur(14px);
+  -webkit-backdrop-filter: saturate(1.6) blur(14px);
+  border-bottom: 1px solid var(--line);
+}
+.topbar-inner { display: flex; align-items: center; gap: 20px; height: 64px; }
+
+.brand {
+  display: flex; align-items: center; gap: 11px;
+  color: var(--ink); text-decoration: none;
+  font-weight: 700; font-size: 15.5px; letter-spacing: -.015em; white-space: nowrap;
+}
+.brand-mark {
+  display: grid; place-items: center;
+  width: 32px; height: 32px; border-radius: 10px;
+  background: var(--grad); color: #fff;
+  font-size: 12px; font-weight: 800; letter-spacing: -.03em;
+  box-shadow: 0 4px 12px -3px rgba(99, 102, 241, .55);
+}
+
+.nav { display: flex; gap: 2px; margin-left: auto; }
+.nav a {
+  display: flex; align-items: center; gap: 7px;
+  padding: 8px 14px; border-radius: 10px;
+  color: var(--muted); text-decoration: none;
+  font-weight: 500; font-size: 14px;
+  transition: background .16s, color .16s;
+}
+.nav a svg { width: 16px; height: 16px; opacity: .85; }
+.nav a:hover { background: var(--surface-2); color: var(--ink); }
+.nav a.active { background: var(--accent-soft); color: var(--accent-ink); font-weight: 600; }
+.nav a.active svg { opacity: 1; }
+
+.model-status {
+  display: flex; align-items: center; gap: 8px;
+  padding: 6px 12px; border-radius: 999px;
+  background: var(--surface-2); border: 1px solid var(--line);
+  font-size: 12px; color: var(--muted); white-space: nowrap;
+}
+.dot { width: 7px; height: 7px; border-radius: 50%; background: var(--faint); flex: none; }
+.dot-ok { background: var(--good); box-shadow: 0 0 0 3px color-mix(in srgb, var(--good) 22%, transparent); }
+.dot-load { background: var(--warn); animation: pulse 1.4s ease-in-out infinite; }
+.dot-bad { background: var(--danger); box-shadow: 0 0 0 3px color-mix(in srgb, var(--danger) 22%, transparent); }
+@keyframes pulse {
+  0%, 100% { opacity: 1; box-shadow: 0 0 0 0 color-mix(in srgb, var(--warn) 45%, transparent); }
+  50% { opacity: .65; box-shadow: 0 0 0 5px transparent; }
+}
+
+/* ================================================================ page === */
+
+.page { padding: 30px 24px 12px; display: flex; flex-direction: column; gap: 20px; }
+
+.hero { margin-bottom: 2px; }
+.hero h1 {
+  margin: 0 0 8px;
+  font-size: clamp(26px, 3.4vw, 34px); font-weight: 800;
+  letter-spacing: -.03em; line-height: 1.15;
+}
+.hero h1 .grad {
+  background: var(--grad); -webkit-background-clip: text; background-clip: text;
+  -webkit-text-fill-color: transparent; color: transparent;
+}
+.hero p { margin: 0; color: var(--muted); font-size: 15.5px; max-width: 68ch; }
+
+.grid-2 { display: grid; grid-template-columns: 1.05fr .95fr; gap: 20px; align-items: start; }
+@media (max-width: 980px) { .grid-2 { grid-template-columns: 1fr; } }
+
+.card {
+  background: var(--surface);
+  border: 1px solid var(--line);
+  border-radius: var(--r-lg);
+  box-shadow: var(--shadow);
+  padding: 24px;
+}
+.card h2 {
+  font-size: 16px; font-weight: 650; margin: 0 0 4px; letter-spacing: -.015em;
+  display: flex; align-items: center; gap: 9px;
+}
+.card h2 svg { width: 17px; height: 17px; color: var(--accent); }
+.card h3 {
+  font-size: 11.5px; font-weight: 700; margin: 22px 0 11px;
+  color: var(--faint); text-transform: uppercase; letter-spacing: .09em;
+}
+.sub { color: var(--muted); font-size: 13.5px; margin: 0 0 16px; }
+
+.muted { color: var(--muted); }
+.small { font-size: 12.5px; }
+.mono { font-family: var(--mono); font-size: 12.5px; }
+.center { text-align: center; }
+.right { text-align: right; }
+.hidden { display: none !important; }
+.row-between {
+  display: flex; align-items: center; justify-content: space-between;
+  gap: 14px; flex-wrap: wrap; margin-bottom: 12px;
+}
+
+/* ============================================================== inputs === */
+
+textarea, input[type=text], input[type=search] {
+  width: 100%; padding: 13px 15px;
+  border: 1px solid var(--line-strong); border-radius: var(--r);
+  background: var(--surface-2); color: var(--ink);
+  font-family: inherit; font-size: 14.5px; line-height: 1.6;
+  resize: vertical;
+  transition: border-color .16s, box-shadow .16s, background .16s;
+}
+textarea::placeholder, input::placeholder { color: var(--faint); }
+textarea:focus, input[type=text]:focus, input[type=search]:focus {
+  outline: none; border-color: var(--accent);
+  background: var(--surface); box-shadow: var(--ring);
+}
+textarea { min-height: 150px; }
+
+input[type=checkbox] { accent-color: var(--accent); width: 15px; height: 15px; cursor: pointer; }
+input[type=range] { accent-color: var(--accent); }
+
+.samples { display: flex; flex-wrap: wrap; gap: 7px; align-items: center; margin: 14px 0 4px; }
+.samples-label {
+  font-size: 11.5px; font-weight: 700; color: var(--faint);
+  text-transform: uppercase; letter-spacing: .08em; margin-right: 2px;
+}
+.chip {
+  display: inline-flex; align-items: center; gap: 6px;
+  border: 1px solid var(--line-strong); background: var(--surface-2); color: var(--ink-2);
+  border-radius: 999px; padding: 5px 13px;
+  font-family: inherit; font-size: 12.5px; font-weight: 500; cursor: pointer;
+  transition: all .16s;
+}
+.chip:hover {
+  border-color: var(--accent); color: var(--accent-ink);
+  background: var(--accent-soft); transform: translateY(-1px);
+}
+.chip .flag { font-size: 13px; }
+
+.options {
+  display: flex; flex-wrap: wrap; gap: 10px 22px; align-items: center;
+  margin: 18px 0 4px; padding: 14px 16px;
+  background: var(--surface-2); border: 1px solid var(--line); border-radius: var(--r);
+  font-size: 13px;
+}
+.check { display: flex; align-items: center; gap: 8px; color: var(--ink-2); cursor: pointer; user-select: none; }
+.check:hover { color: var(--ink); }
+.range { display: flex; align-items: center; gap: 9px; color: var(--ink-2); margin-left: auto; }
+.range input[type=range] { width: 100px; }
+.range output {
+  font-family: var(--mono); font-size: 12px; font-weight: 600; color: var(--accent-ink);
+  background: var(--accent-soft); border-radius: 6px; padding: 1px 7px; min-width: 40px; text-align: center;
+}
+
+.actions { display: flex; align-items: center; gap: 11px; margin-top: 18px; }
+
+.btn {
+  display: inline-flex; align-items: center; justify-content: center; gap: 8px;
+  border: 1px solid var(--line-strong); background: var(--surface); color: var(--ink);
+  padding: 10px 18px; border-radius: var(--r);
+  font-family: inherit; font-size: 14px; font-weight: 550;
+  cursor: pointer; text-decoration: none; white-space: nowrap;
+  transition: all .16s;
+}
+.btn svg { width: 16px; height: 16px; }
+.btn:hover { border-color: var(--line-strong); background: var(--surface-2); transform: translateY(-1px); }
+.btn:active { transform: translateY(0); }
+.btn:focus-visible { outline: none; box-shadow: var(--ring); }
+
+.btn-primary {
+  background: var(--grad); border-color: transparent; color: #fff;
+  box-shadow: 0 4px 14px -4px rgba(99, 102, 241, .6);
+}
+.btn-primary:hover {
+  background: var(--grad); color: #fff;
+  box-shadow: 0 8px 22px -6px rgba(99, 102, 241, .7); transform: translateY(-1px);
+}
+.btn-primary:disabled {
+  opacity: .55; cursor: not-allowed; transform: none;
+  box-shadow: 0 4px 14px -4px rgba(99, 102, 241, .35);
+}
+.btn-sm { padding: 6px 12px; font-size: 12.5px; border-radius: 9px; }
+.btn-danger { color: var(--danger); }
+.btn-danger:hover { border-color: var(--danger); background: var(--danger-soft); }
+.btn-ghost { border-color: transparent; background: transparent; color: var(--muted); }
+.btn-ghost:hover { background: var(--surface-2); color: var(--ink); }
+
+.spinner {
+  width: 17px; height: 17px; border-radius: 50%;
+  border: 2px solid var(--line-strong); border-top-color: var(--accent);
+  animation: spin .65s linear infinite;
+}
+@keyframes spin { to { transform: rotate(360deg); } }
+
+/* ============================================================== result === */
+
+.empty {
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  text-align: center; padding: 44px 20px; color: var(--muted);
+}
+.empty-icon {
+  width: 52px; height: 52px; border-radius: 16px; margin-bottom: 16px;
+  display: grid; place-items: center;
+  background: var(--grad-soft); border: 1px solid var(--accent-line); color: var(--accent);
+}
+.empty-icon svg { width: 24px; height: 24px; }
+.empty strong { color: var(--ink); font-weight: 600; display: block; margin-bottom: 5px; font-size: 14.5px; }
+.empty p { margin: 0; font-size: 13px; max-width: 40ch; }
+
+.verdict {
+  display: flex; align-items: center; gap: 20px;
+  padding: 20px; border-radius: var(--r);
+  background: var(--grad-soft); border: 1px solid var(--accent-line);
+}
+.verdict-main { min-width: 0; flex: 1; }
+.verdict-eyebrow {
+  font-size: 11px; font-weight: 700; color: var(--accent-ink);
+  text-transform: uppercase; letter-spacing: .1em; margin-bottom: 5px;
+}
+.verdict-label {
+  font-size: clamp(20px, 2.6vw, 27px); font-weight: 750;
+  letter-spacing: -.03em; line-height: 1.15; word-break: break-word;
+}
+
+/* confidence ring */
+.ring { position: relative; width: 86px; height: 86px; flex: none; }
+.ring svg { width: 100%; height: 100%; transform: rotate(-90deg); }
+.ring circle { fill: none; stroke-width: 9; stroke-linecap: round; }
+.ring .ring-bg { stroke: var(--accent-line); }
+.ring .ring-fg {
+  stroke: url(#ringGrad);
+  stroke-dasharray: 232.5; stroke-dashoffset: 232.5;
+  transition: stroke-dashoffset .8s cubic-bezier(.22, 1, .36, 1);
+}
+.ring.low .ring-fg { stroke: var(--warn); }
+.ring-val {
+  position: absolute; inset: 0; display: grid; place-items: center;
+  font-family: var(--mono); font-size: 17px; font-weight: 700;
+  letter-spacing: -.04em; color: var(--ink);
+}
+
+.warn {
+  display: flex; gap: 10px; align-items: flex-start;
+  background: var(--warn-soft); color: var(--warn);
+  border: 1px solid color-mix(in srgb, var(--warn) 28%, transparent);
+  border-radius: var(--r); padding: 12px 14px; font-size: 13px; margin-top: 14px;
+}
+.warn svg { width: 16px; height: 16px; flex: none; margin-top: 2px; }
+.warn a { color: inherit; }
+
+.kv { display: grid; grid-template-columns: repeat(3, 1fr); gap: 10px; margin-top: 16px; }
+.kv > div {
+  padding: 11px 13px; border-radius: var(--r-sm);
+  background: var(--surface-2); border: 1px solid var(--line); min-width: 0;
+}
+.kv-k {
+  font-size: 10.5px; font-weight: 700; color: var(--faint);
+  text-transform: uppercase; letter-spacing: .08em; margin-bottom: 3px;
+}
+.kv-v {
+  font-size: 13.5px; font-weight: 600; color: var(--ink);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+
+.trans { margin-top: 16px; border: 1px solid var(--line); border-radius: var(--r); overflow: hidden; }
+.trans summary {
+  cursor: pointer; padding: 11px 15px; background: var(--surface-2);
+  font-size: 13px; font-weight: 550; color: var(--ink-2);
+  list-style: none; display: flex; align-items: center; gap: 8px;
+}
+.trans summary::-webkit-details-marker { display: none; }
+.trans summary::before {
+  content: "›"; font-size: 17px; line-height: 1; color: var(--faint);
+  transition: transform .18s; display: inline-block;
+}
+.trans[open] summary::before { transform: rotate(90deg); }
+.trans-body { padding: 14px 15px; }
+.q-label {
+  font-size: 10.5px; font-weight: 700; color: var(--faint);
+  text-transform: uppercase; letter-spacing: .08em; margin-bottom: 4px;
+}
+.quote {
+  margin: 0 0 14px; padding: 10px 13px;
+  background: var(--surface-2); border-left: 3px solid var(--accent-line);
+  border-radius: 0 var(--r-sm) var(--r-sm) 0;
+  font-size: 13.5px; word-break: break-word;
+}
+.quote:last-of-type { margin-bottom: 0; }
+.note { color: var(--warn); font-size: 12.5px; margin: 10px 0 0; }
+
+.scores { display: flex; flex-direction: column; gap: 3px; }
+.score-row {
+  display: grid; grid-template-columns: minmax(0, 1fr) 96px 46px;
+  align-items: center; gap: 12px;
+  padding: 7px 10px; border-radius: var(--r-sm);
+  transition: background .16s;
+}
+.score-row:hover { background: var(--surface-2); }
+.score-row .n {
+  font-size: 13px; color: var(--ink-2);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  display: flex; align-items: center; gap: 8px;
+}
+.score-row .n::before {
+  content: ""; width: 7px; height: 7px; border-radius: 2px; flex: none;
+  background: hsl(var(--h, 250) 62% 58%);
+}
+.score-row .v {
+  font-family: var(--mono); font-size: 12px; font-weight: 600;
+  text-align: right; color: var(--muted);
+}
+.score-row.top { background: var(--accent-soft); }
+.score-row.top .n { font-weight: 650; color: var(--ink); }
+.score-row.top .v { color: var(--accent-ink); }
+
+.bar { background: var(--line); border-radius: 999px; height: 7px; overflow: hidden; }
+.bar span {
+  display: block; height: 100%; border-radius: 999px;
+  background: hsl(var(--h, 250) 62% 58%);
+  width: 0; transition: width .7s cubic-bezier(.22, 1, .36, 1);
+}
+.score-row.top .bar span { background: var(--grad); }
+
+/* ============================================================== labels === */
+
+.badge {
+  background: var(--accent-soft); color: var(--accent-ink);
+  border-radius: 999px; padding: 2px 10px;
+  font-size: 12px; font-weight: 700; font-family: var(--mono);
+}
+.pill {
+  display: inline-flex; align-items: center; gap: 7px;
+  border-radius: 999px; padding: 5px 13px;
+  font-size: 12.5px; font-weight: 550; white-space: nowrap;
+  background: hsl(var(--h, 250) 70% 96%);
+  color: hsl(var(--h, 250) 52% 38%);
+  border: 1px solid hsl(var(--h, 250) 60% 88%);
+}
+.pill::before {
+  content: ""; width: 6px; height: 6px; border-radius: 50%; flex: none;
+  background: hsl(var(--h, 250) 62% 55%);
+}
+@media (prefers-color-scheme: dark) {
+  .pill {
+    background: hsl(var(--h, 250) 40% 16%);
+    color: hsl(var(--h, 250) 70% 76%);
+    border-color: hsl(var(--h, 250) 35% 26%);
+  }
+  .score-row .n::before, .bar span { background: hsl(var(--h, 250) 60% 62%); }
+}
+.label-strip { display: flex; flex-wrap: wrap; gap: 8px; margin: 4px 0 14px; }
+
+.add-form {
+  display: grid; grid-template-columns: minmax(180px, 1fr) minmax(240px, 2fr) auto;
+  gap: 12px; align-items: end; margin-top: 18px;
+  padding: 18px; background: var(--grad-soft);
+  border: 1px solid var(--accent-line); border-radius: var(--r);
+}
+@media (max-width: 760px) { .add-form { grid-template-columns: 1fr; } }
+.field { display: flex; flex-direction: column; gap: 6px; min-width: 0; }
+.field label { font-size: 12px; font-weight: 600; color: var(--ink-2); }
+.field input { background: var(--surface); }
+
+.table { width: 100%; border-collapse: separate; border-spacing: 0; }
+.table th {
+  text-align: left; font-size: 10.5px; font-weight: 700; color: var(--faint);
+  text-transform: uppercase; letter-spacing: .09em;
+  padding: 10px 10px; border-bottom: 1px solid var(--line);
+}
+.table td { padding: 8px 10px; border-bottom: 1px solid var(--line); vertical-align: middle; }
+.table tbody tr { transition: background .16s; }
+.table tbody tr:hover { background: var(--surface-2); }
+.table tr:last-child td { border-bottom: 0; }
+
+.cell-input {
+  width: 100%; padding: 8px 11px;
+  border: 1px solid transparent; border-radius: var(--r-sm);
+  background: transparent; color: var(--ink);
+  font-family: inherit; font-size: 13.5px;
+  transition: all .16s;
+}
+.cell-input:hover { border-color: var(--line-strong); background: var(--surface-2); }
+.cell-input:focus {
+  outline: none; border-color: var(--accent);
+  background: var(--surface); box-shadow: var(--ring);
+}
+.cell-input.name { font-weight: 600; }
+tr.dirty { background: var(--warn-soft) !important; }
+tr.dirty .save { border-color: var(--warn); color: var(--warn); font-weight: 650; }
+
+.switch { position: relative; display: inline-block; width: 38px; height: 22px; vertical-align: middle; }
+.switch input { opacity: 0; width: 0; height: 0; position: absolute; }
+.switch .slider {
+  position: absolute; inset: 0; cursor: pointer;
+  background: var(--line-strong); border-radius: 999px; transition: background .2s;
+}
+.switch .slider::before {
+  content: ""; position: absolute; height: 16px; width: 16px; left: 3px; top: 3px;
+  background: #fff; border-radius: 50%;
+  transition: transform .2s; box-shadow: var(--shadow-sm);
+}
+.switch input:checked + .slider { background: var(--accent); }
+.switch input:checked + .slider::before { transform: translateX(16px); }
+.switch input:focus-visible + .slider { box-shadow: var(--ring); }
+
+/* ============================================================= history === */
+
+.stats { display: grid; grid-template-columns: repeat(auto-fill, minmax(215px, 1fr)); gap: 12px; margin: 6px 0 22px; }
+.stat {
+  padding: 15px 16px; border-radius: var(--r);
+  background: var(--surface-2); border: 1px solid var(--line);
+  transition: transform .16s, box-shadow .16s;
+}
+.stat:hover { transform: translateY(-2px); box-shadow: var(--shadow); }
+.stat-top { display: flex; justify-content: space-between; align-items: baseline; gap: 10px; margin-bottom: 10px; }
+.stat-label {
+  font-size: 13px; font-weight: 600; color: var(--ink);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.stat-count {
+  font-family: var(--mono); font-size: 18px; font-weight: 700;
+  color: hsl(var(--h, 250) 55% 50%); letter-spacing: -.04em;
+}
+@media (prefers-color-scheme: dark) { .stat-count { color: hsl(var(--h, 250) 65% 68%); } }
+.stat .bar { height: 6px; }
+
+.filter-row { display: flex; align-items: center; gap: 14px; margin-bottom: 14px; flex-wrap: wrap; }
+.search-wrap { position: relative; flex: 1; max-width: 340px; }
+.search-wrap svg {
+  position: absolute; left: 13px; top: 50%; transform: translateY(-50%);
+  width: 15px; height: 15px; color: var(--faint); pointer-events: none;
+}
+.search-wrap input { padding-left: 37px; }
+
+.history td { font-size: 13.5px; }
+.c-orig { white-space: pre-wrap; word-break: break-word; color: var(--ink); line-height: 1.5; }
+.c-trans {
+  margin-top: 5px; padding-left: 10px;
+  border-left: 2px solid var(--accent-line); color: var(--muted); font-size: 12.5px;
+}
+.lang {
+  display: inline-block; font-family: var(--mono); font-size: 11px; font-weight: 600;
+  text-transform: uppercase; color: var(--ink-2);
+  background: var(--surface-2); border: 1px solid var(--line);
+  border-radius: 6px; padding: 2px 7px;
+}
+.tag {
+  display: inline-block; background: var(--accent-soft); color: var(--accent-ink);
+  border-radius: 5px; padding: 1px 6px; font-size: 10px; font-weight: 700;
+  margin-left: 4px; vertical-align: middle;
+}
+.conf-cell { display: flex; align-items: center; gap: 7px; }
+.conf-dot { width: 7px; height: 7px; border-radius: 50%; flex: none; background: var(--good); }
+.conf-dot.low { background: var(--warn); }
+
+.table-scroll { overflow-x: auto; margin: 0 -4px; padding: 0 4px; }
+
+/* ============================================================== footer === */
+
+.foot {
+  color: var(--faint); font-size: 12.5px; padding: 32px 24px 40px;
+  text-align: center; line-height: 1.9;
+}
+.foot .sep { opacity: .45; margin: 0 8px; }
+
+/* =============================================================== toast === */
+
+.toast {
+  position: fixed; left: 50%; bottom: 28px; transform: translate(-50%, 20px);
+  display: flex; align-items: center; gap: 10px;
+  background: var(--ink); color: var(--bg);
+  padding: 12px 20px; border-radius: 999px;
+  font-size: 13.5px; font-weight: 500;
+  box-shadow: var(--shadow-lg);
+  opacity: 0; pointer-events: none;
+  transition: opacity .22s, transform .22s cubic-bezier(.22, 1, .36, 1);
+  z-index: 80; max-width: min(90vw, 520px);
+}
+.toast.show { opacity: 1; transform: translate(-50%, 0); }
+.toast.err { background: var(--danger); color: #fff; }
+
+/* ========================================================= motion prefs === */
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: .01ms !important; animation-iteration-count: 1 !important;
+    transition-duration: .01ms !important;
+  }
+}

app/static/js/app.js

@@ -0,0 +1,87 @@
+/* Shared helpers: fetch wrapper, toasts, model-status poller. */
+
+const $ = (sel, root = document) => root.querySelector(sel);
+const $$ = (sel, root = document) => [...root.querySelectorAll(sel)];
+
+function toast(message, isError = false) {
+  const el = $("#toast");
+  if (!el) return;
+  el.textContent = message;
+  el.classList.toggle("err", isError);
+  el.classList.add("show");
+  clearTimeout(toast._t);
+  toast._t = setTimeout(() => el.classList.remove("show"), 3200);
+}
+
+/* Stable colour per label. Must match label_hue() in main.py so that
+   server-rendered and client-rendered pills agree. */
+function hueOf(name) {
+  let h = 0;
+  for (const ch of String(name)) h = (Math.imul(h, 31) + ch.codePointAt(0)) >>> 0;
+  return h % 360;
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+}
+
+async function api(path, { method = "GET", body } = {}) {
+  const res = await fetch(path, {
+    method,
+    headers: body ? { "Content-Type": "application/json" } : {},
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (res.status === 204) return null;
+
+  let payload = null;
+  try { payload = await res.json(); } catch { /* empty or non-JSON body */ }
+
+  if (!res.ok) {
+    const detail = payload?.detail;
+    const msg = Array.isArray(detail)
+      ? detail.map((d) => d.msg || JSON.stringify(d)).join("; ")
+      : detail || `Request failed (${res.status})`;
+    throw new Error(msg);
+  }
+  return payload;
+}
+
+/* ---------------------------------------------------------- model status */
+
+const STATUS_UI = {
+  ready:      ["dot-ok",   "model ready"],
+  loading:    ["dot-load", "loading model…"],
+  not_loaded: ["dot-idle", "model idle"],
+  failed:     ["dot-bad",  "keyword fallback"],
+};
+
+async function pollModelStatus() {
+  const box = $("#modelStatus");
+  if (!box) return;
+  const dot = $(".dot", box);
+  const text = $(".model-status-text", box);
+
+  try {
+    const health = await api("/api/health");
+    const st = health.model || {};
+    const [cls, label] = STATUS_UI[st.status] || STATUS_UI.not_loaded;
+
+    dot.className = "dot " + cls;
+    text.textContent = st.status === "ready"
+      ? `${label} · ${(st.model || "").split("/").pop()}`
+      : label;
+    box.title = st.error
+      ? `${st.model}\n${st.error}`
+      : `${st.model}${st.load_seconds ? ` · loaded in ${st.load_seconds}s` : ""}`;
+
+    if (st.status === "loading" || st.status === "not_loaded") {
+      setTimeout(pollModelStatus, 2500);
+    }
+  } catch {
+    dot.className = "dot dot-bad";
+    text.textContent = "server offline";
+  }
+}
+
+document.addEventListener("DOMContentLoaded", pollModelStatus);

app/static/js/classify.js

@@ -0,0 +1,127 @@
+/* Classify page: submit a complaint and render the result. */
+
+document.addEventListener("DOMContentLoaded", () => {
+  const input = $("#complaint");
+  const btn = $("#btnClassify");
+  const spin = $("#spin");
+  const thr = $("#optThreshold");
+
+  // r=37 in the ring SVG -> circumference 2*pi*37
+  const RING_C = 2 * Math.PI * 37;
+
+  thr.addEventListener("input", () => { $("#thrOut").value = (+thr.value).toFixed(2); });
+
+  $$(".chip").forEach((chip) =>
+    chip.addEventListener("click", () => {
+      input.value = chip.dataset.sample;
+      input.focus();
+    })
+  );
+
+  $("#btnClear").addEventListener("click", () => {
+    input.value = "";
+    $("#result").classList.add("hidden");
+    $("#resultEmpty").classList.remove("hidden");
+    input.focus();
+  });
+
+  input.addEventListener("keydown", (e) => {
+    if ((e.ctrlKey || e.metaKey) && e.key === "Enter") classify();
+  });
+  btn.addEventListener("click", classify);
+
+  async function classify() {
+    const text = input.value.trim();
+    if (!text) { toast("Type a complaint first.", true); input.focus(); return; }
+
+    btn.disabled = true;
+    spin.classList.remove("hidden");
+    try {
+      const data = await api("/api/classify", {
+        method: "POST",
+        body: {
+          text,
+          translate: $("#optTranslate").checked,
+          multi_label: $("#optMulti").checked,
+          save: $("#optSave").checked,
+          threshold: parseFloat(thr.value),
+        },
+      });
+      render(data);
+      toast(`Classified as "${data.predicted_label}" in ${data.took_ms} ms`);
+    } catch (err) {
+      toast(err.message, true);
+    } finally {
+      btn.disabled = false;
+      spin.classList.add("hidden");
+    }
+  }
+
+  function render(d) {
+    $("#resultEmpty").classList.add("hidden");
+    $("#result").classList.remove("hidden");
+
+    $("#rLabel").textContent = d.predicted_label;
+    $("#rTime").textContent = d.took_ms + " ms";
+    $("#rEngine").textContent = d.engine;
+    $("#rEngine").title = d.engine;
+
+    // Confidence ring -- reset to empty first so the sweep animates every time.
+    const ring = $("#rRing");
+    const arc = $(".ring-fg", ring);
+    ring.classList.toggle("low", !d.confident);
+    $("#rConf").textContent = Math.round(d.confidence * 100) + "%";
+    arc.style.strokeDasharray = RING_C;
+    arc.style.strokeDashoffset = RING_C;
+    requestAnimationFrame(() =>
+      requestAnimationFrame(() => {
+        arc.style.strokeDashoffset = RING_C * (1 - Math.min(d.confidence, 1));
+      })
+    );
+
+    const t = d.translation;
+    // Romanised text (Hindi typed in Latin letters, say) often detects with low
+    // confidence even when the translation itself is fine -- say so rather than
+    // presenting a shaky guess as fact.
+    const shaky = t.detection_confidence > 0 && t.detection_confidence < 0.6 ? " · uncertain" : "";
+    const lang = `${t.source_lang_name} (${t.source_lang})${shaky}`;
+    $("#rLang").textContent = lang + (t.was_translated ? " → EN" : "");
+    $("#rLang").title = t.was_translated ? `${lang}, translated to English` : lang;
+
+    const warn = $("#rWarn");
+    if (!d.confident) {
+      $("#rWarnText").textContent =
+        `Low confidence — the top score of ${(d.confidence * 100).toFixed(1)}% is below the ` +
+        `${(d.threshold * 100).toFixed(0)}% threshold. Treat this as unclassified, or add a ` +
+        `label that covers this kind of complaint.`;
+      warn.classList.remove("hidden");
+    } else {
+      warn.classList.add("hidden");
+    }
+
+    $("#rOriginal").textContent = t.original_text;
+    $("#rTranslated").textContent = t.translated_text;
+    const note = $("#rNote");
+    note.textContent = t.note || "";
+    note.classList.toggle("hidden", !t.note);
+    $("#rTransBox").open = t.was_translated;
+
+    // Bars are scaled to the top score so small differences stay readable.
+    const max = Math.max(...d.scores.map((s) => s.score), 0.0001);
+    $("#rScores").innerHTML = d.scores
+      .map((s, i) => `
+        <div class="score-row ${i === 0 ? "top" : ""}" style="--h: ${hueOf(s.label)}">
+          <span class="n" title="${escapeHtml(s.label)}">${escapeHtml(s.label)}</span>
+          <span class="bar"><span data-w="${(s.score / max * 100).toFixed(1)}%"></span></span>
+          <span class="v">${(s.score * 100).toFixed(1)}%</span>
+        </div>`)
+      .join("");
+
+    // Stagger the bar fills so the ranking reads left-to-right, top-down.
+    requestAnimationFrame(() =>
+      $$("#rScores .bar > span").forEach((el, i) => {
+        setTimeout(() => { el.style.width = el.dataset.w; }, 40 + i * 35);
+      })
+    );
+  }
+});

app/static/js/history.js

@@ -0,0 +1,39 @@
+/* History page: client-side filtering, animated bars and history reset. */
+
+document.addEventListener("DOMContentLoaded", () => {
+  // Animate the breakdown bars in on load.
+  $$(".stat .bar > span").forEach((el, i) => {
+    const w = el.style.width;
+    el.style.width = "0";
+    setTimeout(() => { el.style.width = w; }, 60 + i * 45);
+  });
+
+  const filter = $("#filter");
+  if (filter) {
+    const rows = $$(".history tbody tr");
+    const countEl = $("#filterCount");
+    const totalText = countEl?.textContent || "";
+
+    filter.addEventListener("input", () => {
+      const q = filter.value.toLowerCase().trim();
+      let shown = 0;
+      rows.forEach((tr) => {
+        const hit = !q || tr.textContent.toLowerCase().includes(q);
+        tr.style.display = hit ? "" : "none";
+        if (hit) shown++;
+      });
+      if (countEl) countEl.textContent = q ? `${shown} of ${rows.length} shown` : totalText;
+    });
+  }
+
+  $("#btnClearHistory")?.addEventListener("click", async () => {
+    if (!confirm("Delete every stored complaint? This cannot be undone.")) return;
+    try {
+      const res = await api("/api/history", { method: "DELETE" });
+      toast(`Deleted ${res.deleted} complaint(s).`);
+      setTimeout(() => location.reload(), 700);
+    } catch (err) {
+      toast(err.message, true);
+    }
+  });
+});

app/static/js/labels.js

@@ -0,0 +1,124 @@
+/* Labels page: add, edit, toggle and delete labels without a page reload. */
+
+document.addEventListener("DOMContentLoaded", () => {
+  const tbody = $("#labelTable tbody");
+
+  /* ------------------------------------------------------------- add --- */
+  $("#addForm").addEventListener("submit", async (e) => {
+    e.preventDefault();
+    const name = $("#newName").value.trim();
+    const description = $("#newDesc").value.trim();
+    if (!name) return;
+
+    try {
+      const label = await api("/api/labels", {
+        method: "POST",
+        body: { name, description, active: true },
+      });
+      const row = rowFor(label);
+      tbody.appendChild(row);
+      $("#emptyLabels")?.remove();
+      row.animate(
+        [{ opacity: 0, transform: "translateY(-6px)" }, { opacity: 1, transform: "none" }],
+        { duration: 260, easing: "cubic-bezier(.22,1,.36,1)" }
+      );
+      $("#newName").value = "";
+      $("#newDesc").value = "";
+      $("#newName").focus();
+      bumpCount(1);
+      toast(`Added "${label.name}" — live for the next classification.`);
+    } catch (err) {
+      toast(err.message, true);
+    }
+  });
+
+  /* -------------------------------------------------- edit / delete --- */
+  tbody.addEventListener("click", async (e) => {
+    const row = e.target.closest("tr");
+    if (!row) return;
+
+    if (e.target.closest(".save")) {
+      await save(row, row.dataset.id);
+    } else if (e.target.closest(".del")) {
+      const name = $(".name", row).value;
+      if (!confirm(`Delete label "${name}"? Past complaints keep their label text.`)) return;
+      try {
+        await api(`/api/labels/${row.dataset.id}`, { method: "DELETE" });
+        row.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 160 })
+           .finished.then(() => row.remove());
+        bumpCount(-1);
+        toast(`Deleted "${name}".`);
+      } catch (err) {
+        toast(err.message, true);
+      }
+    }
+  });
+
+  // Toggling Active saves straight away; text edits just mark the row dirty.
+  tbody.addEventListener("change", (e) => {
+    if (e.target.classList.contains("active")) {
+      const row = e.target.closest("tr");
+      save(row, row.dataset.id);
+    }
+  });
+  tbody.addEventListener("input", (e) => {
+    if (e.target.classList.contains("cell-input")) {
+      e.target.closest("tr").classList.add("dirty");
+    }
+  });
+  tbody.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" && e.target.classList.contains("cell-input")) {
+      e.preventDefault();
+      const row = e.target.closest("tr");
+      save(row, row.dataset.id);
+    }
+  });
+
+  async function save(row, id) {
+    const body = {
+      name: $(".name", row).value.trim(),
+      description: $(".desc", row).value.trim(),
+      active: $(".active", row).checked,
+    };
+    if (!body.name) { toast("Label name cannot be empty.", true); return; }
+
+    try {
+      const updated = await api(`/api/labels/${id}`, { method: "PATCH", body });
+      row.classList.remove("dirty");
+      row.style.setProperty("--h", hueOf(updated.name)); // colour follows a rename
+      toast(`Saved "${updated.name}".`);
+    } catch (err) {
+      toast(err.message, true);
+    }
+  }
+
+  const TRASH_ICON = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6m3 0V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/></svg>`;
+
+  function rowFor(l) {
+    const tr = document.createElement("tr");
+    tr.dataset.id = l.id;
+    tr.style.setProperty("--h", hueOf(l.name));
+    tr.innerHTML = `
+      <td><input class="cell-input name" maxlength="80"></td>
+      <td><input class="cell-input desc" maxlength="500"
+                 placeholder="example phrases help the zero-shot model"></td>
+      <td class="center">
+        <label class="switch">
+          <input type="checkbox" class="active" ${l.active ? "checked" : ""}>
+          <span class="slider"></span>
+        </label>
+      </td>
+      <td class="right">
+        <button class="btn btn-sm save">Save</button>
+        <button class="btn btn-sm btn-danger del" title="Delete label">${TRASH_ICON}</button>
+      </td>`;
+    $(".name", tr).value = l.name;          // set via value, never innerHTML
+    $(".desc", tr).value = l.description;
+    return tr;
+  }
+
+  function bumpCount(delta) {
+    const el = $("#count");
+    el.textContent = Math.max(0, parseInt(el.textContent, 10) + delta);
+  }
+});

app/store.py

@@ -0,0 +1,193 @@
+"""SQLite persistence for labels and classified complaints.
+
+A fresh connection is opened per call so the module is safe to use from
+FastAPI's threadpool workers.
+"""
+import json
+import sqlite3
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any
+
+from .config import DB_PATH, DEFAULT_LABELS
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS labels (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    name        TEXT    NOT NULL UNIQUE,
+    description TEXT    NOT NULL DEFAULT '',
+    active      INTEGER NOT NULL DEFAULT 1,
+    created_at  TEXT    NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS complaints (
+    id             INTEGER PRIMARY KEY AUTOINCREMENT,
+    original_text  TEXT    NOT NULL,
+    translated_text TEXT   NOT NULL,
+    source_lang    TEXT    NOT NULL DEFAULT 'unknown',
+    was_translated INTEGER NOT NULL DEFAULT 0,
+    predicted_label TEXT   NOT NULL,
+    confidence     REAL    NOT NULL,
+    scores_json    TEXT    NOT NULL DEFAULT '[]',
+    engine         TEXT    NOT NULL DEFAULT '',
+    took_ms        INTEGER NOT NULL DEFAULT 0,
+    created_at     TEXT    NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_complaints_created ON complaints(created_at DESC);
+"""
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+@contextmanager
+def _conn():
+    conn = sqlite3.connect(DB_PATH, timeout=15)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    try:
+        yield conn
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def init_db() -> None:
+    with _conn() as conn:
+        conn.executescript(SCHEMA)
+        empty = conn.execute("SELECT COUNT(*) AS n FROM labels").fetchone()["n"] == 0
+        if empty:
+            conn.executemany(
+                "INSERT INTO labels (name, description, active, created_at) VALUES (?,?,1,?)",
+                [(name, desc, _now()) for name, desc in DEFAULT_LABELS],
+            )
+
+
+# ---------------------------------------------------------------- labels ----
+
+def list_labels(active_only: bool = False) -> list[dict[str, Any]]:
+    sql = "SELECT * FROM labels"
+    if active_only:
+        sql += " WHERE active = 1"
+    sql += " ORDER BY name COLLATE NOCASE"
+    with _conn() as conn:
+        return [dict(r) for r in conn.execute(sql)]
+
+
+def get_label(label_id: int) -> dict[str, Any] | None:
+    with _conn() as conn:
+        row = conn.execute("SELECT * FROM labels WHERE id = ?", (label_id,)).fetchone()
+    return dict(row) if row else None
+
+
+def add_label(name: str, description: str = "", active: bool = True) -> dict[str, Any]:
+    name = name.strip()
+    if not name:
+        raise ValueError("Label name cannot be empty.")
+    with _conn() as conn:
+        try:
+            cur = conn.execute(
+                "INSERT INTO labels (name, description, active, created_at) VALUES (?,?,?,?)",
+                (name, description.strip(), int(active), _now()),
+            )
+        except sqlite3.IntegrityError as exc:
+            raise ValueError(f"Label {name!r} already exists.") from exc
+        row = conn.execute("SELECT * FROM labels WHERE id = ?", (cur.lastrowid,)).fetchone()
+    return dict(row)
+
+
+def update_label(
+    label_id: int,
+    name: str | None = None,
+    description: str | None = None,
+    active: bool | None = None,
+) -> dict[str, Any] | None:
+    sets, params = [], []
+    if name is not None:
+        if not name.strip():
+            raise ValueError("Label name cannot be empty.")
+        sets.append("name = ?")
+        params.append(name.strip())
+    if description is not None:
+        sets.append("description = ?")
+        params.append(description.strip())
+    if active is not None:
+        sets.append("active = ?")
+        params.append(int(active))
+    if not sets:
+        return get_label(label_id)
+
+    params.append(label_id)
+    with _conn() as conn:
+        try:
+            conn.execute(f"UPDATE labels SET {', '.join(sets)} WHERE id = ?", params)
+        except sqlite3.IntegrityError as exc:
+            raise ValueError("Another label already uses that name.") from exc
+        row = conn.execute("SELECT * FROM labels WHERE id = ?", (label_id,)).fetchone()
+    return dict(row) if row else None
+
+
+def delete_label(label_id: int) -> bool:
+    with _conn() as conn:
+        cur = conn.execute("DELETE FROM labels WHERE id = ?", (label_id,))
+    return cur.rowcount > 0
+
+
+# ------------------------------------------------------------ complaints ----
+
+def save_complaint(record: dict[str, Any]) -> int:
+    with _conn() as conn:
+        cur = conn.execute(
+            """INSERT INTO complaints
+               (original_text, translated_text, source_lang, was_translated,
+                predicted_label, confidence, scores_json, engine, took_ms, created_at)
+               VALUES (?,?,?,?,?,?,?,?,?,?)""",
+            (
+                record["original_text"],
+                record["translated_text"],
+                record["source_lang"],
+                int(record["was_translated"]),
+                record["predicted_label"],
+                float(record["confidence"]),
+                json.dumps(record.get("scores", [])),
+                record.get("engine", ""),
+                int(record.get("took_ms", 0)),
+                _now(),
+            ),
+        )
+    return int(cur.lastrowid)
+
+
+def list_complaints(limit: int = 100, label: str | None = None) -> list[dict[str, Any]]:
+    sql = "SELECT * FROM complaints"
+    params: list[Any] = []
+    if label:
+        sql += " WHERE predicted_label = ?"
+        params.append(label)
+    sql += " ORDER BY id DESC LIMIT ?"
+    params.append(limit)
+
+    with _conn() as conn:
+        rows = [dict(r) for r in conn.execute(sql, params)]
+    for r in rows:
+        r["scores"] = json.loads(r.pop("scores_json") or "[]")
+        r["was_translated"] = bool(r["was_translated"])
+    return rows
+
+
+def label_counts() -> list[dict[str, Any]]:
+    with _conn() as conn:
+        rows = conn.execute(
+            "SELECT predicted_label AS label, COUNT(*) AS count "
+            "FROM complaints GROUP BY predicted_label ORDER BY count DESC"
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def clear_complaints() -> int:
+    with _conn() as conn:
+        cur = conn.execute("DELETE FROM complaints")
+    return cur.rowcount

app/templates/base.html

@@ -0,0 +1,75 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{% block title %}Complaint Classifier{% endblock %}</title>
+  <meta name="description" content="Multilingual complaint classification with runtime-editable labels.">
+
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;600;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/static/css/style.css">
+  <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>&#128221;</text></svg>">
+</head>
+<body>
+
+<!-- gradient used by the confidence ring -->
+<svg width="0" height="0" style="position:absolute" aria-hidden="true">
+  <defs>
+    <linearGradient id="ringGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#6366f1"/>
+      <stop offset="55%" stop-color="#8b5cf6"/>
+      <stop offset="100%" stop-color="#a855f7"/>
+    </linearGradient>
+  </defs>
+</svg>
+
+<header class="topbar">
+  <div class="wrap topbar-inner">
+    <a class="brand" href="/">
+      <span class="brand-mark">CC</span>
+      <span>Complaint&nbsp;Classifier</span>
+    </a>
+
+    <nav class="nav">
+      <a href="/" class="{{ 'active' if page == 'classify' }}">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>
+        Classify
+      </a>
+      <a href="/labels" class="{{ 'active' if page == 'labels' }}">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20.59 13.41l-7.17 7.17a2 2 0 0 1-2.83 0L2 12V2h10l8.59 8.59a2 2 0 0 1 0 2.82z"/><line x1="7" y1="7" x2="7.01" y2="7"/></svg>
+        Labels
+      </a>
+      <a href="/history" class="{{ 'active' if page == 'history' }}">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/></svg>
+        History
+      </a>
+      <a href="/docs" target="_blank" rel="noopener">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>
+        API
+      </a>
+    </nav>
+
+    <div class="model-status" id="modelStatus" title="Model status">
+      <span class="dot dot-idle"></span><span class="model-status-text">checking…</span>
+    </div>
+  </div>
+</header>
+
+<main class="wrap page">
+  {% block content %}{% endblock %}
+</main>
+
+<footer class="wrap foot">
+  Language detected offline, translated with Google Translate, classified by a small
+  zero-shot NLI model.
+  <span class="sep">·</span>
+  Labels are editable at runtime — no retraining.
+</footer>
+
+<div id="toast" class="toast" role="status" aria-live="polite"></div>
+<script src="/static/js/app.js"></script>
+{% block scripts %}{% endblock %}
+</body>
+</html>

app/templates/history.html

@@ -0,0 +1,103 @@
+{% extends "base.html" %}
+{% block title %}History{% endblock %}
+
+{% block content %}
+<div class="hero">
+  <h1>Classified <span class="grad">complaints</span></h1>
+  <p>Everything the classifier has processed, with the language it came in and the
+     English text the model actually scored.</p>
+</div>
+
+{% if counts %}
+{% set total = counts|sum(attribute='count') %}
+<section class="card">
+  <div class="row-between">
+    <h2 style="margin:0">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="20" x2="18" y2="10"/><line x1="12" y1="20" x2="12" y2="4"/><line x1="6" y1="20" x2="6" y2="14"/></svg>
+      Breakdown <span class="badge">{{ total }}</span>
+    </h2>
+    <button class="btn btn-sm btn-danger" id="btnClearHistory">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6"/></svg>
+      Clear history
+    </button>
+  </div>
+
+  <div class="stats">
+    {% for c in counts %}
+    <div class="stat" style="--h: {{ c.label|hue }}">
+      <div class="stat-top">
+        <span class="stat-label">{{ c.label }}</span>
+        <span class="stat-count">{{ c.count }}</span>
+      </div>
+      <div class="bar"><span style="width: {{ (100 * c.count / total)|round(1) }}%"></span></div>
+    </div>
+    {% endfor %}
+  </div>
+</section>
+{% endif %}
+
+<section class="card">
+  {% if complaints %}
+  <div class="filter-row">
+    <div class="search-wrap">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg>
+      <input type="search" id="filter" placeholder="Filter by text or label…">
+    </div>
+    <span class="muted small" id="filterCount">{{ complaints|length }} most recent</span>
+  </div>
+
+  <div class="table-scroll">
+    <table class="table history">
+      <thead>
+        <tr>
+          <th style="width:52px">#</th>
+          <th style="width:180px">Category</th>
+          <th style="width:88px">Conf.</th>
+          <th style="width:96px">Lang</th>
+          <th>Complaint</th>
+          <th style="width:150px">When <span style="opacity:.6">(UTC)</span></th>
+        </tr>
+      </thead>
+      <tbody>
+        {% for c in complaints %}
+        <tr>
+          <td class="mono muted">{{ c.id }}</td>
+          <td><span class="pill" style="--h: {{ c.predicted_label|hue }}">{{ c.predicted_label }}</span></td>
+          <td>
+            <span class="conf-cell">
+              <span class="conf-dot {{ 'low' if c.confidence < 0.35 }}"></span>
+              <span class="mono">{{ '%.2f'|format(c.confidence) }}</span>
+            </span>
+          </td>
+          <td>
+            <span class="lang">{{ c.source_lang }}</span>
+            {% if c.was_translated %}<span class="tag" title="Translated to English">EN</span>{% endif %}
+          </td>
+          <td>
+            <div class="c-orig">{{ c.original_text }}</div>
+            {% if c.was_translated %}<div class="c-trans">{{ c.translated_text }}</div>{% endif %}
+          </td>
+          <td class="mono muted small">{{ c.created_at.replace('T', ' ')[:16] }}</td>
+        </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  </div>
+
+  {% else %}
+  <div class="empty">
+    <div class="empty-icon">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/></svg>
+    </div>
+    <strong>No complaints yet</strong>
+    <p>Once you classify something it shows up here with its language, translation and score.</p>
+    <a class="btn btn-primary" href="/" style="margin-top:18px">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 3l14 9-14 9V3z"/></svg>
+      Submit one
+    </a>
+  </div>
+  {% endif %}
+</section>
+{% endblock %}
+
+{% block scripts %}<script src="/static/js/history.js"></script>{% endblock %}

app/templates/index.html

@@ -0,0 +1,144 @@
+{% extends "base.html" %}
+{% block title %}Classify a complaint{% endblock %}
+
+{% block content %}
+<div class="hero">
+  <h1>Turn any complaint into a <span class="grad">problem type</span></h1>
+  <p>Write in any language. The text is detected, translated to English, then scored
+     against your active labels in real time.</p>
+</div>
+
+<div class="grid-2">
+  <!-- ------------------------------------------------------------ input -->
+  <section class="card">
+    <h2>
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 20h9"/><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4z"/></svg>
+      Submit a complaint
+    </h2>
+    <p class="sub">Sinhala, Tamil, Hindi, English — anything Google Translate supports.</p>
+
+    <textarea id="complaint" rows="7" spellcheck="false"
+      placeholder="අපේ ගමේ දින තුනක් තිස්සේ වතුර නැහැ&#10;Hamare area me 3 din se bijli nahi hai&#10;The street light near the bus stand is broken"></textarea>
+
+    <div class="samples">
+      <span class="samples-label">Try</span>
+      <button class="chip" data-sample="අපේ ගමේ දින තුනක් තිස්සේ වතුර නැහැ. කරුණාකර බලන්න."><span class="flag">🇱🇰</span> Sinhala · water</button>
+      <button class="chip" data-sample="எங்கள் பகுதியில் மூன்று நாட்களாக மின்சாரம் இல்லை"><span class="flag">🇱🇰</span> Tamil · power</button>
+      <button class="chip" data-sample="हमारे मोहल्ले में कचरा एक हफ्ते से नहीं उठाया गया है"><span class="flag">🇮🇳</span> Hindi · waste</button>
+      <button class="chip" data-sample="There is a huge pothole on the main road and it is causing accidents."><span class="flag">🇬🇧</span> English · road</button>
+    </div>
+
+    <div class="options">
+      <label class="check"><input type="checkbox" id="optTranslate" checked> Translate first</label>
+      <label class="check"><input type="checkbox" id="optMulti"> Multi-label</label>
+      <label class="check"><input type="checkbox" id="optSave" checked> Save to history</label>
+      <label class="range" title="Below this score the result is flagged low-confidence">
+        Threshold
+        <input type="range" id="optThreshold" min="0" max="0.9" step="0.05" value="{{ threshold }}">
+        <output id="thrOut">{{ '%.2f'|format(threshold) }}</output>
+      </label>
+    </div>
+
+    <div class="actions">
+      <button id="btnClassify" class="btn btn-primary">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 3l14 9-14 9V3z"/></svg>
+        Classify
+      </button>
+      <button id="btnClear" class="btn btn-ghost">Clear</button>
+      <span id="spin" class="spinner hidden"></span>
+      <span class="muted small" style="margin-left:auto">⌘/Ctrl + ↵</span>
+    </div>
+  </section>
+
+  <!-- ----------------------------------------------------------- result -->
+  <section class="card" id="resultCard">
+    <h2>
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><polyline points="22 4 12 14.01 9 11.01"/></svg>
+      Result
+    </h2>
+
+    <div id="resultEmpty" class="empty">
+      <div class="empty-icon">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg>
+      </div>
+      <strong>Nothing classified yet</strong>
+      <p>Submit a complaint and the category, detected language, translation and every
+         label score appear here.</p>
+    </div>
+
+    <div id="result" class="hidden">
+      <div class="verdict">
+        <div class="verdict-main">
+          <div class="verdict-eyebrow">Predicted category</div>
+          <div class="verdict-label" id="rLabel">—</div>
+        </div>
+        <div class="ring" id="rRing">
+          <svg viewBox="0 0 80 80">
+            <circle class="ring-bg" cx="40" cy="40" r="37"/>
+            <circle class="ring-fg" cx="40" cy="40" r="37"/>
+          </svg>
+          <div class="ring-val" id="rConf">—</div>
+        </div>
+      </div>
+
+      <div id="rWarn" class="warn hidden">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>
+        <span id="rWarnText"></span>
+      </div>
+
+      <div class="kv">
+        <div><div class="kv-k">Language</div><div class="kv-v" id="rLang">—</div></div>
+        <div><div class="kv-k">Latency</div><div class="kv-v" id="rTime">—</div></div>
+        <div><div class="kv-k">Engine</div><div class="kv-v mono" id="rEngine" style="font-size:11.5px">—</div></div>
+      </div>
+
+      <details id="rTransBox" class="trans">
+        <summary>Original &amp; translation</summary>
+        <div class="trans-body">
+          <div class="q-label">Original</div>
+          <p id="rOriginal" class="quote"></p>
+          <div class="q-label">English</div>
+          <p id="rTranslated" class="quote"></p>
+          <p id="rNote" class="note hidden"></p>
+        </div>
+      </details>
+
+      <h3>All label scores</h3>
+      <div id="rScores" class="scores"></div>
+    </div>
+  </section>
+</div>
+
+<!-- ------------------------------------------------------- active labels -->
+<section class="card">
+  <div class="row-between">
+    <h2 style="margin:0">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20.59 13.41l-7.17 7.17a2 2 0 0 1-2.83 0L2 12V2h10l8.59 8.59a2 2 0 0 1 0 2.82z"/><line x1="7" y1="7" x2="7.01" y2="7"/></svg>
+      Active labels <span class="badge" id="labelCount">{{ labels|length }}</span>
+    </h2>
+    <a class="btn btn-sm" href="/labels">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 20h9"/><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4z"/></svg>
+      Edit labels
+    </a>
+  </div>
+
+  {% if labels %}
+  <div class="label-strip">
+    {% for l in labels %}
+      <span class="pill" style="--h: {{ l.name|hue }}" title="{{ l.description }}">{{ l.name }}</span>
+    {% endfor %}
+  </div>
+  <p class="muted small" style="margin:0">
+    Anything you change on the Labels page applies to the very next classification —
+    the model scores against whatever is active at request time.
+  </p>
+  {% else %}
+  <div class="warn" style="margin-top:4px">
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>
+    <span>No active labels yet — <a href="/labels">add one</a> before classifying.</span>
+  </div>
+  {% endif %}
+</section>
+{% endblock %}
+
+{% block scripts %}<script src="/static/js/classify.js"></script>{% endblock %}

app/templates/labels.html

@@ -0,0 +1,94 @@
+{% extends "base.html" %}
+{% block title %}Labels{% endblock %}
+
+{% block content %}
+<div class="hero">
+  <h1>Classification <span class="grad">labels</span></h1>
+  <p>The categories the model chooses between. Classification is zero-shot, so anything
+     you add here works on the next complaint — no retraining, no restart.</p>
+</div>
+
+<section class="card">
+  <h2>
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/></svg>
+    Add a label
+  </h2>
+  <p class="sub">
+    The name is what the model matches against, so keep it a short, plain category.
+    The description is a keyword hint layered on top — list the concrete phrases your
+    complainants actually use and it will break ties the model gets wrong.
+  </p>
+
+  <form id="addForm" class="add-form">
+    <div class="field">
+      <label for="newName">Label name</label>
+      <input id="newName" type="text" maxlength="80" required placeholder="Street Lighting">
+    </div>
+    <div class="field">
+      <label for="newDesc">Description / example phrases</label>
+      <input id="newDesc" type="text" maxlength="500"
+             placeholder="broken street light, dark road at night, lamp post not working">
+    </div>
+    <button class="btn btn-primary" type="submit">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/></svg>
+      Add label
+    </button>
+  </form>
+</section>
+
+<section class="card">
+  <div class="row-between">
+    <h2 style="margin:0">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="8" y1="6" x2="21" y2="6"/><line x1="8" y1="12" x2="21" y2="12"/><line x1="8" y1="18" x2="21" y2="18"/><line x1="3" y1="6" x2="3.01" y2="6"/><line x1="3" y1="12" x2="3.01" y2="12"/><line x1="3" y1="18" x2="3.01" y2="18"/></svg>
+      Configured labels <span class="badge" id="count">{{ labels|length }}</span>
+    </h2>
+    <span class="muted small">Edit inline, press ↵ or Save. Toggle off to exclude without deleting.</span>
+  </div>
+
+  <div class="table-scroll">
+    <table class="table" id="labelTable">
+      <thead>
+        <tr>
+          <th style="width:24%">Name</th>
+          <th>Description / example phrases</th>
+          <th style="width:80px" class="center">Active</th>
+          <th style="width:145px"></th>
+        </tr>
+      </thead>
+      <tbody>
+        {% for l in labels %}
+        <tr data-id="{{ l.id }}" style="--h: {{ l.name|hue }}">
+          <td><input class="cell-input name" value="{{ l.name }}" maxlength="80"></td>
+          <td><input class="cell-input desc" value="{{ l.description }}" maxlength="500"
+                     placeholder="example phrases help the zero-shot model"></td>
+          <td class="center">
+            <label class="switch">
+              <input type="checkbox" class="active" {% if l.active %}checked{% endif %}>
+              <span class="slider"></span>
+            </label>
+          </td>
+          <td class="right">
+            <button class="btn btn-sm save">Save</button>
+            <button class="btn btn-sm btn-danger del" title="Delete label">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="3 6 5 6 21 6"/><path d="M19 6l-1 14a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2L5 6m3 0V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/></svg>
+            </button>
+          </td>
+        </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  </div>
+
+  {% if not labels %}
+  <div class="empty" id="emptyLabels">
+    <div class="empty-icon">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M20.59 13.41l-7.17 7.17a2 2 0 0 1-2.83 0L2 12V2h10l8.59 8.59a2 2 0 0 1 0 2.82z"/><line x1="7" y1="7" x2="7.01" y2="7"/></svg>
+    </div>
+    <strong>No labels yet</strong>
+    <p>Add your first category above — the classifier needs at least one.</p>
+  </div>
+  {% endif %}
+</section>
+{% endblock %}
+
+{% block scripts %}<script src="/static/js/labels.js"></script>{% endblock %}

app/translator.py

@@ -0,0 +1,194 @@
+"""Language detection + translation to English.
+
+Detection uses `langdetect` (offline, instant). Translation uses
+`deep-translator`'s Google Translate backend, which needs network access.
+Every failure degrades gracefully: the original text is passed through so a
+complaint is never lost just because translation was unavailable.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, asdict
+from typing import Any
+
+from .config import TRANSLATE_ENABLED
+
+log = logging.getLogger("translator")
+
+try:
+    from langdetect import DetectorFactory, LangDetectException, detect_langs
+
+    DetectorFactory.seed = 0  # make detection deterministic
+    _LANGDETECT_OK = True
+except Exception:  # pragma: no cover - dependency missing
+    _LANGDETECT_OK = False
+    LangDetectException = Exception  # type: ignore[misc,assignment]
+
+try:
+    from deep_translator import GoogleTranslator
+
+    _TRANSLATOR_OK = True
+except Exception:  # pragma: no cover - dependency missing
+    _TRANSLATOR_OK = False
+
+# Google Translate rejects payloads above ~5000 characters.
+MAX_CHARS = 4800
+
+LANG_NAMES = {
+    "en": "English", "si": "Sinhala", "ta": "Tamil", "hi": "Hindi", "ur": "Urdu",
+    "ar": "Arabic", "bn": "Bengali", "ml": "Malayalam", "te": "Telugu", "kn": "Kannada",
+    "mr": "Marathi", "gu": "Gujarati", "pa": "Punjabi", "ne": "Nepali", "es": "Spanish",
+    "fr": "French", "de": "German", "pt": "Portuguese", "ru": "Russian", "zh-cn": "Chinese",
+    "ja": "Japanese", "ko": "Korean", "id": "Indonesian", "th": "Thai", "vi": "Vietnamese",
+    "tr": "Turkish", "it": "Italian", "nl": "Dutch", "fa": "Persian", "sw": "Swahili",
+}
+
+
+def language_name(code: str) -> str:
+    return LANG_NAMES.get((code or "").lower(), (code or "unknown").upper())
+
+
+# --------------------------------------------------------- script detection --
+# langdetect only covers 55 languages -- Sinhala is not among them, and it is
+# shaky on short text. Unicode-block detection is exact for non-Latin scripts,
+# so it runs alongside langdetect and wins whenever the two disagree about
+# which script the text is even written in.
+#
+# (start, end, default_lang, other langdetect langs using the same script)
+_SCRIPTS: list[tuple[int, int, str, frozenset[str]]] = [
+    (0x0D80, 0x0DFF, "si", frozenset()),                       # Sinhala
+    (0x0B80, 0x0BFF, "ta", frozenset({"ta"})),                 # Tamil
+    (0x0900, 0x097F, "hi", frozenset({"hi", "mr", "ne"})),     # Devanagari
+    (0x0980, 0x09FF, "bn", frozenset({"bn"})),                 # Bengali
+    (0x0A00, 0x0A7F, "pa", frozenset({"pa"})),                 # Gurmukhi
+    (0x0A80, 0x0AFF, "gu", frozenset({"gu"})),                 # Gujarati
+    (0x0B00, 0x0B7F, "or", frozenset()),                       # Odia
+    (0x0C00, 0x0C7F, "te", frozenset({"te"})),                 # Telugu
+    (0x0C80, 0x0CFF, "kn", frozenset({"kn"})),                 # Kannada
+    (0x0D00, 0x0D7F, "ml", frozenset({"ml"})),                 # Malayalam
+    (0x0E00, 0x0E7F, "th", frozenset({"th"})),                 # Thai
+    (0x0600, 0x06FF, "ar", frozenset({"ar", "fa", "ur"})),     # Arabic
+    (0x0590, 0x05FF, "he", frozenset({"he"})),                 # Hebrew
+    (0x0370, 0x03FF, "el", frozenset({"el"})),                 # Greek
+    (0x0400, 0x04FF, "ru", frozenset({"ru", "uk", "bg", "mk"})),  # Cyrillic
+    (0x1200, 0x137F, "am", frozenset()),                       # Ethiopic
+    (0x1780, 0x17FF, "km", frozenset()),                       # Khmer
+    (0x1000, 0x109F, "my", frozenset()),                       # Myanmar
+    (0x3040, 0x30FF, "ja", frozenset({"ja"})),                 # Kana
+    (0xAC00, 0xD7AF, "ko", frozenset({"ko"})),                 # Hangul
+    (0x4E00, 0x9FFF, "zh-cn", frozenset({"zh-cn", "zh-tw", "ja"})),  # CJK
+]
+
+# A script must cover this share of the letters before we trust it.
+_SCRIPT_MIN_SHARE = 0.25
+
+
+def detect_script(text: str) -> tuple[str, float, frozenset[str]] | None:
+    """Dominant non-Latin script as (default_lang, share, sibling_langs)."""
+    letters = [c for c in text if c.isalpha()]
+    if not letters:
+        return None
+
+    counts: dict[int, int] = {}
+    for ch in letters:
+        cp = ord(ch)
+        for idx, (lo, hi, _, _) in enumerate(_SCRIPTS):
+            if lo <= cp <= hi:
+                counts[idx] = counts.get(idx, 0) + 1
+                break
+
+    if not counts:
+        return None  # pure Latin (or unmapped) -- leave it to langdetect
+    idx, hits = max(counts.items(), key=lambda kv: kv[1])
+    share = hits / len(letters)
+    if share < _SCRIPT_MIN_SHARE:
+        return None
+    _, _, default_lang, siblings = _SCRIPTS[idx]
+    return default_lang, share, siblings
+
+
+@dataclass
+class TranslationResult:
+    original_text: str
+    text: str                 # English text handed to the classifier
+    source_lang: str          # ISO code, or "unknown"
+    source_lang_name: str
+    confidence: float         # detector confidence, 0..1
+    was_translated: bool
+    note: str = ""            # populated when something degraded
+
+    def dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def detect_language(text: str) -> tuple[str, float]:
+    """Return (iso_code, confidence). ("unknown", 0.0) when undetectable."""
+    text = (text or "").strip()
+    if not text:
+        return "unknown", 0.0
+
+    lang, conf = "unknown", 0.0
+    if _LANGDETECT_OK:
+        try:
+            best = detect_langs(text)[0]
+            lang, conf = best.lang, float(best.prob)
+        except (LangDetectException, IndexError):
+            pass
+
+    script = detect_script(text)
+    if script is None:
+        return lang, conf  # Latin script -- langdetect is the only signal
+
+    default_lang, share, siblings = script
+    if lang in siblings:
+        # langdetect agrees on the script and is more specific (mr vs hi, ur vs ar).
+        return lang, conf
+    # langdetect is wrong about the script, or has no profile for it (Sinhala).
+    return default_lang, round(share, 4)
+
+
+def to_english(text: str) -> TranslationResult:
+    """Detect the language of `text` and translate it to English when needed."""
+    text = (text or "").strip()
+    lang, conf = detect_language(text)
+    name = language_name(lang)
+
+    if not text:
+        return TranslationResult(text, "", lang, name, conf, False, "Empty input.")
+
+    # Confidently English already -- skip the network round trip.
+    if lang == "en" and conf >= 0.90:
+        return TranslationResult(text, text, "en", "English", conf, False)
+
+    if not TRANSLATE_ENABLED:
+        return TranslationResult(text, text, lang, name, conf, False,
+                                 "Translation disabled by configuration.")
+
+    if not _TRANSLATOR_OK:
+        return TranslationResult(text, text, lang, name, conf, False,
+                                 "deep-translator not installed; classified as-is.")
+
+    payload = text[:MAX_CHARS]
+    try:
+        # source="auto" lets Google do its own detection, which beats langdetect
+        # on short or romanised text.
+        translated = GoogleTranslator(source="auto", target="en").translate(payload)
+    except Exception as exc:  # network down, rate limited, etc.
+        log.warning("Translation failed (%s); using original text.", exc)
+        return TranslationResult(text, text, lang, name, conf, False,
+                                 f"Translation unavailable ({type(exc).__name__}); classified in original language.")
+
+    if not translated or not translated.strip():
+        return TranslationResult(text, text, lang, name, conf, False,
+                                 "Translator returned nothing; classified as-is.")
+
+    translated = translated.strip()
+    truncated = " (input truncated for translation)" if len(text) > MAX_CHARS else ""
+    changed = translated.lower() != text.lower()
+
+    if not changed:
+        return TranslationResult(text, translated, lang if lang != "unknown" else "en",
+                                 language_name(lang if lang != "unknown" else "en"),
+                                 conf, False, "Text was already English." + truncated)
+
+    return TranslationResult(text, translated, lang, name, conf, True, truncated.strip())

requirements.txt

@@ -1,6 +1,21 @@
-fastapi
-requests
-uvicorn
-pydantic
-pandas
-aiohttp
+# --- web ---
+fastapi>=0.115
+uvicorn[standard]>=0.30
+jinja2>=3.1
+python-multipart>=0.0.9
+pydantic>=2.7
+
+# --- language detection + translation ---
+langdetect>=1.0.9
+deep-translator>=1.11.4
+
+# --- zero-shot text classification (small NLI model) ---
+# transformers 4.x and 5.x both work.
+transformers>=4.40
+torch>=2.2
+
+# Tokeniser backend for DeBERTa-v3 style models. Not needed by the default
+# MODEL_NAME, but required if you switch to one -- without these the pipeline
+# cannot build its tokenizer and the app silently drops to the keyword fallback.
+sentencepiece>=0.2
+protobuf>=4.25

run.bat

@@ -0,0 +1,3 @@
+@echo off
+REM Start the complaint classifier on http://127.0.0.1:8000
+python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

run.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Start the complaint classifier on http://127.0.0.1:8000
+python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

scripts/bench.py

@@ -0,0 +1,124 @@
+"""Benchmark the zero-shot classifier against a small labelled set.
+
+Run from the project root:
+
+    python scripts/bench.py                       # current MODEL_NAME
+    python scripts/bench.py MoritzLaurer/deberta-v3-xsmall-zeroshot-v1.1-all-33
+
+Prints accuracy for a sweep of LEXICAL_WEIGHT values and hypothesis templates,
+so config changes are made on evidence rather than vibes. The cases are the
+English text as it would arrive *after* translation, since that is what the
+model actually sees.
+
+The weight sweep runs the model ONCE per case and re-blends the cached scores:
+LEXICAL_WEIGHT only affects the blend, never the model, so re-running inference
+per weight would just burn time for identical numbers.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
+
+from app import classifier                      # noqa: E402
+from app.config import DEFAULT_LABELS           # noqa: E402
+
+LABELS = [{"name": n, "description": d} for n, d in DEFAULT_LABELS]
+
+CASES: list[tuple[str, str]] = [
+    ("There is no water in our village for three days", "Water Supply"),
+    ("The water coming from the tap is muddy and smells bad", "Water Supply"),
+    ("A main pipe has burst and water is flooding the street", "Water Supply"),
+    ("Our area has been without electricity for three days", "Electricity"),
+    ("The transformer near our house is damaged and sparking", "Electricity"),
+    ("Voltage keeps fluctuating and our appliances are getting damaged", "Electricity"),
+    ("There is a huge pothole on the main road", "Road & Transport"),
+    ("The traffic signal at the junction is not working", "Road & Transport"),
+    ("The pavement is broken and people cannot walk safely", "Road & Transport"),
+    ("Garbage has not been collected in our locality for a week", "Waste & Sanitation"),
+    ("The drain is blocked and sewage is overflowing on the street", "Waste & Sanitation"),
+    ("The public bin is overflowing and smells terrible", "Waste & Sanitation"),
+    ("Mosquitoes are breeding in the stagnant water near the school", "Public Health"),
+    ("Stray dogs are attacking children in our neighbourhood", "Public Health"),
+    ("Construction noise starts at 5am every day and nobody can sleep", "Noise & Pollution"),
+    ("A factory is releasing thick black smoke into the air", "Noise & Pollution"),
+    ("Someone is putting up an illegal building without permission", "Building & Property"),
+    ("The old building next door is cracked and looks unsafe", "Building & Property"),
+]
+
+CANDIDATES = [l["name"] for l in LABELS]
+
+
+def model_scores(template: str) -> tuple[list[list[tuple[str, float]]], int]:
+    """Raw model scores for every case under one hypothesis template."""
+    out, latencies = [], []
+    for text, _ in CASES:
+        started = time.perf_counter()
+        r = classifier._pipe(
+            text, candidate_labels=CANDIDATES,
+            hypothesis_template=template, multi_label=False,
+        )
+        latencies.append((time.perf_counter() - started) * 1000)
+        out.append(list(zip(r["labels"], [float(s) for s in r["scores"]])))
+    return out, int(sum(latencies) / len(latencies))
+
+
+def score(cached, weight, avg_ms, title) -> tuple[int, list[str]]:
+    hits, misses = 0, []
+    for (text, expected), raw in zip(CASES, cached):
+        blended = classifier._blend(list(raw), text, LABELS, weight)
+        blended.sort(key=lambda p: p[1], reverse=True)
+        got, conf = blended[0]
+        if got == expected:
+            hits += 1
+        else:
+            misses.append(f"      {expected:<20} -> {got:<20} ({conf:.2f})  {text[:46]}")
+    print(f"  {title:<44} {hits:>2}/{len(CASES)}  ({100 * hits / len(CASES):3.0f}%)  ~{avg_ms}ms")
+    return hits, misses
+
+
+def main() -> int:
+    if len(sys.argv) > 1:
+        classifier.MODEL_NAME = sys.argv[1]
+        classifier._state["model"] = sys.argv[1]
+
+    started = time.time()
+    state = classifier.load_model(force=True)
+    if state["status"] != "ready":
+        print("MODEL FAILED TO LOAD:\n", state["error"][:500])
+        return 1
+    print(f"\nmodel: {classifier._state['model']}   (loaded in {time.time() - started:.0f}s)\n")
+
+    default_template = "This complaint is about {}."
+    cached, avg_ms = model_scores(default_template)
+
+    print("LEXICAL_WEIGHT sweep  (model run once, blend re-applied)")
+    best = (-1, 0.0, [])
+    for weight in (0.0, 0.15, 0.25, 0.3, 0.4, 0.5, 0.6):
+        hits, misses = score(cached, weight, avg_ms, f"lexical_weight = {weight}")
+        if hits > best[0]:
+            best = (hits, weight, misses)
+
+    print(f"\n  best: lexical_weight={best[1]}  ->  {best[0]}/{len(CASES)}")
+    if best[2]:
+        print("  remaining misses:")
+        print("\n".join(best[2]))
+
+    print("\nhypothesis template sweep")
+    score(cached, best[1], avg_ms, f"{default_template!r}")
+    for template in (
+        "This is a complaint about {}.",
+        "The problem is {}.",
+        "This text is about {}.",
+    ):
+        c, ms = model_scores(template)
+        score(c, best[1], ms, f"{template!r}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())