Deploy standalone ML service

.dockerignore

@@ -0,0 +1,10 @@
+.git
+.gitignore
+.env
+.tmp
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+smoke_test.py
+deploy_to_hf_space.py

.env.example

@@ -0,0 +1,8 @@
+APP_NAME=Standalone Content Safety ML Service
+APP_VERSION=0.1.0
+API_PREFIX=/api/v1
+MODEL_ARTIFACT_PATH=./models/muril-balanced-30k-v1
+MODEL_VERSION=muril-balanced-30k-v1
+MODEL_MIN_SCORE=0.35
+MODEL_MAX_LENGTH=256
+CORS_ALLOW_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:5173,http://127.0.0.1:5173

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --upgrade pip
+RUN pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements.txt
+
+COPY app ./app
+COPY .env.example ./.env
+COPY models ./models
+COPY README.md ./README.md
+
+EXPOSE 8000
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,10 +1,57 @@
 ---
-title: Context Aware Safety Ml
-emoji: 🏆
+title: Context-Aware Safety ML API
+emoji: 🛡️
 colorFrom: blue
-colorTo: red
+colorTo: indigo
 sdk: docker
+app_port: 8000
 pinned: false
+license: mit
+short_description: Standalone multilingual safety inference API.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Standalone ML Service
+
+This folder contains a minimal ML-only inference API extracted from the larger project.
+
+It includes:
+
+- a FastAPI app for transformer inference
+- the local MuRIL checkpoint under `models/`
+- basic language detection and text normalization
+- CORS support for frontend clients
+- a smoke test for local verification
+- Docker metadata ready for Hugging Face Spaces
+
+## Run locally
+
+```powershell
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+Copy-Item .env.example .env
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+## Smoke test
+
+```powershell
+python smoke_test.py
+```
+
+## API
+
+- `GET /api/v1/health`
+- `POST /api/v1/moderate`
+
+## Deploy to Hugging Face Spaces
+
+Create a Docker Space and upload this folder:
+
+```powershell
+.\.venv\Scripts\python.exe standalone-ml-service\deploy_to_hf_space.py --repo-id your-username/your-space-name --token hf_xxx
+```
+
+Optional flags:
+
+- `--private`

app/__init__.py

@@ -0,0 +1 @@
+"""Standalone ML inference service package."""

app/config.py

@@ -0,0 +1,41 @@
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+ENV_FILE = Path(__file__).resolve().parents[1] / ".env"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=str(ENV_FILE),
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    app_name: str = "Standalone Content Safety ML Service"
+    app_version: str = "0.1.0"
+    api_prefix: str = "/api/v1"
+    model_artifact_path: str = "./models/muril-balanced-30k-v1"
+    model_version: str = "muril-balanced-30k-v1"
+    model_min_score: float = 0.35
+    model_max_length: int = 256
+    cors_allow_origins: list[str] = [
+        "http://localhost:3000",
+        "http://127.0.0.1:3000",
+        "http://localhost:5173",
+        "http://127.0.0.1:5173",
+    ]
+
+    @field_validator("cors_allow_origins", mode="before")
+    @classmethod
+    def _split_origins(cls, value):
+        if isinstance(value, str):
+            return [item.strip() for item in value.split(",") if item.strip()]
+        return value
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

app/language.py

@@ -0,0 +1,136 @@
+import unicodedata
+from collections import Counter
+
+from app.schemas import LanguageProfile, LanguageSignal, ScriptRatio
+
+
+class HeuristicLanguageDetector:
+    roman_hindi_markers = {
+        "hai",
+        "nahi",
+        "nahin",
+        "tum",
+        "aap",
+        "mera",
+        "meri",
+        "kya",
+        "kyu",
+        "kyun",
+        "mat",
+        "kar",
+        "kr",
+        "bhai",
+        "yaar",
+        "acha",
+        "accha",
+        "bakwas",
+        "bewakoof",
+    }
+
+    def detect(self, text: str) -> LanguageProfile:
+        script_counts = Counter()
+
+        for char in text:
+            script_name = self._script_name(char)
+            if script_name is not None:
+                script_counts[script_name] += 1
+
+        total = sum(script_counts.values())
+        scripts = []
+        if total:
+            scripts = [
+                ScriptRatio(name=name, ratio=round(count / total, 3))
+                for name, count in script_counts.most_common()
+            ]
+
+        lowered_tokens = {token.strip(".,!?;:()[]{}\"'").lower() for token in text.split()}
+        roman_hindi_hits = len(self.roman_hindi_markers.intersection(lowered_tokens))
+
+        has_latin = script_counts["latin"] > 0
+        has_devanagari = script_counts["devanagari"] > 0
+        has_other_indic = script_counts["indic_other"] > 0
+
+        if has_devanagari and has_latin:
+            return LanguageProfile(
+                primary_language="hinglish",
+                code_mixed=True,
+                scripts=scripts,
+                candidates=[
+                    LanguageSignal(name="hinglish", confidence=0.9),
+                    LanguageSignal(name="hindi", confidence=0.72),
+                    LanguageSignal(name="english", confidence=0.63),
+                ],
+            )
+
+        if has_devanagari:
+            return LanguageProfile(
+                primary_language="hindi",
+                code_mixed=False,
+                scripts=scripts,
+                candidates=[
+                    LanguageSignal(name="hindi", confidence=0.92),
+                    LanguageSignal(name="hinglish", confidence=0.28),
+                ],
+            )
+
+        if has_latin and roman_hindi_hits >= 2:
+            return LanguageProfile(
+                primary_language="hinglish",
+                code_mixed=True,
+                scripts=scripts,
+                candidates=[
+                    LanguageSignal(name="hinglish", confidence=0.82),
+                    LanguageSignal(name="english", confidence=0.58),
+                ],
+            )
+
+        if has_latin:
+            return LanguageProfile(
+                primary_language="english",
+                code_mixed=False,
+                scripts=scripts,
+                candidates=[
+                    LanguageSignal(name="english", confidence=0.9),
+                    LanguageSignal(name="hinglish", confidence=0.25),
+                ],
+            )
+
+        if has_other_indic:
+            return LanguageProfile(
+                primary_language="indic_other",
+                code_mixed=False,
+                scripts=scripts,
+                candidates=[LanguageSignal(name="indic_other", confidence=0.8)],
+            )
+
+        return LanguageProfile(
+            primary_language="unknown",
+            code_mixed=False,
+            scripts=scripts,
+            candidates=[LanguageSignal(name="unknown", confidence=0.4)],
+        )
+
+    def _script_name(self, char: str) -> str | None:
+        if not char.isalpha():
+            return None
+
+        name = unicodedata.name(char, "")
+        if "LATIN" in name:
+            return "latin"
+        if "DEVANAGARI" in name:
+            return "devanagari"
+        if any(
+            block in name
+            for block in (
+                "BENGALI",
+                "GURMUKHI",
+                "GUJARATI",
+                "ORIYA",
+                "TAMIL",
+                "TELUGU",
+                "KANNADA",
+                "MALAYALAM",
+            )
+        ):
+            return "indic_other"
+        return "other"

app/main.py

@@ -0,0 +1,97 @@
+from contextlib import asynccontextmanager
+from time import perf_counter
+
+from fastapi import APIRouter, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.config import get_settings
+from app.language import HeuristicLanguageDetector
+from app.model import TransformerModerationModel
+from app.normalization import TextNormalizer
+from app.schemas import HealthResponse, ModerateRequest, ModerateResponse
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    settings = get_settings()
+    model = TransformerModerationModel(
+        artifact_path=settings.model_artifact_path,
+        max_length=settings.model_max_length,
+        min_score=settings.model_min_score,
+    )
+    model.warmup()
+    app.state.model = model
+    app.state.normalizer = TextNormalizer()
+    app.state.language_detector = HeuristicLanguageDetector()
+    app.state.settings = settings
+    yield
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+    app = FastAPI(
+        title=settings.app_name,
+        version=settings.app_version,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        lifespan=lifespan,
+    )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_allow_origins,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    router = APIRouter(prefix=settings.api_prefix)
+
+    @router.get("/health", response_model=HealthResponse)
+    async def health() -> HealthResponse:
+        model = app.state.model
+        app_settings = app.state.settings
+        return HealthResponse(
+            status="ok",
+            model_backend=model.backend_name,
+            model_version=app_settings.model_version,
+            model_artifact_path=app_settings.model_artifact_path,
+            model_loaded=model.is_loaded,
+        )
+
+    @router.post("/moderate", response_model=ModerateResponse)
+    async def moderate(payload: ModerateRequest) -> ModerateResponse:
+        started_at = perf_counter()
+        normalizer = app.state.normalizer
+        detector = app.state.language_detector
+        model = app.state.model
+        settings = app.state.settings
+
+        normalized_text = normalizer.normalize(payload.text)
+        language = detector.detect(normalized_text)
+        categories = model.predict(normalized_text, payload.context)
+        latency_ms = round((perf_counter() - started_at) * 1000, 2)
+
+        return ModerateResponse(
+            normalized_text=normalized_text,
+            categories=categories,
+            language=language,
+            model_backend=model.backend_name,
+            model_version=settings.model_version,
+            latency_ms=latency_ms,
+        )
+
+    app.include_router(router)
+
+    @app.get("/", tags=["root"])
+    async def root():
+        return {
+            "service": settings.app_name,
+            "docs": "/docs",
+            "health": f"{settings.api_prefix}/health",
+            "moderate": f"{settings.api_prefix}/moderate",
+        }
+
+    return app
+
+
+app = create_app()

app/model.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cached_property
+
+from app.schemas import CategoryName, CategoryScore, ConversationTurn
+
+
+@dataclass
+class TransformerModerationModel:
+    artifact_path: str
+    max_length: int = 256
+    min_score: float = 0.35
+    backend_name: str = "transformer"
+
+    @cached_property
+    def tokenizer(self):
+        from transformers import AutoTokenizer
+
+        return AutoTokenizer.from_pretrained(self.artifact_path)
+
+    @cached_property
+    def model(self):
+        from transformers import AutoModelForSequenceClassification
+
+        return AutoModelForSequenceClassification.from_pretrained(self.artifact_path)
+
+    @property
+    def is_loaded(self) -> bool:
+        return "model" in self.__dict__ and "tokenizer" in self.__dict__
+
+    def warmup(self) -> None:
+        _ = self.tokenizer
+        _ = self.model
+
+    def predict(
+        self,
+        text: str,
+        context: list[ConversationTurn],
+    ) -> list[CategoryScore]:
+        import torch
+
+        packed_text = self._pack_input(text=text, context=context)
+        encoded = self.tokenizer(
+            packed_text,
+            truncation=True,
+            padding=False,
+            max_length=self.max_length,
+            return_tensors="pt",
+        )
+        with torch.no_grad():
+            logits = self.model(**encoded).logits[0]
+        probabilities = torch.sigmoid(logits).tolist()
+
+        results: list[CategoryScore] = []
+        id_to_label = getattr(self.model.config, "id2label", {})
+        for index, score in enumerate(probabilities):
+            label = id_to_label.get(index, str(index))
+            normalized_label = normalize_label(label)
+            if normalized_label is None or score < self.min_score:
+                continue
+            results.append(
+                CategoryScore(
+                    name=normalized_label,
+                    score=round(float(score), 4),
+                    source="transformer",
+                    rationale=f"Model logits crossed threshold for {normalized_label.value}.",
+                )
+            )
+        return sorted(results, key=lambda category: category.score, reverse=True)
+
+    def _pack_input(
+        self,
+        text: str,
+        context: list[ConversationTurn],
+    ) -> str:
+        turns = []
+        for offset, turn in enumerate(context[-5:], start=1):
+            turns.append(f"[TURN-{offset}] {turn.role.value}: {turn.text}")
+        turns.append(f"[CURRENT] user: {text}")
+        return "\n".join(turns)
+
+
+def normalize_label(label: str) -> CategoryName | None:
+    normalized = (
+        label.strip()
+        .lower()
+        .replace("-", "_")
+        .replace("/", "_")
+        .replace(" ", "_")
+    )
+    mapping = {
+        "harassment_or_insult": CategoryName.HARASSMENT_OR_INSULT,
+        "insult": CategoryName.HARASSMENT_OR_INSULT,
+        "harassment": CategoryName.HARASSMENT_OR_INSULT,
+        "toxic": CategoryName.HARASSMENT_OR_INSULT,
+        "severe_toxic": CategoryName.HARASSMENT_OR_INSULT,
+        "threat_or_violence": CategoryName.THREAT_OR_VIOLENCE,
+        "threat": CategoryName.THREAT_OR_VIOLENCE,
+        "violence": CategoryName.THREAT_OR_VIOLENCE,
+        "hate": CategoryName.HATE,
+        "identity_hate": CategoryName.HATE,
+        "self_harm": CategoryName.SELF_HARM,
+        "sexual_explicit": CategoryName.SEXUAL_EXPLICIT,
+        "sexual": CategoryName.SEXUAL_EXPLICIT,
+        "obscene": CategoryName.PROFANITY,
+        "profanity": CategoryName.PROFANITY,
+        "spam": CategoryName.SPAM,
+    }
+    return mapping.get(normalized)

app/normalization.py

@@ -0,0 +1,21 @@
+import re
+import unicodedata
+
+
+class TextNormalizer:
+    url_pattern = re.compile(r"https?://\S+|www\.\S+", re.IGNORECASE)
+    mention_pattern = re.compile(r"@\w+")
+    whitespace_pattern = re.compile(r"\s+")
+    repeated_latin_pattern = re.compile(r"([A-Za-z])\1{2,}")
+    zero_width_pattern = re.compile(r"[\u200b-\u200f\u2060\ufeff]")
+    repeated_punctuation_pattern = re.compile(r"([!?.,])\1{2,}")
+
+    def normalize(self, text: str) -> str:
+        normalized = unicodedata.normalize("NFKC", text).strip()
+        normalized = self.zero_width_pattern.sub("", normalized)
+        normalized = self.url_pattern.sub("<URL>", normalized)
+        normalized = self.mention_pattern.sub("<USER>", normalized)
+        normalized = self.repeated_latin_pattern.sub(r"\1\1", normalized)
+        normalized = self.repeated_punctuation_pattern.sub(r"\1\1", normalized)
+        normalized = self.whitespace_pattern.sub(" ", normalized)
+        return normalized

app/schemas.py

@@ -0,0 +1,72 @@
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class CategoryName(StrEnum):
+    HARASSMENT_OR_INSULT = "harassment_or_insult"
+    THREAT_OR_VIOLENCE = "threat_or_violence"
+    HATE = "hate"
+    SELF_HARM = "self_harm"
+    SEXUAL_EXPLICIT = "sexual_explicit"
+    PROFANITY = "profanity"
+    SPAM = "spam"
+
+
+class ConversationRole(StrEnum):
+    USER = "user"
+    ASSISTANT = "assistant"
+    MODERATOR = "moderator"
+    SYSTEM = "system"
+
+
+class ConversationTurn(BaseModel):
+    role: ConversationRole
+    text: str = Field(min_length=1, max_length=2000)
+    user_id: str | None = None
+
+
+class CategoryScore(BaseModel):
+    name: CategoryName
+    score: float = Field(ge=0.0, le=1.0)
+    source: str
+    rationale: str
+
+
+class ScriptRatio(BaseModel):
+    name: str
+    ratio: float = Field(ge=0.0, le=1.0)
+
+
+class LanguageSignal(BaseModel):
+    name: str
+    confidence: float = Field(ge=0.0, le=1.0)
+
+
+class LanguageProfile(BaseModel):
+    primary_language: str
+    code_mixed: bool
+    scripts: list[ScriptRatio] = Field(default_factory=list)
+    candidates: list[LanguageSignal] = Field(default_factory=list)
+
+
+class ModerateRequest(BaseModel):
+    text: str = Field(min_length=1, max_length=4000)
+    context: list[ConversationTurn] = Field(default_factory=list, max_length=10)
+
+
+class ModerateResponse(BaseModel):
+    normalized_text: str
+    categories: list[CategoryScore] = Field(default_factory=list)
+    language: LanguageProfile
+    model_backend: str
+    model_version: str
+    latency_ms: float = Field(ge=0.0)
+
+
+class HealthResponse(BaseModel):
+    status: str
+    model_backend: str
+    model_version: str
+    model_artifact_path: str
+    model_loaded: bool

deploy_to_hf_space.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from huggingface_hub import HfApi
+
+
+SPACE_DIR = Path(__file__).resolve().parent
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Deploy the standalone ML service to Hugging Face Spaces.")
+    parser.add_argument("--repo-id", required=True, help="Space repo id, for example: username/space-name")
+    parser.add_argument("--token", required=True, help="Hugging Face access token")
+    parser.add_argument("--private", action="store_true", help="Create the Space as private")
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    api = HfApi(token=args.token)
+
+    create_kwargs = {
+        "repo_id": args.repo_id,
+        "token": args.token,
+        "repo_type": "space",
+        "space_sdk": "docker",
+        "private": args.private,
+        "exist_ok": True,
+    }
+
+    api.create_repo(**create_kwargs)
+
+    ignore_patterns = [
+        ".env",
+        ".tmp/*",
+        "__pycache__/*",
+        "*.pyc",
+        "*.pyo",
+        "*.pyd",
+    ]
+
+    api.upload_folder(
+        repo_id=args.repo_id,
+        folder_path=str(SPACE_DIR),
+        repo_type="space",
+        token=args.token,
+        commit_message="Deploy standalone ML service",
+        ignore_patterns=ignore_patterns,
+    )
+
+    print(f"Deployment uploaded to https://huggingface.co/spaces/{args.repo_id}")
+
+
+if __name__ == "__main__":
+    main()

models/muril-balanced-30k-v1/config.json

@@ -0,0 +1,43 @@
+{
+  "_name_or_path": "google/muril-base-cased",
+  "architectures": [
+    "BertForSequenceClassification"
+  ],
+  "attention_probs_dropout_prob": 0.1,
+  "classifier_dropout": null,
+  "embedding_size": 768,
+  "hidden_act": "gelu",
+  "hidden_dropout_prob": 0.1,
+  "hidden_size": 768,
+  "id2label": {
+    "0": "toxic",
+    "1": "severe_toxic",
+    "2": "obscene",
+    "3": "threat",
+    "4": "insult",
+    "5": "identity_hate"
+  },
+  "initializer_range": 0.02,
+  "intermediate_size": 3072,
+  "label2id": {
+    "identity_hate": 5,
+    "insult": 4,
+    "obscene": 2,
+    "severe_toxic": 1,
+    "threat": 3,
+    "toxic": 0
+  },
+  "layer_norm_eps": 1e-12,
+  "max_position_embeddings": 512,
+  "model_type": "bert",
+  "num_attention_heads": 12,
+  "num_hidden_layers": 12,
+  "pad_token_id": 0,
+  "position_embedding_type": "absolute",
+  "problem_type": "multi_label_classification",
+  "torch_dtype": "float32",
+  "transformers_version": "4.40.0",
+  "type_vocab_size": 2,
+  "use_cache": true,
+  "vocab_size": 197285
+}

models/muril-balanced-30k-v1/model.safetensors

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

models/muril-balanced-30k-v1/special_tokens_map.json

@@ -0,0 +1,7 @@
+{
+  "cls_token": "[CLS]",
+  "mask_token": "[MASK]",
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "unk_token": "[UNK]"
+}

models/muril-balanced-30k-v1/tokenizer_config.json

@@ -0,0 +1,58 @@
+{
+  "added_tokens_decoder": {
+    "0": {
+      "content": "[PAD]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "100": {
+      "content": "[UNK]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "103": {
+      "content": "[MASK]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "104": {
+      "content": "[CLS]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "105": {
+      "content": "[SEP]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    }
+  },
+  "clean_up_tokenization_spaces": true,
+  "cls_token": "[CLS]",
+  "do_basic_tokenize": true,
+  "do_lower_case": false,
+  "lowercase": false,
+  "mask_token": "[MASK]",
+  "model_max_length": 512,
+  "never_split": null,
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "strip_accents": false,
+  "tokenize_chinese_chars": true,
+  "tokenizer_class": "BertTokenizer",
+  "unk_token": "[UNK]"
+}

requirements.txt

@@ -0,0 +1,9 @@
+fastapi==0.135.2
+uvicorn[standard]==0.42.0
+pydantic==2.12.5
+pydantic-settings==2.13.1
+httpx==0.28.1
+torch==2.5.1
+transformers==4.46.3
+sentencepiece==0.2.1
+safetensors==0.7.0

smoke_test.py

@@ -0,0 +1,38 @@
+import os
+from pathlib import Path
+
+from fastapi.testclient import TestClient
+
+
+def main() -> None:
+    project_root = Path(__file__).resolve().parent
+    os.environ["MODEL_ARTIFACT_PATH"] = str(project_root / "models" / "muril-balanced-30k-v1")
+
+    from app.config import get_settings
+    from app.main import create_app
+
+    get_settings.cache_clear()
+    app = create_app()
+
+    with TestClient(app) as client:
+        health = client.get("/api/v1/health")
+        assert health.status_code == 200, health.text
+
+        response = client.post(
+            "/api/v1/moderate",
+            json={
+                "text": "You are an idiot and I will hurt you",
+                "context": [],
+            },
+        )
+        assert response.status_code == 200, response.text
+        payload = response.json()
+        assert payload["model_backend"] == "transformer"
+        assert payload["normalized_text"]
+        assert payload["latency_ms"] >= 0
+
+    print("Standalone ML service smoke test passed.")
+
+
+if __name__ == "__main__":
+    main()