Deploy SafeChat ML service to Hugging Face Space

.dockerignore

@@ -1,10 +1,24 @@
-.git
-.gitignore
-.env
-.tmp
-__pycache__
+__pycache__/
 *.pyc
 *.pyo
 *.pyd
-smoke_test.py
-deploy_to_hf_space.py
+.env
+.env.*
+tests/
+training/
+downloads/
+venv_py310_detox/
+muril-base-local/
+MIXED_MODERATION_TEST_RESULTS.md
+pip_error.log
+train_log.txt
+train_trace.txt
+setup_and_train.ps1
+download_muril.py
+fix_transformers.py
+checkpoints/indicbart-base/
+checkpoints/indicbart-base-fresh/
+checkpoints/indicbart-detox/
+checkpoints/indicbart-detox-from-fresh-base/
+checkpoints/muril-toxicity-finetuned/
+checkpoints/muril-toxicity-finetuned/checkpoint-*/

Dockerfile

@@ -1,20 +1,37 @@
-FROM python:3.12-slim
+FROM python:3.11-slim
 
-ENV PYTHONDONTWRITEBYTECODE=1
-ENV PYTHONUNBUFFERED=1
-ENV PIP_NO_CACHE_DIR=1
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    HF_HOME=/tmp/huggingface \
+    TRANSFORMERS_CACHE=/tmp/huggingface/hub \
+    SAFECHAT_CLASSIFIER_MODEL=vineet88/safechat-muril-toxicity-finetuned \
+    SAFECHAT_DETOX_MODEL=ai4bharat/IndicBART \
+    SAFECHAT_USE_MODEL_DETOX=false
 
 WORKDIR /app
 
+# Install system dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first (Docker cache optimization)
 COPY requirements.txt .
-RUN pip install --upgrade pip
-RUN pip install --extra-index-url https://download.pytorch.org/whl/cpu -r requirements.txt
+RUN pip install --upgrade pip && pip install --no-cache-dir -r requirements.txt
 
+# Copy only the runtime payload used by the Space.
 COPY app ./app
-COPY .env.example ./.env
-COPY models ./models
-COPY README.md ./README.md
 
+# Create directories
+RUN mkdir -p /app/checkpoints /app/models /tmp/huggingface
+
+# Expose port
 EXPOSE 8000
 
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
+    CMD python -c "import httpx; r = httpx.get('http://localhost:8000/api/v1/health'); exit(0 if r.status_code == 200 else 1)"
+
+# Run with uvicorn (1 worker — models are loaded per worker)
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]

README.md

@@ -1,57 +1,35 @@
 ---
-title: Context-Aware Safety ML API
-emoji: 🛡️
+title: SafeChat ML Service
 colorFrom: blue
-colorTo: indigo
+colorTo: gray
 sdk: docker
 app_port: 8000
 pinned: false
-license: mit
-short_description: Standalone multilingual safety inference API.
 ---
 
-# Standalone ML Service
+# SafeChat ML Service
 
-This folder contains a minimal ML-only inference API extracted from the larger project.
+FastAPI-based toxicity classification and detoxification service for English, Hindi, and Hinglish.
 
-It includes:
+## What This Space Exposes
 
-- 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
+- `GET /` service metadata
+- `GET /docs` interactive API docs
+- `POST /api/v1/moderate` toxicity classification with polite suggestions
+- `POST /api/v1/moderate/batch` batch moderation
+- `POST /api/v1/detoxify` detoxification-only endpoint
+- `GET /api/v1/health` and `GET /api/v1/ready` health endpoints
 
-## Run locally
+## Model Setup
 
-```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
-```
+- Toxicity classifier: `vineet88/safechat-muril-toxicity-finetuned`
+- Detoxifier: template fallback enabled by default in the Space for faster startup on CPU
+- Optional detox model: `ai4bharat/IndicBART` can still be enabled by setting `SAFECHAT_USE_MODEL_DETOX=true`
 
-## Smoke test
+## Notes
 
-```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`
+- The Space is packaged as a Docker Space.
+- The container listens on port `8000`.
+- The root endpoint returns JSON. API docs are available at `/docs`.
+- The Space pulls the fine-tuned MuRIL checkpoint from a separate Hugging Face model repo at runtime.
+- The default Space configuration favors faster boot over heavy seq2seq model loading.

app/__init__.py

@@ -1 +1 @@
-"""Standalone ML inference service package."""
+# SafeChat ML Service

app/api/__init__.py

@@ -0,0 +1 @@
+# API package

app/api/dependencies.py

@@ -0,0 +1,22 @@
+"""
+SafeChat — FastAPI Dependencies
+
+Shared dependencies injected into API route handlers.
+"""
+
+from fastapi import Depends, HTTPException
+
+from app.models.model_manager import model_manager
+
+
+async def require_models_ready():
+    """
+    Dependency that ensures ML models are loaded before processing requests.
+    Raises 503 if models aren't ready yet.
+    """
+    if not model_manager.is_ready:
+        raise HTTPException(
+            status_code=503,
+            detail="ML models are still loading. Please try again in a moment.",
+        )
+    return model_manager

app/api/routes/__init__.py

@@ -0,0 +1 @@
+# API Routes package

app/api/routes/detoxify.py

@@ -0,0 +1,45 @@
+"""
+SafeChat — Detoxify API Route
+
+POST /api/v1/detoxify — Generate a polite alternative for toxic text
+"""
+
+from fastapi import APIRouter, HTTPException
+
+from app.models.model_manager import model_manager
+from app.schemas.moderation import DetoxifyRequest, DetoxifyResponse
+
+router = APIRouter(prefix="/api/v1", tags=["Detoxification"])
+
+
+@router.post("/detoxify", response_model=DetoxifyResponse)
+async def detoxify_text(request: DetoxifyRequest):
+    """
+    Generate a polite, non-toxic alternative for the given text.
+
+    Supports English, Hindi, and Hinglish (code-mixed) text.
+    Uses template-based suggestions (Phase 1) or model-based
+    generation (Phase 2, when enabled).
+    """
+    if not model_manager.is_ready:
+        raise HTTPException(status_code=503, detail="Models not loaded yet.")
+
+    detoxifier = model_manager.detoxifier
+    if not detoxifier:
+        raise HTTPException(status_code=503, detail="Detoxifier not available.")
+
+    try:
+        # First classify to know which category of toxicity
+        classification = model_manager.classifier.predict(request.text)
+
+        result = detoxifier.detoxify(
+            text=request.text,
+            toxicity_categories=classification["categories"],
+            target_language=request.target_language,
+            preserve_intent=request.preserve_intent,
+        )
+
+        return DetoxifyResponse(**result)
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Detoxification failed: {str(e)}")

app/api/routes/feedback.py

@@ -0,0 +1,47 @@
+"""
+SafeChat — Feedback API Route
+
+POST /api/v1/feedback       — Submit moderator feedback
+GET  /api/v1/feedback/stats — Get feedback statistics
+"""
+
+from fastapi import APIRouter, HTTPException
+
+from app.schemas.feedback import FeedbackRequest, FeedbackResponse, FeedbackStats
+from app.services.feedback_service import feedback_service
+
+router = APIRouter(prefix="/api/v1", tags=["Feedback & Continuous Learning"])
+
+
+@router.post("/feedback", response_model=FeedbackResponse)
+async def submit_feedback(request: FeedbackRequest):
+    """
+    Submit moderator feedback on a moderation decision.
+
+    This feedback is used for:
+      1. Tracking model accuracy over time
+      2. Collecting training data for model retraining
+      3. Triggering automatic retraining when threshold is reached
+    """
+    try:
+        result = await feedback_service.submit_feedback(request.model_dump())
+        return FeedbackResponse(**result)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to submit feedback: {str(e)}")
+
+
+@router.get("/feedback/stats", response_model=FeedbackStats)
+async def get_feedback_stats():
+    """
+    Get feedback statistics including model accuracy and retraining progress.
+
+    Shows:
+      - Total feedback count
+      - Model accuracy (correct / total)
+      - Progress toward next retraining trigger
+    """
+    try:
+        stats = await feedback_service.get_stats()
+        return FeedbackStats(**stats)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to get stats: {str(e)}")

app/api/routes/health.py

@@ -0,0 +1,46 @@
+"""
+SafeChat — Health Check API Route
+
+GET /api/v1/health — Service health with model status and GPU info
+"""
+
+import time
+from fastapi import APIRouter
+
+from app.config import settings
+from app.models.model_manager import model_manager
+
+router = APIRouter(prefix="/api/v1", tags=["Health"])
+
+_start_time = time.time()
+
+
+@router.get("/health")
+async def health_check():
+    """
+    Comprehensive health check including model status and GPU metrics.
+
+    Used by:
+      - Spring Boot backend to verify ML service availability
+      - Docker health checks
+      - Monitoring dashboards
+    """
+    health = model_manager.get_health()
+
+    return {
+        **health,
+        "service": settings.APP_NAME,
+        "version": settings.APP_VERSION,
+        "uptime_seconds": int(time.time() - _start_time),
+    }
+
+
+@router.get("/ready")
+async def readiness_check():
+    """
+    Readiness probe — returns 200 only when models are loaded and ready.
+    Used by Kubernetes / Docker for routing traffic.
+    """
+    if model_manager.is_ready:
+        return {"ready": True}
+    return {"ready": False, "detail": "Models still loading..."}

app/api/routes/moderation.py

@@ -0,0 +1,70 @@
+"""
+SafeChat — Moderation API Route
+
+POST /api/v1/moderate       — Moderate a single message
+POST /api/v1/moderate/batch — Moderate multiple messages
+"""
+
+import time
+from fastapi import APIRouter, HTTPException
+
+from app.models.model_manager import model_manager
+from app.schemas.moderation import (
+    ModerationRequest,
+    ModerationResponse,
+    BatchModerationRequest,
+    BatchModerationResponse,
+)
+from app.services.moderation_service import moderation_service
+
+router = APIRouter(prefix="/api/v1", tags=["Moderation"])
+
+
+@router.post("/moderate", response_model=ModerationResponse)
+async def moderate_message(request: ModerationRequest):
+    """
+    Classify a message for toxicity and suggest a polite alternative.
+
+    Returns toxicity scores across 6 categories, overall severity,
+    detected language, and a suggested rephrasing if the message is toxic.
+    """
+    if not model_manager.is_ready:
+        raise HTTPException(status_code=503, detail="Models not loaded yet. Please wait.")
+
+    try:
+        result = await moderation_service.moderate(
+            text=request.text,
+            context=request.context,
+            channel_id=request.channel_id,
+            user_id=request.user_id,
+        )
+        return result
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Moderation failed: {str(e)}")
+
+
+@router.post("/moderate/batch", response_model=BatchModerationResponse)
+async def moderate_batch(request: BatchModerationRequest):
+    """
+    Moderate multiple messages in a single request.
+    Max 50 messages per batch.
+    """
+    if not model_manager.is_ready:
+        raise HTTPException(status_code=503, detail="Models not loaded yet. Please wait.")
+
+    start_time = time.perf_counter()
+
+    try:
+        results = await moderation_service.moderate_batch(
+            texts=request.texts,
+            channel_id=request.channel_id,
+            user_id=request.user_id,
+        )
+        total_time = int((time.perf_counter() - start_time) * 1000)
+
+        return BatchModerationResponse(
+            results=results,
+            total_inference_time_ms=total_time,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Batch moderation failed: {str(e)}")

app/config.py

@@ -1,37 +1,86 @@
-from functools import lru_cache
+"""
+SafeChat ML Service — Configuration
+"""
+
 from pathlib import Path
+from pydantic_settings import BaseSettings
+import torch
+
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+DEFAULT_CHECKPOINT_DIR = BASE_DIR / "checkpoints"
+DEFAULT_CLASSIFIER_PATH = DEFAULT_CHECKPOINT_DIR / "muril-toxicity-finetuned"
+DEFAULT_DETOX_BASE_FRESH_PATH = DEFAULT_CHECKPOINT_DIR / "indicbart-base-fresh"
+DEFAULT_DETOX_BASE_PATH = DEFAULT_CHECKPOINT_DIR / "indicbart-base"
+DEFAULT_DETOX_FINAL_PATH = DEFAULT_CHECKPOINT_DIR / "indicbart-detox"
+DEFAULT_DETOX_CHECKPOINT_PATH = DEFAULT_DETOX_FINAL_PATH / "checkpoint-1000"
 
-from pydantic_settings import BaseSettings, SettingsConfigDict
 
-ENV_FILE = Path(__file__).resolve().parents[1] / ".env"
+def _prefer_local_checkpoint(local_paths: list[Path], fallback: str) -> str:
+    """Use the first available local checkpoint, otherwise fall back."""
+    for local_path in local_paths:
+        has_config = (local_path / "config.json").exists()
+        has_weights = (local_path / "model.safetensors").exists() or (local_path / "pytorch_model.bin").exists()
+        if has_config and has_weights:
+            return str(local_path)
+    return fallback
 
 
 class Settings(BaseSettings):
-    model_config = SettingsConfigDict(
-        env_file=str(ENV_FILE),
-        env_file_encoding="utf-8",
-        extra="ignore",
-    )
+    """Application settings with environment variable support."""
+
+    # ── App ──────────────────────────────────────────────
+    APP_NAME: str = "SafeChat ML Service (MuRIL & IndicBART)"
+    APP_VERSION: str = "2.0.0"
+    DEBUG: bool = True
+    HOST: str = "0.0.0.0"
+    PORT: int = 8000
 
-    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: str = (
-        "http://localhost:3000,"
-        "http://127.0.0.1:3000,"
-        "http://localhost:5173,"
-        "http://127.0.0.1:5173"
+    # ── Device ───────────────────────────────────────────
+    DEVICE: str = "cuda" if torch.cuda.is_available() else "cpu"
+
+    # ── Model Configuration ──────────────────────────────
+    # Prefer saved fine-tuned checkpoints when available.
+    CLASSIFIER_MODEL: str = _prefer_local_checkpoint(
+        [DEFAULT_CLASSIFIER_PATH],
+        "google/muril-base-cased",
+    )
+    
+    # Use the original downloaded IndicBART model for prompt-based detoxification.
+    DETOX_MODEL: str = _prefer_local_checkpoint(
+        [
+            DEFAULT_DETOX_BASE_FRESH_PATH,
+            DEFAULT_DETOX_BASE_PATH,
+            DEFAULT_DETOX_FINAL_PATH,
+            DEFAULT_DETOX_CHECKPOINT_PATH,
+        ],
+        "ai4bharat/IndicBART",
     )
+    DETOX_MAX_LENGTH: int = 128
+    DETOX_NUM_BEAMS: int = 4
+    USE_MODEL_DETOX: bool = True  # Enforce Model usage
+
+    # ── Inference Settings ───────────────────────────────
+    MAX_SEQ_LENGTH: int = 256
+    BATCH_SIZE: int = 8
+
+    # ── Severity Thresholds ──────────────────────────────
+    THRESHOLD_SAFE: float = 0.30
+    THRESHOLD_SAFE_HINGLISH: float = 0.18
+    THRESHOLD_LOW: float = 0.55
+    THRESHOLD_MEDIUM: float = 0.75
+
+    # ── MongoDB & Continuous Learning ──────────────────────
+    MONGODB_URL: str = "mongodb://localhost:27017"
+    MONGODB_DB: str = "safechat"
+    FEEDBACK_THRESHOLD_FOR_RETRAIN: int = 500
+    MODEL_CHECKPOINT_DIR: str = str(DEFAULT_CHECKPOINT_DIR)
 
-    @property
-    def cors_allow_origins_list(self) -> list[str]:
-        return [item.strip() for item in self.cors_allow_origins.split(",") if item.strip()]
+    class Config:
+        env_file = ".env"
+        env_prefix = "SAFECHAT_"
+        case_sensitive = True
 
 
-@lru_cache
-def get_settings() -> Settings:
-    return Settings()
+# Singleton settings instance
+settings = Settings()

app/main.py

@@ -1,97 +1,114 @@
+"""
+SafeChat ML Service — FastAPI Application
+
+Entry point for the ML inference service.
+Handles toxicity classification, detoxification, and feedback collection.
+
+Run with:
+    uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+
+Or for production:
+    gunicorn app.main:app -w 1 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
+    (Use 1 worker since models are loaded in-memory per worker)
+"""
+
 from contextlib import asynccontextmanager
-from time import perf_counter
 
-from fastapi import APIRouter, FastAPI
+from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from loguru import logger
+
+from app.config import settings
+from app.models.model_manager import model_manager
+
+# Import route modules
+from app.api.routes import moderation, detoxify, health, feedback
 
-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
 
+# ── Application Lifespan ───────────────────────────────────────────────
 
 @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_list,
-        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()
+    """
+    Startup: Load ML models into GPU memory.
+    Shutdown: Clean up resources.
+    """
+    # ── STARTUP ────────────────────────────────────────
+    logger.info("Starting SafeChat ML Service...")
+    await model_manager.initialize()
+    logger.success(f"SafeChat ML Service ready on {settings.HOST}:{settings.PORT}")
+
+    yield  # Application runs here
+
+    # ── SHUTDOWN ───────────────────────────────────────
+    logger.info("Shutting down SafeChat ML Service...")
+    # GPU memory cleanup
+    import torch
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+    logger.info("Cleanup complete. Goodbye!")
+
+
+# ── Create FastAPI Application ─────────────────────────────────────────
+
+app = FastAPI(
+    title=settings.APP_NAME,
+    version=settings.APP_VERSION,
+    description=(
+        "Real-time toxicity classification and detoxification service. "
+        "Supports English, Hindi, Hinglish (code-mixed), and Indian languages. "
+        "Features a language-aware ensemble classifier with continuous learning."
+    ),
+    docs_url="/docs",
+    redoc_url="/redoc",
+    lifespan=lifespan,
+)
+
+
+# ── CORS Middleware ────────────────────────────────────────────────────
+# Allow React frontend and Spring Boot backend to call this service
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:3000",    # React dev server
+        "http://localhost:5173",    # Vite dev server
+        "http://localhost:8080",    # Spring Boot
+        "http://127.0.0.1:3000",
+        "http://127.0.0.1:5173",
+        "http://127.0.0.1:8080",
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ── Register Routes ───────────────────────────────────────────────────
+
+app.include_router(moderation.router)
+app.include_router(detoxify.router)
+app.include_router(health.router)
+app.include_router(feedback.router)
+
+
+# ── Root Endpoint ─────────────────────────────────────────────────────
+
+@app.get("/", tags=["Root"])
+async def root():
+    """Service info and links to documentation."""
+    return {
+        "service": settings.APP_NAME,
+        "version": settings.APP_VERSION,
+        "docs": "/docs",
+        "health": "/api/v1/health",
+        "endpoints": {
+            "moderate": "POST /api/v1/moderate",
+            "moderate_batch": "POST /api/v1/moderate/batch",
+            "detoxify": "POST /api/v1/detoxify",
+            "feedback": "POST /api/v1/feedback",
+            "feedback_stats": "GET /api/v1/feedback/stats",
+            "health": "GET /api/v1/health",
+            "ready": "GET /api/v1/ready",
+        },
+    }

app/models/__init__.py

@@ -0,0 +1 @@
+# Models package

app/models/detoxifier.py

@@ -0,0 +1,359 @@
+"""
+SafeChat — Text Detoxifier (IndicBART Generation)
+
+Converts toxic Hindi/Hinglish/English sentences to polite versions.
+Uses the original downloaded IndicBART model with prompt-based generation.
+"""
+
+import re
+from typing import Dict, List, Optional
+from loguru import logger
+import torch
+from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
+
+from app.config import settings
+from app.utils.preprocessing import detect_language
+
+LANGUAGE_TAGS = {
+    "en": "<2en>",
+    "hi": "<2hi>",
+    "hi-en": "<2en>",
+    "indic-en": "<2en>",
+}
+
+POLITE_FALLBACKS = {
+    "en": "Could you please say that more politely and respectfully?",
+    "hi": "कृपया यही बात थोड़े विनम्र और सम्मानजनक तरीके से कहें।",
+    "hi-en": "Please isi baat ko thoda politely aur respectfully bolo.",
+    "indic-en": "Please say this more politely and respectfully.",
+}
+
+
+class Detoxifier:
+    def __init__(self):
+        self._model = None
+        self._tokenizer = None
+        self._model_loaded = False
+        logger.info("Detoxifier initialized (IndicBART mode).")
+
+    def load_model(self) -> None:
+        if not settings.USE_MODEL_DETOX:
+            return
+
+        try:
+            logger.info(f"Loading IndicBART detox model: {settings.DETOX_MODEL}...")
+            self._tokenizer = AutoTokenizer.from_pretrained(settings.DETOX_MODEL, use_fast=False)
+            self._model = AutoModelForSeq2SeqLM.from_pretrained(settings.DETOX_MODEL)
+            self._model.to(settings.DEVICE)
+            self._model.eval()
+            self._model_loaded = True
+            logger.success(f"IndicBART Detox model loaded successfully on {settings.DEVICE}.")
+        except Exception as e:
+            logger.warning(f"Failed to load IndicBART: {e}")
+            self._model_loaded = False
+
+    def detoxify(
+        self,
+        text: str,
+        toxicity_categories: Optional[Dict[str, float]] = None,
+        target_language: Optional[str] = None,
+        preserve_intent: bool = True,
+    ) -> Dict:
+        lang = self._normalize_language(target_language or detect_language(text))
+        dominant_category = self._dominant_category(toxicity_categories)
+
+        if toxicity_categories and max(toxicity_categories.values(), default=0.0) < self._safe_threshold_for_language(lang):
+            return {
+                "original": text,
+                "detoxified": text,
+                "suggestions": [text],
+                "method": "passthrough",
+                "language": lang,
+                "confidence": 1.0,
+            }
+
+        generated = None
+        if self._model_loaded and settings.USE_MODEL_DETOX:
+            generated = self._model_detoxify(text, lang)
+
+        suggestions = self._build_suggestions(
+            original_text=text,
+            lang=lang,
+            dominant_category=dominant_category,
+            generated=generated,
+            preserve_intent=preserve_intent,
+        )
+        primary = suggestions[0] if suggestions else self._fallback_rewrite(lang)
+
+        return {
+            "original": text,
+            "detoxified": primary,
+            "suggestions": suggestions,
+            "method": "indic_bart" if generated else "template",
+            "language": lang,
+            "confidence": 0.85 if generated else 0.60,
+        }
+
+    def _model_detoxify(self, text: str, lang: str) -> Optional[str]:
+        if not self._model or not self._tokenizer:
+            return None
+
+        try:
+            prompt = self._build_prompt(text, lang)
+
+            inputs = self._tokenizer(
+                prompt,
+                return_tensors="pt",
+                max_length=settings.MAX_SEQ_LENGTH,
+                truncation=True,
+            )
+            inputs = {k: v.to(settings.DEVICE) for k, v in inputs.items()}
+
+            forced_bos_token_id = self._forced_bos_token_id(lang)
+            with torch.no_grad():
+                outputs = self._model.generate(
+                    **inputs,
+                    max_new_tokens=settings.DETOX_MAX_LENGTH,
+                    num_beams=settings.DETOX_NUM_BEAMS,
+                    min_new_tokens=8,
+                    no_repeat_ngram_size=3,
+                    repetition_penalty=1.2,
+                    length_penalty=1.0,
+                    early_stopping=True,
+                    forced_bos_token_id=forced_bos_token_id,
+                )
+
+            result = self._tokenizer.decode(outputs[0], skip_special_tokens=False)
+            cleaned = self._clean_generation(result, prompt, text)
+            return cleaned
+
+        except Exception as e:
+            logger.error(f"IndicBART detoxification failed: {e}")
+            return None
+
+    def get_info(self) -> Dict:
+        return {
+            "mode": "indic_bart" if self._model_loaded else "fallback",
+            "model_name": settings.DETOX_MODEL if self._model_loaded else None,
+        }
+
+    @staticmethod
+    def _normalize_language(lang: str) -> str:
+        if lang in {"hi", "hi-en", "indic-en", "en"}:
+            return lang
+        return "en"
+
+    @staticmethod
+    def _safe_threshold_for_language(lang: str) -> float:
+        if lang == "hi-en":
+            return settings.THRESHOLD_SAFE_HINGLISH
+        return settings.THRESHOLD_SAFE
+
+    def _forced_bos_token_id(self, lang: str) -> Optional[int]:
+        if not self._tokenizer:
+            return None
+        token = LANGUAGE_TAGS.get(lang, "<2en>")
+        token_id = self._tokenizer.convert_tokens_to_ids(token)
+        return token_id if isinstance(token_id, int) and token_id >= 0 else None
+
+    @staticmethod
+    def _build_prompt(text: str, lang: str) -> str:
+        if lang == "hi":
+            return (
+                "इस अपमानजनक वाक्य को विनम्र और सम्मानजनक हिंदी में दोबारा लिखो.\n"
+                f"अपमानजनक: {text}\n"
+                "विनम्र:"
+            )
+        if lang == "hi-en":
+            return (
+                "Is toxic text ko polite aur respectful Hinglish mein Roman script me rewrite karo.\n"
+                f"Toxic: {text}\n"
+                "Polite Hinglish:"
+            )
+        return (
+            "Rewrite the following toxic text into polite and respectful English.\n"
+            f"Toxic: {text}\n"
+            "Polite:"
+        )
+
+    @staticmethod
+    def _fallback_rewrite(lang: str) -> str:
+        return POLITE_FALLBACKS.get(lang, POLITE_FALLBACKS["en"])
+
+    @staticmethod
+    def _dominant_category(toxicity_categories: Optional[Dict[str, float]]) -> str:
+        if not toxicity_categories:
+            return "toxic"
+        for label in ("identity_hate", "threat", "obscene", "insult"):
+            if toxicity_categories.get(label, 0.0) >= 0.30:
+                return label
+        return max(toxicity_categories, key=toxicity_categories.get)
+
+    def _build_suggestions(
+        self,
+        original_text: str,
+        lang: str,
+        dominant_category: str,
+        generated: Optional[str],
+        preserve_intent: bool,
+    ) -> List[str]:
+        suggestions: List[str] = []
+        if generated:
+            suggestions.append(generated)
+
+        suggestions.extend(self._template_suggestions(lang, dominant_category, preserve_intent))
+        if not suggestions:
+            suggestions.append(self._fallback_rewrite(lang))
+
+        deduped: List[str] = []
+        seen = set()
+        original_normalized = original_text.strip().lower()
+        for suggestion in suggestions:
+            cleaned = suggestion.strip()
+            if not cleaned:
+                continue
+            normalized = cleaned.lower()
+            if normalized == original_normalized:
+                continue
+            if normalized in seen:
+                continue
+            seen.add(normalized)
+            deduped.append(cleaned)
+            if len(deduped) == 3:
+                break
+
+        return deduped or [self._fallback_rewrite(lang)]
+
+    def _template_suggestions(self, lang: str, dominant_category: str, preserve_intent: bool) -> List[str]:
+        category = dominant_category if dominant_category in {"insult", "obscene", "threat", "identity_hate"} else "toxic"
+
+        if lang == "hi":
+            templates = {
+                "toxic": [
+                    "कृपया यही बात थोड़े विनम्र और सम्मानजनक तरीके से कहें।",
+                    "अपनी बात बिना अपमानजनक भाषा के भी कही जा सकती है।",
+                    "कृपया बातचीत में शिष्ट और सम्मानजनक भाषा रखें।",
+                ],
+                "insult": [
+                    "मैं असहमत हूँ, लेकिन कृपया सम्मानजनक भाषा रखें।",
+                    "नाराज़गी जताइए, पर व्यक्तिगत अपमान मत कीजिए।",
+                    "कृपया मुद्दे पर बात करें, व्यक्ति पर नहीं।",
+                ],
+                "obscene": [
+                    "कृपया अश्लील शब्दों के बिना अपनी बात कहें।",
+                    "आप नाराज़ हो सकते हैं, लेकिन भाषा मर्यादित रखें।",
+                    "अपना संदेश साफ और सम्मानजनक तरीके से रखें।",
+                ],
+                "threat": [
+                    "धमकी देने के बजाय शांत और स्पष्ट तरीके से अपनी बात र��ें।",
+                    "मैं बहुत नाराज़ हूँ, लेकिन धमकी नहीं देना चाहता।",
+                    "हिंसा या डराने वाली भाषा से बचते हुए बात करें।",
+                ],
+                "identity_hate": [
+                    "कृपया किसी की पहचान या समुदाय को निशाना बनाए बिना अपनी बात कहें।",
+                    "असहमति व्यक्त की जा सकती है, लेकिन घृणित भाषा ठीक नहीं है।",
+                    "हर व्यक्ति और समुदाय के प्रति सम्मानजनक भाषा रखें।",
+                ],
+            }
+        elif lang == "hi-en":
+            templates = {
+                "toxic": [
+                    "Please isi baat ko thoda politely aur respectfully bolo.",
+                    "Apni baat bina gaali diye bhi clear tarah se boli ja sakti hai.",
+                    "Chalo baat ko thoda calm aur respectful tareeke se rakhte hain.",
+                ],
+                "insult": [
+                    "Main disagree karta hoon, lekin personal insult ke bina bolunga.",
+                    "Please gusse mein bhi respectfully baat karo.",
+                    "Issue par bolo, insaan ko target mat karo.",
+                ],
+                "obscene": [
+                    "Please abusive words hata kar apni baat bolo.",
+                    "Frustration dikhani hai to bhi language clean rakho.",
+                    "Same point ko thoda decent aur respectful Hinglish mein bolo.",
+                ],
+                "threat": [
+                    "Main upset hoon, lekin dhamki nahi dunga.",
+                    "Please threatening language ke bina apni baat bolo.",
+                    "Chalo isko calmly resolve karte hain, darane wali language ke bina.",
+                ],
+                "identity_hate": [
+                    "Please kisi identity ya community ko target kiye bina baat karo.",
+                    "Disagree karna theek hai, hate speech nahi.",
+                    "Respectful Hinglish mein point rakho, identity-based abuse ke bina.",
+                ],
+            }
+        else:
+            templates = {
+                "toxic": [
+                    "Could you please say that more politely and respectfully?",
+                    "You can make the same point without abusive language.",
+                    "Let's keep the conversation respectful.",
+                ],
+                "insult": [
+                    "I disagree, but I want to say it respectfully.",
+                    "Please speak respectfully even if you're upset.",
+                    "Let's discuss the issue without personal insults.",
+                ],
+                "obscene": [
+                    "Please say this without profanity.",
+                    "You can express frustration without abusive words.",
+                    "Let's keep the wording clean and respectful.",
+                ],
+                "threat": [
+                    "I am upset, but I will not use threats.",
+                    "Please address this calmly without threatening language.",
+                    "Let's resolve this without violence or intimidation.",
+                ],
+                "identity_hate": [
+                    "Please make your point without targeting anyone's identity.",
+                    "Disagreement is fine, but hateful language is not.",
+                    "Let's keep this respectful toward every person and community.",
+                ],
+            }
+
+        selected = list(templates.get(category, templates["toxic"]))
+        if not preserve_intent:
+            selected[0] = self._fallback_rewrite(lang)
+        return selected
+
+    @staticmethod
+    def _clean_generation(result: str, prompt: str, original_text: str) -> Optional[str]:
+        cleaned = result
+        cleaned = re.sub(r"</?s>", " ", cleaned, flags=re.IGNORECASE)
+        cleaned = re.sub(r"<2[a-z]+>", " ", cleaned, flags=re.IGNORECASE)
+        cleaned = cleaned.replace("[CLS]", " ").replace("[SEP]", " ").replace("<pad>", " ")
+        cleaned = re.sub(r"\s+", " ", cleaned).strip()
+
+        for marker in ("Polite Hinglish:", "Polite:", "विनम्र:", "अपमानजनक:", "Toxic:"):
+            if marker in cleaned:
+                cleaned = cleaned.split(marker)[-1].strip()
+
+        if not cleaned:
+            return None
+
+        # Reject degenerate outputs that mostly echo the prompt or collapse into punctuation.
+        lowered = cleaned.lower()
+        if len(cleaned) < 4:
+            return None
+        if re.fullmatch(r"[\W_]+", cleaned):
+            return None
+        if any(
+            token in lowered
+            for token in (
+                "rewrite the following",
+                "polite hinglish",
+                "toxic:",
+                "tox",
+                "polite",
+                "rewrite",
+                "अपमानजनक",
+            )
+        ):
+            return None
+        if lowered == original_text.lower().strip():
+            return None
+        if re.search(r"\b(\w+)(?:\s+\1){2,}\b", lowered):
+            return None
+
+        return cleaned

app/models/model_manager.py

@@ -0,0 +1,89 @@
+"""
+SafeChat — Model Manager
+Cenrtalized lifecycle manager for ML models.
+"""
+
+from typing import Dict, Optional
+import torch
+from loguru import logger
+
+from app.config import settings
+from app.models.toxicity_classifier import ToxicityClassifier
+from app.models.detoxifier import Detoxifier
+
+class ModelManager:
+    """Singleton-style manager for Mutli-label Classification and Seq2Seq Detoxification."""
+
+    def __init__(self):
+        self.classifier: Optional[ToxicityClassifier] = None
+        self.detoxifier: Optional[Detoxifier] = None
+        self._initialized = False
+
+    async def initialize(self) -> None:
+        """Load all models. Called once during FastAPI startup."""
+        logger.info("=" * 60)
+        logger.info("  SafeChat Model Manager — Initializing (MuRIL & IndicBART)")
+        logger.info("=" * 60)
+        self._log_hardware_info()
+
+        # Load MuRIL
+        try:
+            self.classifier = ToxicityClassifier(
+                model_name=settings.CLASSIFIER_MODEL,
+                device=settings.DEVICE,
+            )
+            self.classifier.load()
+        except Exception as e:
+            logger.error(f"Failed to load toxicity classifier: {e}")
+            raise RuntimeError(f"Classifier initialization failed: {e}")
+
+        # Load IndicBART
+        try:
+            self.detoxifier = Detoxifier()
+            self.detoxifier.load_model()
+        except Exception as e:
+            logger.warning(f"Detoxifier model loading failed: {e}. Template fallback will be used.")
+
+        self._initialized = True
+        logger.success("All models initialized successfully!")
+        logger.info("=" * 60)
+
+    @property
+    def is_ready(self) -> bool:
+        return self._initialized and self.classifier is not None and self.classifier.is_loaded
+
+    def get_health(self) -> Dict:
+        return {
+            "status": "healthy" if self.is_ready else "degraded",
+            "models": {
+                "toxicity_classifier": self.classifier.get_info() if self.classifier else {"loaded": False},
+                "detoxifier": self.detoxifier.get_info() if self.detoxifier else {"loaded": False},
+            },
+            "device": settings.DEVICE,
+        }
+
+    async def swap_classifier(self, new_model_path: str) -> bool:
+        """Hot-swap the toxicity classifier."""
+        logger.info(f"Hot-swapping classifier to: {new_model_path}")
+        try:
+            new_classifier = ToxicityClassifier(model_name=new_model_path, device=settings.DEVICE)
+            new_classifier.load()
+            old_classifier = self.classifier
+            self.classifier = new_classifier
+            del old_classifier
+            if settings.DEVICE == "cuda":
+                torch.cuda.empty_cache()
+            return True
+        except Exception as e:
+            logger.error(f"Classifier hot-swap failed: {e}.")
+            return False
+
+    @staticmethod
+    def _log_hardware_info():
+        if torch.cuda.is_available():
+            logger.info(f"GPU: {torch.cuda.get_device_name(0)}")
+        else:
+            logger.warning("No GPU detected. Running on CPU (slower inference).")
+        logger.info(f"Selected device: {settings.DEVICE}")
+
+model_manager = ModelManager()

app/models/toxicity_classifier.py

@@ -0,0 +1,603 @@
+"""
+SafeChat — Toxicity Classifier (Single MuRIL Model)
+
+Architecture:
+  ┌─────────┐
+  │  Input  │ (Hindi, English, Hinglish)
+  └────┬────┘
+       │
+       ▼
+  ┌───────────────────────┐
+  │ google/muril-base     │ (SequenceClassifier)
+  └───────┬───────────────┘
+          │ Output Logits
+          ▼
+  ┌───────────────────────┐
+  │ Sigmoid Activation    │ 
+  └───────┬───────────────┘
+          ▼
+  ┌───────────────────────┐
+  │ Labels & Severity     │
+  └───────────────────────┘
+"""
+
+import time
+import re
+from typing import Dict, Optional
+import torch
+import torch.nn.functional as F
+from transformers import AutoModelForSequenceClassification, AutoTokenizer
+from loguru import logger
+
+from app.config import settings
+from app.utils.preprocessing import clean_text, detect_language, normalize_for_toxicity
+
+# Labels as defined in our training data
+LABELS = ["toxic", "severe_toxic", "obscene", "threat", "insult", "identity_hate"]
+
+LOW_INSULT_FLOORS = {"toxic": 0.24, "insult": 0.21}
+MEDIUM_INSULT_FLOORS = {"toxic": 0.38, "insult": 0.34}
+STRONG_INSULT_FLOORS = {"toxic": 0.44, "insult": 0.38}
+OBSCENE_FLOORS = {"toxic": 0.68, "obscene": 0.62, "insult": 0.56}
+SEVERE_OBSCENE_FLOORS = {"toxic": 0.74, "obscene": 0.68, "insult": 0.60}
+IDENTITY_SLUR_FLOORS = {"toxic": 0.44, "insult": 0.38, "identity_hate": 0.34}
+
+HINGLISH_LOW_INSULT_WORDS = (
+    "badir",
+    "badirchand",
+    "baklol",
+    "baklund",
+    "bakwas",
+    "bakwaas",
+    "fatu",
+    "fattu",
+    "ghatiya",
+    "gawar",
+    "jahil",
+    "jhandu",
+    "jhant",
+    "jhantu",
+    "jhaantu",
+    "nalayak",
+    "nikamma",
+    "pagal",
+    "paagal",
+    "sala",
+    "saala",
+    "saale",
+    "sali",
+    "saali",
+    "ullu",
+)
+
+HINGLISH_MEDIUM_INSULT_WORDS = (
+    "bastard",
+    "bewakoof",
+    "bewaqoof",
+    "bewakuf",
+    "bevakuf",
+    "chinal",
+    "gadha",
+    "gadhe",
+    "gadhi",
+    "idiot",
+    "jerk",
+    "kamina",
+    "kamine",
+    "kaminey",
+    "kamini",
+    "kamino",
+    "kanjar",
+    "kanjari",
+    "kanjaron",
+    "kutta",
+    "kutte",
+    "kuttey",
+    "kuttay",
+    "kutti",
+    "kuttia",
+    "kuttiya",
+    "kutiya",
+    "loser",
+    "moron",
+    "rascal",
+    "stupid",
+    "suar",
+    "suvar",
+    "suwar",
+    "sooar",
+    "tharki",
+)
+
+HINGLISH_STRONG_INSULT_WORDS = (
+    "bhadva",
+    "bhadve",
+    "bhadwa",
+    "bhadwe",
+    "bhadwi",
+    "harami",
+    "haraami",
+    "haramkhor",
+    "haramzada",
+    "haramzade",
+    "haramzaadi",
+    "haramzadi",
+    "najayaz",
+    "najayz",
+    "randi",
+    "randwa",
+    "randwe",
+)
+
+HINGLISH_IDENTITY_SLUR_WORDS = (
+    "chakka",
+    "chakke",
+    "chhakka",
+    "chhakke",
+    "hijda",
+    "hijde",
+    "hijra",
+    "hijre",
+)
+
+HINGLISH_OBSCENE_WORDS = (
+    "asshole",
+    "bakchod",
+    "bakchodi",
+    "bsdk",
+    "chodra",
+    "chodu",
+    "choot",
+    "chosi",
+    "chot",
+    "chuth",
+    "chut",
+    "chutiya",
+    "chutiye",
+    "chutiyagiri",
+    "chutiyapa",
+    "chutiyon",
+    "chutia",
+    "gaand",
+    "gaandu",
+    "gand",
+    "gandu",
+    "lawda",
+    "lauda",
+    "laude",
+    "lavda",
+    "loda",
+    "lode",
+    "lodu",
+    "lund",
+    "lundi",
+    "lundtopi",
+    "tatta",
+    "tatte",
+    "tattey",
+    "tatti",
+)
+
+HINGLISH_SEVERE_OBSCENE_WORDS = (
+    "allahchodi",
+    "allachodi",
+    "bahanchod",
+    "bahenchod",
+    "banchod",
+    "behenchod",
+    "behenchhod",
+    "benchod",
+    "bhencho",
+    "bhenchod",
+    "bhenchhod",
+    "bhnchod",
+    "bhosad",
+    "bhosada",
+    "bhosadi",
+    "bhosadike",
+    "bhosadika",
+    "bhosadiwala",
+    "bhosadiwale",
+    "bhosde",
+    "bhosday",
+    "bhosdi",
+    "bhosdika",
+    "bhosdiki",
+    "bhosdike",
+    "bhosdiwala",
+    "bhosdiwale",
+    "bhosdiwaloon",
+    "bhosri",
+    "bhosrik",
+    "bhosriwala",
+    "bhosriwale",
+    "bitch",
+    "cunt",
+    "dickhead",
+    "dipshit",
+    "fucker",
+    "fucking",
+    "madarchod",
+    "madarchood",
+    "madarjaat",
+    "madarjat",
+    "motherfucker",
+    "motherfucking",
+    "scumbag",
+    "slut",
+    "whore",
+)
+
+HINDI_LOW_INSULT_WORDS = (
+    "अक्लहीन",
+    "बकवास",
+    "बेकार",
+    "जाहिल",
+    "घटिया",
+    "पागल",
+    "नालायक",
+    "निकम्मा",
+    "निकम्मे",
+)
+
+HINDI_MEDIUM_INSULT_WORDS = (
+    "बेवकूफ",
+    "गधा",
+    "गधे",
+    "गधी",
+    "कमीना",
+    "कमीने",
+    "कमीनी",
+    "कुत्ता",
+    "कुत्ते",
+    "कुतिया",
+    "मूर्ख",
+    "गंवार",
+    "बदतमीज",
+)
+
+HINDI_STRONG_INSULT_WORDS = (
+    "हरामी",
+    "हरामखोर",
+    "हरामज़ादा",
+    "हरामजादा",
+    "हरामज़ादी",
+    "हरामजादी",
+    "रंडी",
+    "नीच",
+)
+
+HINDI_IDENTITY_SLUR_WORDS = (
+    "छक्का",
+    "छक्के",
+    "हिजड़ा",
+    "हिजड़े",
+    "हिजरा",
+    "हिजरे",
+)
+
+HINDI_OBSCENE_WORDS = (
+    "चूत",
+    "चूतिया",
+    "चूतिये",
+    "चूतियापा",
+    "गांड",
+    "गाण्ड",
+    "गांडू",
+    "गाण्डू",
+    "लंड",
+    "लौड़ा",
+    "लौड़े",
+    "लवड़ा",
+    "टट्टी",
+    "टट्टे",
+)
+
+HINDI_SEVERE_OBSCENE_WORDS = (
+    "बहनचोद",
+    "भोसड़ी",
+    "भोसडी",
+    "भोसड़ीके",
+    "भोसडीके",
+    "मादरचोद",
+    "मदरचोद",
+    "मादरजात",
+)
+
+ENGLISH_TOKEN_FLOORS = {
+    "asshole": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "bastard": {"toxic": 0.38, "insult": 0.34},
+    "bitch": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "bullshit": {"toxic": 0.44, "obscene": 0.38, "insult": 0.34},
+    "crap": {"toxic": 0.34, "insult": 0.31},
+    "dickhead": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "dipshit": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "dumbass": {"toxic": 0.44, "insult": 0.38},
+    "fucker": {"toxic": 0.74, "obscene": 0.68, "insult": 0.60},
+    "fucking": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "idiot": {"toxic": 0.38, "insult": 0.34},
+    "jackass": {"toxic": 0.44, "insult": 0.38},
+    "jerk": {"toxic": 0.34, "insult": 0.31},
+    "loser": {"toxic": 0.38, "insult": 0.34},
+    "moron": {"toxic": 0.38, "insult": 0.34},
+    "prick": {"toxic": 0.44, "insult": 0.38},
+    "retard": {"toxic": 0.44, "insult": 0.38, "identity_hate": 0.34},
+    "scumbag": {"toxic": 0.44, "insult": 0.38},
+    "shithead": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "slut": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "stupid": {"toxic": 0.34, "insult": 0.31},
+    "trash": {"toxic": 0.34, "insult": 0.31},
+    "whore": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+}
+
+ENGLISH_PHRASE_FLOORS = {
+    "drop dead": {"toxic": 0.44, "threat": 0.38},
+    "go kill yourself": {"toxic": 0.56, "threat": 0.52},
+    "go to hell": {"toxic": 0.38, "insult": 0.34},
+    "i will kill you": {"toxic": 0.56, "threat": 0.52},
+    "i'll kill you": {"toxic": 0.56, "threat": 0.52},
+    "piece of shit": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "shut the fuck up": {"toxic": 0.74, "obscene": 0.68, "insult": 0.60},
+    "shut up": {"toxic": 0.34, "insult": 0.31},
+    "son of a bitch": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+}
+
+
+def _build_token_floors(grouped_words: tuple[tuple[tuple[str, ...], Dict[str, float]], ...]) -> Dict[str, Dict[str, float]]:
+    floors: Dict[str, Dict[str, float]] = {}
+    for words, labels in grouped_words:
+        for word in words:
+            floors[word] = dict(labels)
+    return floors
+
+
+HINGLISH_TOKEN_FLOORS = _build_token_floors(
+    (
+        (HINGLISH_LOW_INSULT_WORDS, LOW_INSULT_FLOORS),
+        (HINGLISH_MEDIUM_INSULT_WORDS, MEDIUM_INSULT_FLOORS),
+        (HINGLISH_STRONG_INSULT_WORDS, STRONG_INSULT_FLOORS),
+        (HINGLISH_IDENTITY_SLUR_WORDS, IDENTITY_SLUR_FLOORS),
+        (HINGLISH_OBSCENE_WORDS, OBSCENE_FLOORS),
+        (HINGLISH_SEVERE_OBSCENE_WORDS, SEVERE_OBSCENE_FLOORS),
+    )
+)
+
+HINGLISH_PHRASE_FLOORS = {
+    "behen chod": {"toxic": 0.74, "obscene": 0.68, "insult": 0.60},
+    "bhen chod": {"toxic": 0.74, "obscene": 0.68, "insult": 0.60},
+    "gaand mar": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "jaan se maar": {"toxic": 0.56, "threat": 0.52},
+    "kill kar dunga": {"toxic": 0.56, "threat": 0.52},
+    "kutte ki aulad": {"toxic": 0.44, "insult": 0.38},
+    "maar dunga": {"toxic": 0.52, "threat": 0.48},
+    "madar chod": {"toxic": 0.74, "obscene": 0.68, "insult": 0.60},
+    "mar dunga": {"toxic": 0.52, "threat": 0.48},
+    "mother fucker": {"toxic": 0.74, "obscene": 0.68, "insult": 0.60},
+    "piece of shit": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "son of a bitch": {"toxic": 0.68, "obscene": 0.62, "insult": 0.56},
+    "suwar ki aulad": {"toxic": 0.44, "insult": 0.38},
+    "teri behen": {"toxic": 0.44, "insult": 0.38},
+    "teri ma": {"toxic": 0.44, "insult": 0.38},
+    "teri maa": {"toxic": 0.44, "insult": 0.38},
+    "tu mar ja": {"toxic": 0.38, "threat": 0.34},
+    "ullu ka pattha": {"toxic": 0.38, "insult": 0.34},
+}
+
+HINDI_TOKEN_FLOORS = _build_token_floors(
+    (
+        (HINDI_LOW_INSULT_WORDS, LOW_INSULT_FLOORS),
+        (HINDI_MEDIUM_INSULT_WORDS, MEDIUM_INSULT_FLOORS),
+        (HINDI_STRONG_INSULT_WORDS, STRONG_INSULT_FLOORS),
+        (HINDI_IDENTITY_SLUR_WORDS, IDENTITY_SLUR_FLOORS),
+        (HINDI_OBSCENE_WORDS, OBSCENE_FLOORS),
+        (HINDI_SEVERE_OBSCENE_WORDS, SEVERE_OBSCENE_FLOORS),
+    )
+)
+
+HINDI_PHRASE_FLOORS = {
+    "जा मर": {"toxic": 0.38, "threat": 0.34},
+    "जान से मार दूंगा": {"toxic": 0.56, "threat": 0.52},
+    "जान से मार दूँगा": {"toxic": 0.56, "threat": 0.52},
+    "तेरी बहन": {"toxic": 0.44, "insult": 0.38},
+    "तेरी मां": {"toxic": 0.44, "insult": 0.38},
+    "तेरी माँ": {"toxic": 0.44, "insult": 0.38},
+    "मार दूंगा": {"toxic": 0.52, "threat": 0.48},
+    "मार दूँगा": {"toxic": 0.52, "threat": 0.48},
+}
+
+class ToxicityClassifier:
+    """
+    Toxicity classifier powered by fine-tuned MuRIL base.
+    """
+
+    def __init__(self, model_name: str = settings.CLASSIFIER_MODEL, device: str = settings.DEVICE):
+        self.device = device
+        self._loaded = False
+        self._model_name = model_name
+
+        self.tokenizer = None
+        self.model = None
+        self.model_version = settings.APP_VERSION
+
+    def load(self) -> None:
+        """Load MuRIL model into memory."""
+        logger.info(f"Loading tokenizer and model ({self._model_name}) on {self.device}...")
+        try:
+            # MuRIL can require protobuf-backed slow tokenizer loading in lean container environments.
+            self.tokenizer = AutoTokenizer.from_pretrained(self._model_name, use_fast=False)
+            self.model = AutoModelForSequenceClassification.from_pretrained(
+                self._model_name, 
+                num_labels=len(LABELS),
+                problem_type="multi_label_classification"
+            )
+            # If the model hasn't been fine-tuned yet, it will throw a warning about randomly initialized weights. 
+            # We explicitly ignore here for first-time startup.
+            self.model.to(self.device)
+            self.model.eval()
+
+            self._loaded = True
+            logger.success("MuRIL toxicity model loaded successfully.")
+        except Exception as e:
+            logger.error(f"Failed to load MuRIL model: {e}")
+            raise e
+
+    @property
+    def is_loaded(self) -> bool:
+        return self._loaded
+
+    def predict(self, text: str, context: Optional[list[str]] = None) -> Dict:
+        """
+        Classify text for toxicity using MuRIL.
+        """
+        if not self._loaded:
+            raise RuntimeError("Model not loaded. Call classifier.load() first.")
+
+        start_time = time.perf_counter()
+
+        # Step 1: Preprocess
+        normalized = normalize_for_toxicity(text)
+        lang = detect_language(text)  # "en", "hi", "hi-en"
+        model_input = normalized
+
+        # Incorporate up to 4 past messages for context if provided
+        if context and len(context) > 0:
+            context_str = " [SEP] ".join(context[-4:])
+            model_input = f"{context_str} [SEP] {normalized}"
+
+        # Step 2: Tokenize
+        inputs = self.tokenizer(
+            model_input,
+            return_tensors="pt",
+            max_length=settings.MAX_SEQ_LENGTH,
+            truncation=True,
+            padding=True,
+        )
+        inputs = {k: v.to(self.device) for k, v in inputs.items()}
+
+        # Step 3: Inference
+        with torch.no_grad():
+            outputs = self.model(**inputs)
+            logits = outputs.logits
+            # Sigmoid is used for multi-label classification to get probabilities 0-1
+            probs = torch.sigmoid(logits)[0].cpu().numpy().tolist()
+
+        # Step 4: Map back to Categories
+        categories = {LABELS[i]: float(probs[i]) for i in range(len(LABELS))}
+        categories = self._apply_hindi_lexicon_boost(normalized, categories, lang)
+        categories = self._apply_hinglish_lexicon_boost(normalized, categories, lang)
+        categories = self._apply_english_lexicon_boost(normalized, categories, lang)
+        
+        # Step 5: Overall score + severity
+        overall_score = round(max(categories.values()), 4)
+        severity = self._score_to_severity(overall_score, lang)
+        categories = {label: round(score, 4) for label, score in categories.items()}
+
+        inference_time_ms = int((time.perf_counter() - start_time) * 1000)
+
+        return {
+            "is_toxic": overall_score >= self._safe_threshold_for_language(lang),
+            "overall_score": overall_score,
+            "severity": severity,
+            "categories": categories,
+            "detected_language": lang,
+            "ensemble_weights": {"muril": 1.0}, # Single model now
+            "model_version": self.model_version,
+            "inference_time_ms": inference_time_ms,
+        }
+
+    def predict_batch(self, texts: list[str]) -> list[Dict]:
+        """Classify a batch of texts."""
+        return [self.predict(text) for text in texts]
+
+    @staticmethod
+    def _safe_threshold_for_language(lang: str) -> float:
+        if lang == "hi-en":
+            return settings.THRESHOLD_SAFE_HINGLISH
+        return settings.THRESHOLD_SAFE
+
+    @classmethod
+    def _score_to_severity(cls, score: float, lang: str) -> str:
+        """Map a toxicity score to a severity level."""
+        safe_threshold = cls._safe_threshold_for_language(lang)
+        if score < safe_threshold:
+            return "SAFE"
+        elif score < settings.THRESHOLD_LOW:
+            return "LOW"
+        elif score < settings.THRESHOLD_MEDIUM:
+            return "MEDIUM"
+        else:
+            return "HIGH"
+
+    @staticmethod
+    def _apply_hinglish_lexicon_boost(text: str, categories: Dict[str, float], lang: str) -> Dict[str, float]:
+        """Boost missed Hinglish toxicity for common romanized abuse terms."""
+        if lang != "hi-en":
+            return categories
+
+        return ToxicityClassifier._apply_lexicon_floors(
+            text=text,
+            categories=categories,
+            token_floors=HINGLISH_TOKEN_FLOORS,
+            phrase_floors=HINGLISH_PHRASE_FLOORS,
+        )
+
+    @staticmethod
+    def _apply_hindi_lexicon_boost(text: str, categories: Dict[str, float], lang: str) -> Dict[str, float]:
+        """Boost missed Hindi-script toxicity for common slurs, obscenity, and threat phrases."""
+        if lang != "hi":
+            return categories
+
+        return ToxicityClassifier._apply_lexicon_floors(
+            text=text,
+            categories=categories,
+            token_floors=HINDI_TOKEN_FLOORS,
+            phrase_floors=HINDI_PHRASE_FLOORS,
+        )
+
+    @staticmethod
+    def _apply_english_lexicon_boost(text: str, categories: Dict[str, float], lang: str) -> Dict[str, float]:
+        """Boost obvious English profanity and insults the base model may under-score."""
+        if lang != "en":
+            return categories
+
+        return ToxicityClassifier._apply_lexicon_floors(
+            text=text,
+            categories=categories,
+            token_floors=ENGLISH_TOKEN_FLOORS,
+            phrase_floors=ENGLISH_PHRASE_FLOORS,
+        )
+
+    @staticmethod
+    def _apply_lexicon_floors(
+        text: str,
+        categories: Dict[str, float],
+        token_floors: Dict[str, Dict[str, float]],
+        phrase_floors: Dict[str, Dict[str, float]],
+    ) -> Dict[str, float]:
+        """Apply token and phrase-based minimum scores for language-specific abuse lexicons."""
+        boosted = dict(categories)
+        lowered = text.lower()
+        tokens = set(re.findall(r"[a-z\u0900-\u097f]+", lowered))
+
+        for token, floors in token_floors.items():
+            if token in tokens:
+                for label, floor in floors.items():
+                    boosted[label] = max(boosted[label], floor)
+
+        for phrase, floors in phrase_floors.items():
+            if phrase in lowered:
+                for label, floor in floors.items():
+                    boosted[label] = max(boosted[label], floor)
+
+        return boosted
+
+    def get_info(self) -> Dict:
+        """Return model metadata for health checks."""
+        return {
+            "muril_model": {
+                "name": self._model_name,
+                "loaded": self._loaded,
+            },
+            "device": self.device,
+            "version": self.model_version,
+        }

app/schemas/__init__.py

@@ -0,0 +1 @@
+# Schemas package

app/schemas/feedback.py

@@ -0,0 +1,50 @@
+"""
+SafeChat — Feedback API Schemas (Pydantic v2)
+
+Used by the moderator dashboard to submit corrections,
+which feed into the continuous learning pipeline.
+"""
+
+from typing import Optional
+from datetime import datetime
+from pydantic import BaseModel, Field
+
+
+class FeedbackRequest(BaseModel):
+    """Request body for POST /api/v1/feedback"""
+    message_id: str = Field(..., description="MongoDB ObjectId of the moderated message")
+    moderator_id: str = Field(..., description="UUID of the moderator")
+    model_prediction_was_correct: bool = Field(
+        ..., description="Did the model classify correctly?"
+    )
+    correct_label: Optional[str] = Field(
+        None,
+        description="Correct toxicity label if model was wrong (e.g., 'not_toxic', 'toxic', 'insult')",
+    )
+    correct_severity: Optional[str] = Field(
+        None, description="Correct severity if model was wrong (SAFE/LOW/MEDIUM/HIGH)"
+    )
+    notes: Optional[str] = Field(
+        None, max_length=1000, description="Moderator notes explaining the correction"
+    )
+
+
+class FeedbackResponse(BaseModel):
+    """Response body for POST /api/v1/feedback"""
+    feedback_id: str
+    message: str
+    total_feedback_count: int
+    retrain_threshold: int
+    retrain_triggered: bool
+
+
+class FeedbackStats(BaseModel):
+    """Response body for GET /api/v1/feedback/stats"""
+    total_feedback: int
+    correct_predictions: int
+    incorrect_predictions: int
+    accuracy: float = Field(ge=0, le=1)
+    feedback_since_last_retrain: int
+    retrain_threshold: int
+    next_retrain_at: int  # Feedback count needed to trigger retrain
+    last_retrain_at: Optional[datetime] = None

app/schemas/moderation.py

@@ -0,0 +1,85 @@
+"""
+SafeChat — Moderation API Schemas (Pydantic v2)
+"""
+
+from typing import Dict, Optional
+from pydantic import BaseModel, Field
+
+
+class ModerationRequest(BaseModel):
+    """Request body for POST /api/v1/moderate"""
+    text: str = Field(..., min_length=1, max_length=5000, description="Text to moderate")
+    channel_id: Optional[str] = Field(None, description="Channel ID for policy lookup")
+    user_id: Optional[str] = Field(None, description="User ID for tracking")
+    context: Optional[list[str]] = Field(default_factory=list, description="List of previous messages for conversation context")
+
+    model_config = {"json_schema_extra": {
+        "examples": [
+            {
+                "text": "tu bahut bada bewakoof hai bro",
+                "channel_id": "general",
+                "user_id": "user-123",
+                "context": ["Hi, how are you?", "I am fine, but you are annoying"]
+            }
+        ]
+    }}
+
+
+class ToxicityCategories(BaseModel):
+    """Breakdown of toxicity scores by category."""
+    toxic: float = Field(ge=0, le=1)
+    severe_toxic: float = Field(ge=0, le=1)
+    obscene: float = Field(ge=0, le=1)
+    identity_hate: float = Field(ge=0, le=1)
+    insult: float = Field(ge=0, le=1)
+    threat: float = Field(ge=0, le=1)
+
+
+class EnsembleWeights(BaseModel):
+    """Weights used for the ensemble prediction."""
+    en_model: float
+    multi_model: float
+
+
+class ModerationResponse(BaseModel):
+    """Response body for POST /api/v1/moderate"""
+    is_toxic: bool
+    overall_score: float = Field(ge=0, le=1)
+    severity: str = Field(description="SAFE | LOW | MEDIUM | HIGH")
+    categories: Dict[str, float]
+    detected_language: str
+    ensemble_weights: Dict[str, float]
+    suggestion: Optional[str] = Field(None, description="Polite alternative (if toxic)")
+    suggestions: Optional[list[str]] = Field(None, description="Alternative polite rewrites (if toxic)")
+    model_version: str
+    inference_time_ms: int
+
+
+class DetoxifyRequest(BaseModel):
+    """Request body for POST /api/v1/detoxify"""
+    text: str = Field(..., min_length=1, max_length=5000)
+    target_language: Optional[str] = Field(None, description="Override language detection")
+    preserve_intent: bool = Field(True, description="Try to preserve the original meaning")
+
+
+class DetoxifyResponse(BaseModel):
+    """Response body for POST /api/v1/detoxify"""
+    original: str
+    detoxified: str
+    suggestions: list[str] = Field(default_factory=list, description="Alternative polite rewrites")
+    method: str = Field(description="'passthrough' | 'template' | 'indic_bart'")
+    language: str
+    confidence: float = Field(ge=0, le=1)
+
+
+class BatchModerationRequest(BaseModel):
+    """Request body for POST /api/v1/moderate/batch"""
+    texts: list[str] = Field(..., min_length=1, max_length=50)
+    channel_id: Optional[str] = None
+    user_id: Optional[str] = None
+
+
+class BatchModerationResponse(BaseModel):
+    """Response body for POST /api/v1/moderate/batch"""
+    results: list[ModerationResponse]
+    total_inference_time_ms: int

app/services/__init__.py

@@ -0,0 +1 @@
+# Services package

app/services/feedback_service.py

@@ -0,0 +1,139 @@
+"""
+SafeChat — Feedback Service
+
+Handles moderator feedback storage and continuous learning triggers.
+Feedback is stored in MongoDB and used to retrain models when
+the threshold is reached.
+"""
+
+from typing import Dict, Optional
+from datetime import datetime
+
+from loguru import logger
+
+from app.config import settings
+
+
+class FeedbackService:
+    """
+    Manages the moderator feedback loop.
+
+    Flow:
+      1. Moderator reviews a flagged message
+      2. Submits correction via POST /api/v1/feedback
+      3. Feedback stored in MongoDB
+      4. When feedback count reaches threshold → trigger retraining
+    """
+
+    def __init__(self):
+        self._feedback_count = 0
+        self._correct_count = 0
+        self._incorrect_count = 0
+        self._last_retrain_at: Optional[datetime] = None
+        self._feedback_since_retrain = 0
+
+        # In-memory store (replaced by MongoDB in production)
+        self._feedback_store: list[Dict] = []
+
+    async def submit_feedback(self, feedback: Dict) -> Dict:
+        """
+        Store moderator feedback and check if retraining should be triggered.
+
+        Args:
+            feedback: Dict with message_id, moderator_id, correct_label, etc.
+
+        Returns:
+            Dict with feedback_id, counts, and whether retrain was triggered
+        """
+        # Store feedback
+        feedback_entry = {
+            **feedback,
+            "feedback_id": f"fb-{self._feedback_count + 1}",
+            "submitted_at": datetime.utcnow().isoformat(),
+        }
+        self._feedback_store.append(feedback_entry)
+
+        # Update counters
+        self._feedback_count += 1
+        self._feedback_since_retrain += 1
+
+        if feedback.get("model_prediction_was_correct", True):
+            self._correct_count += 1
+        else:
+            self._incorrect_count += 1
+
+        # Check if retraining should be triggered
+        retrain_triggered = False
+        if self._feedback_since_retrain >= settings.FEEDBACK_THRESHOLD_FOR_RETRAIN:
+            retrain_triggered = await self._trigger_retraining()
+
+        logger.info(
+            f"Feedback #{self._feedback_count} received. "
+            f"Correct: {self._correct_count}, Incorrect: {self._incorrect_count}. "
+            f"Retrain triggered: {retrain_triggered}"
+        )
+
+        return {
+            "feedback_id": feedback_entry["feedback_id"],
+            "message": "Feedback recorded successfully",
+            "total_feedback_count": self._feedback_count,
+            "retrain_threshold": settings.FEEDBACK_THRESHOLD_FOR_RETRAIN,
+            "retrain_triggered": retrain_triggered,
+        }
+
+    async def get_stats(self) -> Dict:
+        """Return feedback statistics."""
+        accuracy = (
+            self._correct_count / self._feedback_count
+            if self._feedback_count > 0
+            else 0.0
+        )
+
+        return {
+            "total_feedback": self._feedback_count,
+            "correct_predictions": self._correct_count,
+            "incorrect_predictions": self._incorrect_count,
+            "accuracy": round(accuracy, 4),
+            "feedback_since_last_retrain": self._feedback_since_retrain,
+            "retrain_threshold": settings.FEEDBACK_THRESHOLD_FOR_RETRAIN,
+            "next_retrain_at": max(
+                0,
+                settings.FEEDBACK_THRESHOLD_FOR_RETRAIN - self._feedback_since_retrain,
+            ),
+            "last_retrain_at": self._last_retrain_at,
+        }
+
+    async def _trigger_retraining(self) -> bool:
+        """
+        Trigger model retraining.
+
+        In production, this would:
+          1. Export feedback data from MongoDB
+          2. Combine with original training data
+          3. Fine-tune models (background job)
+          4. Evaluate new model on holdout set
+          5. Hot-swap if improved
+        """
+        logger.warning(
+            f"Retraining threshold reached ({self._feedback_since_retrain} feedback samples). "
+            f"Triggering retraining pipeline..."
+        )
+
+        # TODO: Implement actual retraining pipeline
+        # For now, just reset the counter and log
+        self._feedback_since_retrain = 0
+        self._last_retrain_at = datetime.utcnow()
+
+        logger.info("Retraining pipeline placeholder executed. Reset feedback counter.")
+        return True
+
+    def get_training_data(self) -> list[Dict]:
+        """Export feedback data for retraining."""
+        return [
+            fb for fb in self._feedback_store
+            if not fb.get("model_prediction_was_correct", True)
+        ]
+
+
+# Singleton instance
+feedback_service = FeedbackService()

app/services/moderation_service.py

@@ -0,0 +1,104 @@
+"""
+SafeChat — Moderation Service
+
+Orchestrates the full moderation pipeline:
+  1. Classify text for toxicity (ensemble)
+  2. Generate polite alternative (if toxic)
+  3. Return combined result
+
+This is the main entry point called by the API routes.
+"""
+
+import time
+from typing import Dict, Optional
+
+from loguru import logger
+
+from app.models.model_manager import model_manager
+from app.schemas.moderation import ModerationResponse
+
+
+class ModerationService:
+    """
+    Orchestrates toxicity classification + detoxification.
+
+    Stateless service — all state lives in ModelManager.
+    """
+
+    @staticmethod
+    async def moderate(
+        text: str,
+        context: Optional[list[str]] = None,
+        channel_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> ModerationResponse:
+        """
+        Full moderation pipeline for a single message.
+
+        Args:
+            text: Raw message text
+            channel_id: Channel for policy lookup (future use)
+            user_id: Sender ID for tracking (future use)
+
+        Returns:
+            ModerationResponse with toxicity scores and suggestion
+        """
+        start_time = time.perf_counter()
+
+        # Step 1: Classify toxicity
+        classifier = model_manager.classifier
+        if not classifier or not classifier.is_loaded:
+            raise RuntimeError("Toxicity classifier not available")
+
+        classification = classifier.predict(text, context=context)
+
+        # Step 2: Generate suggestion if toxic
+        suggestion = None
+        suggestions = None
+        if classification["is_toxic"]:
+            detoxifier = model_manager.detoxifier
+            if detoxifier:
+                detox_result = detoxifier.detoxify(
+                    text=text,
+                    toxicity_categories=classification["categories"],
+                    target_language=classification["detected_language"],
+                    preserve_intent=True,
+                )
+                suggestion = detox_result["detoxified"]
+                suggestions = detox_result.get("suggestions")
+
+        total_time_ms = int((time.perf_counter() - start_time) * 1000)
+
+        return ModerationResponse(
+            is_toxic=classification["is_toxic"],
+            overall_score=classification["overall_score"],
+            severity=classification["severity"],
+            categories=classification["categories"],
+            detected_language=classification["detected_language"],
+            ensemble_weights=classification["ensemble_weights"],
+            suggestion=suggestion,
+            suggestions=suggestions,
+            model_version=classification["model_version"],
+            inference_time_ms=total_time_ms,
+        )
+
+    @staticmethod
+    async def moderate_batch(
+        texts: list[str],
+        channel_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> list[ModerationResponse]:
+        """Moderate multiple messages. Simple sequential for now."""
+        results = []
+        for text in texts:
+            result = await ModerationService.moderate(
+                text=text,
+                channel_id=channel_id,
+                user_id=user_id,
+            )
+            results.append(result)
+        return results
+
+
+# Singleton service instance
+moderation_service = ModerationService()

app/utils/__init__.py

@@ -0,0 +1 @@
+# Utils package

app/utils/preprocessing.py

@@ -0,0 +1,257 @@
+"""
+Text Preprocessing for SafeChat
+
+Handles text normalization, language detection (with Hinglish/code-mixing support),
+and cleaning for optimal model input.
+"""
+
+import re
+import unicodedata
+from typing import Optional
+
+from loguru import logger
+
+
+# ── Script Detection (for code-mixed language identification) ───────────
+
+# Unicode ranges for Indian scripts
+DEVANAGARI_RANGE = re.compile(r"[\u0900-\u097F]")   # Hindi, Sanskrit, Marathi
+BENGALI_RANGE = re.compile(r"[\u0980-\u09FF]")       # Bengali, Assamese
+TAMIL_RANGE = re.compile(r"[\u0B80-\u0BFF]")
+TELUGU_RANGE = re.compile(r"[\u0C00-\u0C7F]")
+KANNADA_RANGE = re.compile(r"[\u0C80-\u0CFF]")
+MALAYALAM_RANGE = re.compile(r"[\u0D00-\u0D7F]")
+GUJARATI_RANGE = re.compile(r"[\u0A80-\u0AFF]")
+GURMUKHI_RANGE = re.compile(r"[\u0A00-\u0A7F]")       # Punjabi
+ODIA_RANGE = re.compile(r"[\u0B00-\u0B7F]")
+LATIN_RANGE = re.compile(r"[a-zA-Z]")
+
+INDIAN_SCRIPT_MAP = {
+    "devanagari": DEVANAGARI_RANGE,
+    "bengali": BENGALI_RANGE,
+    "tamil": TAMIL_RANGE,
+    "telugu": TELUGU_RANGE,
+    "kannada": KANNADA_RANGE,
+    "malayalam": MALAYALAM_RANGE,
+    "gujarati": GUJARATI_RANGE,
+    "gurmukhi": GURMUKHI_RANGE,
+    "odia": ODIA_RANGE,
+}
+
+
+def detect_language(text: str) -> str:
+    """
+    Detect language with special handling for Indian languages and code-mixing.
+
+    Returns standardized language codes:
+      - 'en'    : English
+      - 'hi'    : Hindi (Devanagari script)
+      - 'hi-en' : Hinglish (code-mixed Hindi + English)
+      - 'bn'    : Bengali
+      - 'ta'    : Tamil
+      - 'te'    : Telugu
+      - 'kn'    : Kannada
+      - 'ml'    : Malayalam
+      - 'gu'    : Gujarati
+      - 'pa'    : Punjabi
+      - 'or'    : Odia
+      - 'indic-en' : Any Indian language mixed with English
+      - 'other' : Fallback
+
+    NOTE: This script-based detection is MORE RELIABLE for code-mixed text
+    than library-based detectors (langdetect/fasttext) which assume monolingual input.
+    """
+    if not text or not text.strip():
+        return "en"
+
+    has_latin = bool(LATIN_RANGE.search(text))
+
+    # Check each Indian script
+    detected_scripts = {}
+    for script_name, pattern in INDIAN_SCRIPT_MAP.items():
+        matches = pattern.findall(text)
+        if matches:
+            detected_scripts[script_name] = len(matches)
+
+    # No Indian script detected
+    if not detected_scripts:
+        if has_latin:
+            # Could be transliterated Hindi (romanized) — check with langdetect
+            return _detect_romanized_indian(text)
+        return "en"
+
+    # Find dominant Indian script
+    dominant_script = max(detected_scripts, key=detected_scripts.get)
+
+    # Map script to language code
+    script_to_lang = {
+        "devanagari": "hi",
+        "bengali": "bn",
+        "tamil": "ta",
+        "telugu": "te",
+        "kannada": "kn",
+        "malayalam": "ml",
+        "gujarati": "gu",
+        "gurmukhi": "pa",
+        "odia": "or",
+    }
+
+    lang = script_to_lang.get(dominant_script, "other")
+
+    # Check for code-mixing (Indian script + significant Latin text)
+    if has_latin and detected_scripts:
+        latin_chars = len(LATIN_RANGE.findall(text))
+        indian_chars = sum(detected_scripts.values())
+        total = latin_chars + indian_chars
+
+        # If more than 20% of script chars are Latin, it's code-mixed
+        if total > 0 and latin_chars / total > 0.2:
+            if lang == "hi":
+                return "hi-en"  # Hinglish
+            return "indic-en"   # Other Indian + English mix
+
+    return lang
+
+
+def _detect_romanized_indian(text: str) -> str:
+    """
+    Detect if Latin-script text is actually romanized Hindi/Hinglish.
+
+    Uses common Hindi words written in Latin script as indicators.
+    """
+    # Common romanized Hindi words (colloquial + formal)
+    hindi_indicators = {
+        # Pronouns and common words
+        "kya", "hai", "hain", "nahi", "nhi", "mat", "aur", "bhi", "toh",
+        "mein", "main", "tera", "mera", "tumhara", "hamara", "apna",
+        "yeh", "woh", "koi", "kuch", "sab", "bahut", "bohot",
+        # Verbs
+        "karo", "karna", "bolo", "bolna", "jao", "jana", "aao", "aana",
+        "dekho", "dekhna", "suno", "sunna", "chalo", "ruk", "ruko",
+        # Slang / colloquial
+        "yaar", "bhai", "dude", "arre", "abey", "oye", "chal",
+        "accha", "theek", "sahi", "galat", "bakwas", "pagal",
+        # Toxicity indicators (important for our use case)
+        "bewakoof", "gadha", "ullu", "kamina", "kamini", "harami",
+        "chutiya", "madarchod", "behenchod", "bhosdike", "gaandu",
+        "saala", "saali", "kutte", "kuttia", "haramkhor",
+        # Expanded romanized abuse cues so short profanity-heavy chats are
+        # still routed through the Hinglish path.
+        "badir", "badirchand", "bakchod", "bakchodi", "bakland",
+        "baklol", "baklund", "bakwaas", "bhenchod", "bhosdi",
+        "bhosdika", "bhosdiki", "bhosde", "bhadwa", "bhadwe",
+        "bsdk", "chakka", "chhakka", "chinal", "chodu", "chut",
+        "chutiye", "chutiyapa", "gaand", "gandu", "ghatiya", "gawar",
+        "haramzada", "haramzade", "hijda", "hijde", "hijra", "jahil",
+        "jhantu", "jhandu", "kanjar", "kanjari", "kaminey", "kutta",
+        "kuttey", "kuttay",
+        "lauda", "lavda", "loda", "lodu", "lund", "lundtopi",
+        "madarchod", "madarchood", "najayaz",
+        "nalayak", "nikamma", "paagal", "randi", "randwa", "randwe",
+        "sala", "saale", "sali", "stupid", "suar", "suwar",
+        "tharki", "tatti", "tatte",
+    }
+
+    # Tokenize defensively so "bhosdike," still counts as a Hinglish cue.
+    words = set(re.findall(r"[a-z]+", text.lower()))
+    hindi_word_count = len(words & hindi_indicators)
+
+    # If 2+ Hindi indicator words found, classify as romanized Hindi/Hinglish
+    if hindi_word_count >= 2:
+        return "hi-en"
+    elif hindi_word_count >= 1 and len(words) <= 5:
+        return "hi-en"
+
+    # For Latin-script text that doesn't look like Hinglish, default to English.
+    # Generic language detectors are noisy on short toxic chat messages and can
+    # misclassify simple English as unrelated languages such as "sw".
+    return "en"
+
+
+def is_indian_language(lang_code: str) -> bool:
+    """Check if a language code represents an Indian language."""
+    return lang_code in {
+        "hi", "hi-en", "bn", "ta", "te", "kn", "ml",
+        "gu", "pa", "or", "indic-en",
+    }
+
+
+# ── Text Cleaning ──────────────────────────────────────────────────────
+
+def clean_text(text: str, preserve_case: bool = False) -> str:
+    """
+    Clean and normalize text for model input.
+
+    Steps:
+      1. Unicode normalization (NFC — canonical composition)
+      2. Remove zero-width characters and control chars (preserve newlines)
+      3. Normalize whitespace
+      4. Optionally lowercase
+
+    NOTE: We do NOT remove emojis or special chars — the models handle them,
+    and they carry semantic meaning for toxicity detection.
+    """
+    if not text:
+        return ""
+
+    # Unicode normalization
+    text = unicodedata.normalize("NFC", text)
+
+    # Remove zero-width chars and most control characters (keep \n, \t)
+    text = re.sub(r"[\u200b-\u200f\u2028-\u202f\u2060-\u2069\ufeff]", "", text)
+
+    # Normalize repeated whitespace (but preserve single newlines)
+    text = re.sub(r"[ \t]+", " ", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+
+    # Strip
+    text = text.strip()
+
+    if not preserve_case:
+        text = text.lower()
+
+    return text
+
+
+def normalize_for_toxicity(text: str) -> str:
+    """
+    Additional normalization specifically for toxicity detection.
+
+    Handles common evasion techniques:
+      - L33t speak: "h4te" → "hate"
+      - Character repetition: "fuckkkk" → "fuck"
+      - Separator insertion: "f.u.c.k" → "fuck"
+      - Mixed scripts for evasion: "fuсk" (Cyrillic с) → "fuck"
+    """
+    # Step 1: Basic cleaning
+    text = clean_text(text, preserve_case=False)
+
+    # Step 2: Reduce character repetition (keep max 2 of same char)
+    text = re.sub(r"(.)\1{2,}", r"\1\1", text)
+
+    # Step 3: Remove separators between single characters
+    # "f.u.c.k" or "f u c k" → "fuck"
+    # Only for Latin characters (don't break Devanagari)
+    text = re.sub(
+        r"(?<=[a-z])[.\-_\s](?=[a-z](?:[.\-_\s][a-z]){2,})",
+        "",
+        text,
+    )
+
+    # Step 4: Common leet speak mappings
+    leet_map = {
+        "0": "o", "1": "i", "3": "e", "4": "a",
+        "5": "s", "7": "t", "8": "b", "@": "a",
+        "$": "s", "!": "i",
+    }
+    # Only apply leet substitution in words that look like leet speak
+    def _deleet(match):
+        word = match.group(0)
+        if any(c in word for c in leet_map):
+            for leet, normal in leet_map.items():
+                word = word.replace(leet, normal)
+        return word
+
+    text = re.sub(r"\b\S+\b", _deleet, text)
+
+    return text

requirements.txt

@@ -1,9 +1,30 @@
-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
+# ============================================
+# SafeChat ML Service — Dependencies
+# ============================================
+
+# --- Core ML ---
+torch>=2.1.0
+transformers>=4.36.0
+tokenizers>=0.15.0
+accelerate>=0.25.0
+sentencepiece>=0.1.99
+protobuf>=4.25.3
+
+# --- FastAPI ---
+fastapi>=0.109.0
+uvicorn[standard]>=0.25.0
+pydantic>=2.5.0
+pydantic-settings>=2.1.0
+
+# --- Language Detection ---
+langdetect>=1.0.9
+
+# --- Text Processing ---
+regex>=2023.12.25
+emoji>=2.9.0
+
+# --- Utilities ---
+python-dotenv>=1.0.0
+loguru>=0.7.2
+httpx>=0.26.0
+numpy>=1.24.0