Deploy backend from GitHub 43a4c2cb381254b3c2fd54acd891b54847bb81d1

Dockerfile

@@ -0,0 +1,40 @@
+# Hugging Face Spaces Docker – Sentinel Backend API
+# HF Spaces requires the app to listen on port 7860.
+#
+# Required Secrets (set in Space Settings -> Repository secrets):
+#   FIREBASE_PROJECT_ID        – Firebase project ID
+#   FIREBASE_CREDENTIALS_JSON  – Full service account JSON as a single-line string
+#   REDIS_URL                  – Upstash Redis URL (rediss://...)
+#   HF_API_KEY                 – Hugging Face API token
+#   GROQ_API_KEY               – Groq API key
+#   CORS_ORIGINS               – Comma-separated allowed origins (your Vercel URL)
+#   QDRANT_URL / QDRANT_API_KEY – Optional, for vector clustering signal
+#   SENTRY_DSN                 – Optional error tracking
+
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# System dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# Python dependencies
+COPY backend/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Application code
+COPY backend/ ./backend/
+
+# Non-root user (HF Spaces security best practice)
+RUN useradd -m appuser && chown -R appuser:appuser /app
+USER appuser
+
+# HF Spaces requires port 7860
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+CMD ["uvicorn", "backend.app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,12 +1,22 @@
 ---
-title: Sentinel LLM Misuse Detector
-emoji: 🛡️
-colorFrom: red
-colorTo: blue
-sdk: static
+title: Sentinel Backend API
+emoji: 🔒
+colorFrom: blue
+colorTo: red
+sdk: docker
 pinned: false
+app_port: 7860
 ---
 
-# Sentinel - LLM Misuse Detection System
+# Sentinel Backend API
 
-Frontend for the Sentinel system for detecting misuse of Large Language Models.
+FastAPI backend for the Sentinel LLM Misuse Detection System.
+Exposes a REST API on port 7860.
+
+## Required Secrets (Space Settings → Repository secrets)
+- `FIREBASE_PROJECT_ID` – Firebase project ID
+- `FIREBASE_CREDENTIALS_JSON` – Service account JSON (single-line string)
+- `REDIS_URL` – Upstash Redis URL
+- `HF_API_KEY` – Hugging Face API token
+- `GROQ_API_KEY` – Groq API key
+- `CORS_ORIGINS` – Your Vercel frontend URL

backend/app/api/auth_routes.py

@@ -0,0 +1,40 @@
+"""
+Authentication routes for user registration and login.
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+
+from backend.app.api.models import AuthRequest, TokenResponse
+from backend.app.core.auth import hash_password, verify_password, create_access_token
+from backend.app.db.session import get_session
+from backend.app.models.schemas import User
+
+router = APIRouter(prefix="/api/auth", tags=["authentication"])
+
+
+@router.post("/register", response_model=TokenResponse, status_code=201)
+async def register(req: AuthRequest, session: AsyncSession = Depends(get_session)):
+    """Register a new user."""
+    stmt = select(User).where(User.email == req.email)
+    existing = await session.execute(stmt)
+    if existing.scalar_one_or_none():
+        raise HTTPException(status_code=409, detail="Email already registered")
+
+    user = User(email=req.email, hashed_password=hash_password(req.password))
+    session.add(user)
+    await session.commit()
+    token = create_access_token(subject=user.id)
+    return TokenResponse(access_token=token)
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(req: AuthRequest, session: AsyncSession = Depends(get_session)):
+    """Login with email and password."""
+    stmt = select(User).where(User.email == req.email)
+    result = await session.execute(stmt)
+    user = result.scalar_one_or_none()
+    if not user or not verify_password(req.password, user.hashed_password):
+        raise HTTPException(status_code=401, detail="Invalid credentials")
+    token = create_access_token(subject=user.id)
+    return TokenResponse(access_token=token)

backend/app/api/models.py

@@ -0,0 +1,45 @@
+"""
+Pydantic request/response models for the API.
+Auth is handled entirely by Firebase on the frontend — no auth models here.
+"""
+from pydantic import BaseModel, Field
+from typing import List, Optional
+
+
+class AnalyzeRequest(BaseModel):
+    text: str = Field(..., min_length=10, max_length=50000, description="Text to analyze")
+
+
+class BulkAnalyzeRequest(BaseModel):
+    texts: List[str] = Field(..., min_length=1, max_length=20)
+
+
+class SignalScores(BaseModel):
+    p_ai: Optional[float] = Field(None, description="AI-generation probability (ensemble)")
+    s_perp: Optional[float] = Field(None, description="Normalized perplexity score")
+    s_embed_cluster: Optional[float] = Field(None, description="Embedding cluster outlier score")
+    p_ext: Optional[float] = Field(None, description="Extremism/harm probability")
+    s_styl: Optional[float] = Field(None, description="Stylometry anomaly score")
+    p_watermark: Optional[float] = Field(None, description="Watermark detection (negative signal)")
+
+
+class ExplainabilityItem(BaseModel):
+    signal: str
+    value: float
+    weight: float
+    contribution: float
+    description: str
+
+
+class AnalyzeResponse(BaseModel):
+    id: str
+    status: str
+    threat_score: Optional[float] = None
+    signals: Optional[SignalScores] = None
+    explainability: Optional[List[ExplainabilityItem]] = None
+    processing_time_ms: Optional[int] = None
+
+
+class HealthResponse(BaseModel):
+    status: str = "ok"
+    version: str = "1.0.0"

backend/app/api/routes.py

@@ -0,0 +1,207 @@
+"""
+Main API routes for the LLM Misuse Detection system.
+Endpoints: /api/analyze, /api/analyze/bulk, /api/results/{id}
+Persistence: Firestore (replaces PostgreSQL)
+"""
+import hashlib
+import time
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from backend.app.api.models import (
+    AnalyzeRequest, AnalyzeResponse, BulkAnalyzeRequest,
+    SignalScores, ExplainabilityItem,
+)
+from backend.app.core.auth import get_current_user
+from backend.app.core.config import settings
+from backend.app.core.redis import check_rate_limit, get_cached, set_cached
+from backend.app.db.firestore import get_db
+from backend.app.models.schemas import AnalysisResult
+from backend.app.services.ensemble import compute_ensemble
+from backend.app.services.hf_service import detect_ai_text, get_embeddings, detect_harm
+from backend.app.services.groq_service import compute_perplexity
+from backend.app.services.stylometry import compute_stylometry_score
+from backend.app.services.vector_db import compute_cluster_score, upsert_embedding
+from backend.app.core.logging import get_logger
+
+import json
+
+logger = get_logger(__name__)
+router = APIRouter(prefix="/api", tags=["analysis"])
+
+COLLECTION = "analysis_results"
+
+
+async def _analyze_text(text: str, user_id: str = None) -> dict:
+    """Core analysis pipeline for a single text."""
+    start_time = time.time()
+    text_hash = hashlib.sha256(text.encode()).hexdigest()
+
+    # Check cache
+    cached = await get_cached(f"analysis:{text_hash}")
+    if cached:
+        return json.loads(cached)
+
+    # Step 1: AI detection
+    try:
+        p_ai = await detect_ai_text(text)
+    except Exception:
+        p_ai = None
+
+    # Step 2: Perplexity (cost-gated)
+    s_perp = None
+    if p_ai is not None and p_ai > settings.PERPLEXITY_THRESHOLD:
+        s_perp = await compute_perplexity(text)
+
+    # Step 3: Embeddings + cluster score
+    s_embed_cluster = None
+    try:
+        embeddings = await get_embeddings(text)
+        s_embed_cluster = await compute_cluster_score(embeddings)
+        await upsert_embedding(text_hash[:16], embeddings, {"text_preview": text[:200]})
+    except Exception:
+        pass
+
+    # Step 4: Harm/extremism
+    p_ext = await detect_harm(text)
+
+    # Step 5: Stylometry
+    s_styl = compute_stylometry_score(text)
+
+    # Step 6: Watermark placeholder
+    p_watermark = None
+
+    # Step 7: Ensemble
+    ensemble_result = compute_ensemble(
+        p_ai=p_ai,
+        s_perp=s_perp,
+        s_embed_cluster=s_embed_cluster,
+        p_ext=p_ext,
+        s_styl=s_styl,
+        p_watermark=p_watermark,
+    )
+
+    processing_time_ms = int((time.time() - start_time) * 1000)
+
+    result = {
+        "text_hash": text_hash,
+        "p_ai": p_ai,
+        "s_perp": s_perp,
+        "s_embed_cluster": s_embed_cluster,
+        "p_ext": p_ext,
+        "s_styl": s_styl,
+        "p_watermark": p_watermark,
+        "threat_score": ensemble_result["threat_score"],
+        "explainability": ensemble_result["explainability"],
+        "processing_time_ms": processing_time_ms,
+    }
+
+    # Cache
+    try:
+        await set_cached(f"analysis:{text_hash}", json.dumps(result), ttl=600)
+    except Exception:
+        pass
+
+    # Persist to Firestore
+    try:
+        db = get_db()
+        doc = AnalysisResult(
+            input_text=text,
+            text_hash=text_hash,
+            user_id=user_id,
+            p_ai=p_ai,
+            s_perp=s_perp,
+            s_embed_cluster=s_embed_cluster,
+            p_ext=p_ext,
+            s_styl=s_styl,
+            p_watermark=p_watermark,
+            threat_score=ensemble_result["threat_score"],
+            explainability=ensemble_result["explainability"],
+            status="done",
+            completed_at=datetime.now(timezone.utc),
+            processing_time_ms=processing_time_ms,
+        )
+        db.collection(COLLECTION).document(doc.id).set(doc.to_dict())
+        result["id"] = doc.id
+    except Exception as e:
+        logger.warning("Firestore persist failed", error=str(e))
+        result["id"] = text_hash
+
+    return result
+
+
+@router.post("/analyze", response_model=AnalyzeResponse)
+async def analyze_text(request: AnalyzeRequest):
+    """Analyze a single text for LLM misuse indicators."""
+    rate_ok = await check_rate_limit("analyze:global")
+    if not rate_ok:
+        raise HTTPException(status_code=429, detail="Rate limit exceeded")
+
+    result = await _analyze_text(request.text)
+
+    return AnalyzeResponse(
+        id=result.get("id", result.get("text_hash", "")),
+        status="done",
+        threat_score=result["threat_score"],
+        signals=SignalScores(
+            p_ai=result["p_ai"],
+            s_perp=result["s_perp"],
+            s_embed_cluster=result["s_embed_cluster"],
+            p_ext=result["p_ext"],
+            s_styl=result["s_styl"],
+            p_watermark=result["p_watermark"],
+        ),
+        explainability=[
+            ExplainabilityItem(**e) for e in result["explainability"]
+        ],
+        processing_time_ms=result["processing_time_ms"],
+    )
+
+
+@router.post("/analyze/bulk")
+async def bulk_analyze(request: BulkAnalyzeRequest):
+    """Analyze multiple texts (max 20)."""
+    rate_ok = await check_rate_limit("analyze:bulk:global", limit=5)
+    if not rate_ok:
+        raise HTTPException(status_code=429, detail="Rate limit exceeded")
+
+    results = []
+    for text in request.texts:
+        try:
+            r = await _analyze_text(text)
+            results.append({"status": "done", **r})
+        except Exception as e:
+            results.append({"status": "error", "error": str(e)})
+    return {"results": results}
+
+
+@router.get("/results/{result_id}")
+async def get_result(
+    result_id: str,
+    user_id: str = Depends(get_current_user),
+):
+    """Fetch a previously computed analysis result by Firestore document ID."""
+    db = get_db()
+    doc_ref = db.collection(COLLECTION).document(result_id)
+    doc = doc_ref.get()
+    if not doc.exists:
+        raise HTTPException(status_code=404, detail="Result not found")
+    data = doc.to_dict()
+    return AnalyzeResponse(
+        id=data["id"],
+        status=data["status"],
+        threat_score=data.get("threat_score"),
+        signals=SignalScores(
+            p_ai=data.get("p_ai"),
+            s_perp=data.get("s_perp"),
+            s_embed_cluster=data.get("s_embed_cluster"),
+            p_ext=data.get("p_ext"),
+            s_styl=data.get("s_styl"),
+            p_watermark=data.get("p_watermark"),
+        ),
+        explainability=[
+            ExplainabilityItem(**e) for e in (data.get("explainability") or [])
+        ],
+        processing_time_ms=data.get("processing_time_ms"),
+    )

backend/app/core/auth.py

@@ -0,0 +1,40 @@
+"""
+Firebase Authentication utilities.
+Verifies Firebase ID tokens issued by the frontend (Firebase Auth SDK).
+
+Env vars: FIREBASE_PROJECT_ID (used implicitly by firebase-admin)
+"""
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from firebase_admin import auth as firebase_auth
+
+security_scheme = HTTPBearer()
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security_scheme),
+) -> str:
+    """
+    Dependency: extracts and verifies the Firebase ID token from the
+    Authorization: Bearer <id_token> header.
+    Returns the Firebase UID of the authenticated user.
+    """
+    id_token = credentials.credentials
+    try:
+        decoded = firebase_auth.verify_id_token(id_token)
+    except firebase_auth.ExpiredIdTokenError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Firebase ID token has expired. Please re-authenticate.",
+        )
+    except firebase_auth.InvalidIdTokenError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid Firebase ID token.",
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"Token verification failed: {str(e)}",
+        )
+    return decoded["uid"]

backend/app/core/config.py

@@ -0,0 +1,76 @@
+"""
+Configuration module for the LLM Misuse Detection backend.
+Reads all settings from environment variables.
+
+Env vars: FIREBASE_PROJECT_ID, FIREBASE_CREDENTIALS_JSON,
+          REDIS_URL, HF_API_KEY, GROQ_API_KEY,
+          SENTRY_DSN, CORS_ORIGINS
+"""
+from pydantic_settings import BaseSettings
+from typing import Optional
+from typing import List
+
+
+class Settings(BaseSettings):
+    # Application
+    APP_NAME: str = "LLM Misuse Detector"
+    DEBUG: bool = False
+
+    # Firebase
+    # Set FIREBASE_PROJECT_ID to your Firebase project ID.
+    # Set FIREBASE_CREDENTIALS_JSON to the *contents* of your service account
+    # JSON (as a single-line escaped string), OR set GOOGLE_APPLICATION_CREDENTIALS
+    # to the path of the JSON file on disk. The latter is preferred for local dev.
+    FIREBASE_PROJECT_ID: str = ""
+    FIREBASE_CREDENTIALS_JSON: Optional[str] = None  # JSON string (for Render env vars)
+
+    # Redis
+    REDIS_URL: str = "redis://localhost:6379/0"
+
+    # CORS
+    CORS_ORIGINS: str = "http://localhost:3000"
+
+    # HuggingFace
+    HF_API_KEY: str = ""
+    HF_DETECTOR_PRIMARY: str = "https://api-inference.huggingface.co/models/desklib/ai-text-detector-v1.01"
+    HF_DETECTOR_FALLBACK: str = "https://api-inference.huggingface.co/models/fakespot-ai/roberta-base-ai-text-detection-v1"
+    HF_EMBEDDINGS_PRIMARY: str = "https://api-inference.huggingface.co/models/sentence-transformers/all-mpnet-base-v2"
+    HF_EMBEDDINGS_FALLBACK: str = "https://api-inference.huggingface.co/models/sentence-transformers/all-MiniLM-L6-v2"
+    HF_HARM_CLASSIFIER: str = "https://api-inference.huggingface.co/models/facebook/roberta-hate-speech-dynabench-r4-target"
+
+    # Groq
+    GROQ_API_KEY: str = ""
+    GROQ_MODEL: str = "llama-3.3-70b-versatile"
+    GROQ_BASE_URL: str = "https://api.groq.com/openai/v1"
+
+    # Vector DB (Qdrant)
+    QDRANT_URL: str = "http://localhost:6333"
+    QDRANT_API_KEY: Optional[str] = None
+    QDRANT_COLLECTION: str = "sentinel_embeddings"
+
+    # Observability
+    SENTRY_DSN: str = ""
+    LOG_LEVEL: str = "INFO"
+
+    # Ensemble weights (defaults)
+    WEIGHT_AI_DETECT: float = 0.30
+    WEIGHT_PERPLEXITY: float = 0.20
+    WEIGHT_EMBEDDING: float = 0.15
+    WEIGHT_EXTREMISM: float = 0.20
+    WEIGHT_STYLOMETRY: float = 0.10
+    WEIGHT_WATERMARK: float = 0.05
+
+    # Cost control
+    PERPLEXITY_THRESHOLD: float = 0.3
+
+    # Rate limiting
+    RATE_LIMIT_PER_MINUTE: int = 30
+
+    @property
+    def cors_origins_list(self) -> List[str]:
+        return [o.strip() for o in self.CORS_ORIGINS.split(",")]
+
+    model_config = {"env_file": ".env", "extra": "ignore"}
+
+
+settings = Settings()

backend/app/core/logging.py

@@ -0,0 +1,46 @@
+"""
+Structured logging configuration with PII redaction.
+Uses structlog for JSON-formatted log output.
+"""
+import logging
+import re
+import structlog
+
+
+_EMAIL_RE = re.compile(r"[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+")
+_PHONE_RE = re.compile(r"\b\d{3}[-.]?\d{3}[-.]?\d{4}\b")
+
+
+def _redact_pii(_logger, _method, event_dict):
+    """Redact emails and phone numbers from log messages."""
+    msg = event_dict.get("event", "")
+    if isinstance(msg, str):
+        msg = _EMAIL_RE.sub("[REDACTED_EMAIL]", msg)
+        msg = _PHONE_RE.sub("[REDACTED_PHONE]", msg)
+        event_dict["event"] = msg
+    return event_dict
+
+
+def setup_logging(log_level: str = "INFO"):
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.stdlib.filter_by_level,
+            structlog.stdlib.add_logger_name,
+            structlog.stdlib.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            _redact_pii,
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+    logging.basicConfig(format="%(message)s", level=getattr(logging, log_level))
+
+
+def get_logger(name: str = __name__):
+    return structlog.get_logger(name)

backend/app/core/redis.py

@@ -0,0 +1,51 @@
+"""
+Redis-based rate limiter using a sliding window approach.
+Env vars: REDIS_URL, RATE_LIMIT_PER_MINUTE
+"""
+import time
+from typing import Optional
+
+import redis.asyncio as aioredis
+
+from backend.app.core.config import settings
+
+_redis_client: Optional[aioredis.Redis] = None
+
+
+async def get_redis() -> aioredis.Redis:
+    global _redis_client
+    if _redis_client is None:
+        _redis_client = aioredis.from_url(
+            settings.REDIS_URL, decode_responses=True, socket_connect_timeout=5
+        )
+    return _redis_client
+
+
+async def check_rate_limit(key: str, limit: int = 0, window: int = 60) -> bool:
+    """
+    Returns True if under limit, False if rate-limited.
+    Uses sorted set with timestamps for sliding window.
+    """
+    if limit <= 0:
+        limit = settings.RATE_LIMIT_PER_MINUTE
+    r = await get_redis()
+    now = time.time()
+    window_start = now - window
+    pipe = r.pipeline()
+    pipe.zremrangebyscore(key, 0, window_start)
+    pipe.zadd(key, {str(now): now})
+    pipe.zcard(key)
+    pipe.expire(key, window + 1)
+    results = await pipe.execute()
+    count = results[2]
+    return count <= limit
+
+
+async def get_cached(key: str) -> Optional[str]:
+    r = await get_redis()
+    return await r.get(key)
+
+
+async def set_cached(key: str, value: str, ttl: int = 300):
+    r = await get_redis()
+    await r.setex(key, ttl, value)

backend/app/db/firestore.py

@@ -0,0 +1,54 @@
+"""
+Firebase Admin SDK initialisation and Firestore client.
+
+Priority for credentials (in order):
+  1. FIREBASE_CREDENTIALS_JSON env var  – JSON string of the service account
+     (paste the whole file contents as a single escaped string in Render/CI)
+  2. GOOGLE_APPLICATION_CREDENTIALS env var – path to the JSON file on disk
+     (recommended for local development)
+
+Call `get_db()` anywhere to obtain the Firestore async client.
+"""
+import json
+import os
+
+import firebase_admin
+from firebase_admin import credentials, firestore
+
+from backend.app.core.config import settings
+
+_app: firebase_admin.App | None = None
+_db = None
+
+
+def init_firebase() -> None:
+    """Initialise the Firebase Admin SDK (idempotent)."""
+    global _app, _db
+    if _app is not None:
+        return
+
+    if settings.FIREBASE_CREDENTIALS_JSON:
+        # Credentials supplied as a JSON string (production / Render)
+        cred_dict = json.loads(settings.FIREBASE_CREDENTIALS_JSON)
+        cred = credentials.Certificate(cred_dict)
+    elif os.getenv("GOOGLE_APPLICATION_CREDENTIALS"):
+        # Path to JSON file on disk (local dev)
+        cred = credentials.ApplicationDefault()
+    else:
+        raise RuntimeError(
+            "Firebase credentials not configured. "
+            "Set FIREBASE_CREDENTIALS_JSON or GOOGLE_APPLICATION_CREDENTIALS."
+        )
+
+    _app = firebase_admin.initialize_app(
+        cred,
+        {"projectId": settings.FIREBASE_PROJECT_ID},
+    )
+    _db = firestore.client()
+
+
+def get_db():
+    """Return the Firestore client. Call init_firebase() first."""
+    if _db is None:
+        raise RuntimeError("Firestore not initialised. Call init_firebase() on startup.")
+    return _db

backend/app/db/session.py

@@ -0,0 +1,21 @@
+"""
+Database connection and session management.
+Env vars: DATABASE_URL
+"""
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
+
+from backend.app.core.config import settings
+
+engine = create_async_engine(settings.DATABASE_URL, echo=settings.DEBUG, pool_size=10)
+async_session = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+async def get_session() -> AsyncSession:
+    async with async_session() as session:
+        yield session
+
+
+async def init_db():
+    from backend.app.models.schemas import Base
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)

backend/app/main.py

@@ -0,0 +1,99 @@
+"""
+FastAPI main application entry point.
+Configures CORS, secure headers, routes, and observability.
+
+Auth: Firebase Auth (frontend issues ID tokens; backend verifies via firebase-admin)
+DB:   Firestore (via firebase-admin)
+
+Env vars: All from core/config.py
+Run: uvicorn backend.app.main:app --host 0.0.0.0 --port 8000
+"""
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from prometheus_client import Counter, Histogram, generate_latest, CONTENT_TYPE_LATEST
+
+from backend.app.core.config import settings
+from backend.app.core.logging import setup_logging, get_logger
+from backend.app.api.routes import router as analysis_router
+from backend.app.api.models import HealthResponse
+from backend.app.db.firestore import init_firebase
+
+# Sentry (optional)
+if settings.SENTRY_DSN:
+    import sentry_sdk
+    from sentry_sdk.integrations.fastapi import FastApiIntegration
+    sentry_sdk.init(dsn=settings.SENTRY_DSN, integrations=[FastApiIntegration()])
+
+setup_logging(settings.LOG_LEVEL)
+logger = get_logger(__name__)
+
+# Prometheus metrics
+REQUEST_COUNT = Counter("http_requests_total", "Total HTTP requests", ["method", "endpoint", "status"])
+REQUEST_LATENCY = Histogram("http_request_duration_seconds", "Request latency", ["method", "endpoint"])
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.info("Starting LLM Misuse Detection API")
+    try:
+        init_firebase()
+        logger.info("Firebase + Firestore initialised")
+    except Exception as e:
+        logger.warning("Firebase init failed – auth and DB will be unavailable", error=str(e))
+    yield
+    logger.info("Shutting down")
+
+
+app = FastAPI(
+    title=settings.APP_NAME,
+    version="1.0.0",
+    description="Production system for detecting and mitigating LLM misuse in information operations",
+    lifespan=lifespan,
+)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.middleware("http")
+async def add_security_headers(request: Request, call_next):
+    response: Response = await call_next(request)
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    response.headers["X-Frame-Options"] = "DENY"
+    response.headers["X-XSS-Protection"] = "1; mode=block"
+    response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
+    response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+    response.headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=()"
+    return response
+
+
+@app.middleware("http")
+async def metrics_middleware(request: Request, call_next):
+    import time
+    start = time.time()
+    response = await call_next(request)
+    duration = time.time() - start
+    REQUEST_COUNT.labels(request.method, request.url.path, response.status_code).inc()
+    REQUEST_LATENCY.labels(request.method, request.url.path).observe(duration)
+    return response
+
+
+app.include_router(analysis_router)
+
+
+@app.get("/health", response_model=HealthResponse)
+async def health():
+    return HealthResponse()
+
+
+@app.get("/metrics")
+async def metrics():
+    return Response(content=generate_latest(), media_type=CONTENT_TYPE_LATEST)

backend/app/models/schemas.py

@@ -0,0 +1,56 @@
+"""
+Data models for the LLM Misuse Detection system.
+Plain dataclasses – no ORM layer (Firestore is schemaless).
+"""
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Optional, Any
+import uuid
+
+
+@dataclass
+class AnalysisResult:
+    """Mirrors the Firestore document structure stored under 'analysis_results'."""
+    input_text: str
+    text_hash: str
+
+    # Per-signal scores
+    p_ai: Optional[float] = None
+    s_perp: Optional[float] = None
+    s_embed_cluster: Optional[float] = None
+    p_ext: Optional[float] = None
+    s_styl: Optional[float] = None
+    p_watermark: Optional[float] = None
+
+    # Ensemble
+    threat_score: Optional[float] = None
+    explainability: Optional[Any] = None
+
+    # Metadata
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    user_id: Optional[str] = None
+    status: str = "done"
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    completed_at: Optional[datetime] = None
+    processing_time_ms: Optional[int] = None
+
+    def to_dict(self) -> dict:
+        """Serialise to a plain dict suitable for Firestore."""
+        return {
+            "id": self.id,
+            "user_id": self.user_id,
+            "input_text": self.input_text[:10000],
+            "text_hash": self.text_hash,
+            "p_ai": self.p_ai,
+            "s_perp": self.s_perp,
+            "s_embed_cluster": self.s_embed_cluster,
+            "p_ext": self.p_ext,
+            "s_styl": self.s_styl,
+            "p_watermark": self.p_watermark,
+            "threat_score": self.threat_score,
+            "explainability": self.explainability,
+            "status": self.status,
+            "created_at": self.created_at,
+            "completed_at": self.completed_at,
+            "processing_time_ms": self.processing_time_ms,
+        }

backend/app/services/ensemble.py

@@ -0,0 +1,115 @@
+"""
+Ensemble scoring module.
+Combines all signal scores into a final threat_score with explainability.
+
+Configurable weights via environment variables.
+"""
+from typing import Optional, List, Dict
+from backend.app.core.config import settings
+
+
+def compute_ensemble(
+    p_ai: Optional[float] = None,
+    s_perp: Optional[float] = None,
+    s_embed_cluster: Optional[float] = None,
+    p_ext: Optional[float] = None,
+    s_styl: Optional[float] = None,
+    p_watermark: Optional[float] = None,
+) -> Dict:
+    """
+    Deterministic ensemble scoring.
+    Returns threat_score (0-1) and explainability breakdown.
+    """
+    signals = {
+        "p_ai": {"value": p_ai, "weight": settings.WEIGHT_AI_DETECT, "desc": "AI-generated text probability"},
+        "s_perp": {"value": s_perp, "weight": settings.WEIGHT_PERPLEXITY, "desc": "Perplexity anomaly score"},
+        "s_embed_cluster": {"value": s_embed_cluster, "weight": settings.WEIGHT_EMBEDDING, "desc": "Embedding cluster outlier score"},
+        "p_ext": {"value": p_ext, "weight": settings.WEIGHT_EXTREMISM, "desc": "Extremism/harm probability"},
+        "s_styl": {"value": s_styl, "weight": settings.WEIGHT_STYLOMETRY, "desc": "Stylometry anomaly score"},
+        "p_watermark": {"value": p_watermark, "weight": settings.WEIGHT_WATERMARK, "desc": "Watermark detection (negative signal)"},
+    }
+
+    total_weight = 0.0
+    weighted_sum = 0.0
+    explainability: List[Dict] = []
+
+    for name, sig in signals.items():
+        value = sig["value"]
+        if value is None:
+            continue
+
+        weight = sig["weight"]
+
+        # Watermark is a negative signal: if detected, reduce threat
+        if name == "p_watermark":
+            contribution = -value * weight
+        else:
+            contribution = value * weight
+
+        weighted_sum += contribution
+        total_weight += weight
+
+        explainability.append({
+            "signal": name,
+            "value": round(value, 4),
+            "weight": round(weight, 4),
+            "contribution": round(contribution, 4),
+            "description": sig["desc"],
+        })
+
+    # Normalize
+    if total_weight > 0:
+        threat_score = max(0.0, min(1.0, weighted_sum / total_weight))
+    else:
+        threat_score = 0.0
+
+    return {
+        "threat_score": round(threat_score, 4),
+        "explainability": explainability,
+    }
+
+
+def calibrate_weights(sample_results: List[Dict]) -> Dict[str, float]:
+    """
+    Auto-calibrate weights based on sample dataset.
+    This does NOT train any model - just adjusts weight vector using
+    signal variance and correlation heuristics.
+    Returns updated weight dict.
+    """
+    if not sample_results:
+        return {
+            "WEIGHT_AI_DETECT": settings.WEIGHT_AI_DETECT,
+            "WEIGHT_PERPLEXITY": settings.WEIGHT_PERPLEXITY,
+            "WEIGHT_EMBEDDING": settings.WEIGHT_EMBEDDING,
+            "WEIGHT_EXTREMISM": settings.WEIGHT_EXTREMISM,
+            "WEIGHT_STYLOMETRY": settings.WEIGHT_STYLOMETRY,
+            "WEIGHT_WATERMARK": settings.WEIGHT_WATERMARK,
+        }
+
+    # Compute variance per signal to weight higher-variance signals more
+    signal_names = ["p_ai", "s_perp", "s_embed_cluster", "p_ext", "s_styl", "p_watermark"]
+    variances = {}
+    for sig in signal_names:
+        vals = [r.get(sig) for r in sample_results if r.get(sig) is not None]
+        if len(vals) >= 2:
+            mean = sum(vals) / len(vals)
+            var = sum((v - mean) ** 2 for v in vals) / len(vals)
+            variances[sig] = var
+        else:
+            variances[sig] = 0.01
+
+    # Normalize variances to sum to 1
+    total_var = sum(variances.values())
+    if total_var > 0:
+        weights = {k: v / total_var for k, v in variances.items()}
+    else:
+        weights = {k: 1.0 / len(signal_names) for k in signal_names}
+
+    return {
+        "WEIGHT_AI_DETECT": round(weights.get("p_ai", 0.3), 4),
+        "WEIGHT_PERPLEXITY": round(weights.get("s_perp", 0.2), 4),
+        "WEIGHT_EMBEDDING": round(weights.get("s_embed_cluster", 0.15), 4),
+        "WEIGHT_EXTREMISM": round(weights.get("p_ext", 0.2), 4),
+        "WEIGHT_STYLOMETRY": round(weights.get("s_styl", 0.1), 4),
+        "WEIGHT_WATERMARK": round(weights.get("p_watermark", 0.05), 4),
+    }

backend/app/services/groq_service.py

@@ -0,0 +1,106 @@
+"""
+Groq API client for perplexity scoring using Llama models.
+Computes token-level log-probabilities to produce perplexity scores.
+
+Env vars: GROQ_API_KEY, GROQ_MODEL, GROQ_BASE_URL
+"""
+import math
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
+from typing import Optional
+
+from backend.app.core.config import settings
+from backend.app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+_TIMEOUT = httpx.Timeout(60.0, connect=10.0)
+
+
+class GroqServiceError(Exception):
+    pass
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=1, min=2, max=15),
+    retry=retry_if_exception_type((httpx.HTTPStatusError, httpx.ConnectError)),
+)
+async def _groq_chat_completion(text: str) -> dict:
+    """Call Groq chat completion with logprobs enabled.
+    Note: Input is truncated to 2000 chars for cost control. Perplexity
+    scores for longer texts reflect only the first 2000 characters.
+    """
+    headers = {
+        "Authorization": f"Bearer {settings.GROQ_API_KEY}",
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "model": settings.GROQ_MODEL,
+        "messages": [
+            {"role": "system", "content": "Repeat the following text exactly:"},
+            {"role": "user", "content": text[:2000]},  # Truncated for cost control
+        ],
+        "max_tokens": 1,
+        "temperature": 0,
+        "logprobs": True,
+        "top_logprobs": 1,
+    }
+    async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+        resp = await client.post(
+            f"{settings.GROQ_BASE_URL}/chat/completions",
+            json=payload,
+            headers=headers,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def compute_perplexity(text: str) -> Optional[float]:
+    """
+    Compute a normalized perplexity score using Groq Llama endpoints.
+    Returns a score between 0 and 1 where higher = more anomalous.
+
+    Strategy: Use logprobs from a single completion call to estimate
+    the model's surprise at the input text.
+    """
+    try:
+        result = await _groq_chat_completion(text)
+        choices = result.get("choices", [])
+        if not choices:
+            return None
+
+        logprobs_data = choices[0].get("logprobs", {})
+        if not logprobs_data:
+            # If logprobs not available, use usage-based heuristic
+            usage = result.get("usage", {})
+            prompt_tokens = usage.get("prompt_tokens", 0)
+            if prompt_tokens > 0:
+                text_len = len(text.split())
+                ratio = prompt_tokens / max(text_len, 1)
+                # Normalize: high token ratio suggests unusual tokenization
+                return min(1.0, max(0.0, (ratio - 1.0) / 2.0))
+            return None
+
+        content = logprobs_data.get("content", [])
+        if not content:
+            return None
+
+        # Compute perplexity from log-probabilities
+        log_probs = []
+        for token_info in content:
+            lp = token_info.get("logprob")
+            if lp is not None:
+                log_probs.append(lp)
+
+        if not log_probs:
+            return None
+
+        avg_log_prob = sum(log_probs) / len(log_probs)
+        perplexity = math.exp(-avg_log_prob)
+        # Normalize to 0-1 range (perplexity of 1 = perfectly predicted, >100 = very unusual)
+        normalized = min(1.0, max(0.0, (math.log(perplexity + 1) / math.log(101))))
+        return round(normalized, 4)
+    except Exception as e:
+        logger.warning("Groq perplexity computation failed", error=str(e))
+        return None

backend/app/services/hf_service.py

@@ -0,0 +1,102 @@
+"""
+Hugging Face Inference API client.
+Calls AI-text detectors and embedding models hosted on HF Inference Endpoints.
+Implements retry/backoff and circuit-breaker behavior.
+
+Env vars: HF_API_KEY, HF_DETECTOR_PRIMARY, HF_DETECTOR_FALLBACK,
+          HF_EMBEDDINGS_PRIMARY, HF_EMBEDDINGS_FALLBACK, HF_HARM_CLASSIFIER
+"""
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
+from typing import List, Optional, Dict, Any
+
+from backend.app.core.config import settings
+from backend.app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+_HEADERS = lambda: {"Authorization": f"Bearer {settings.HF_API_KEY}"}
+_TIMEOUT = httpx.Timeout(30.0, connect=10.0)
+
+
+class HFServiceError(Exception):
+    pass
+
+
+@retry(
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=1, min=1, max=10),
+    retry=retry_if_exception_type((httpx.HTTPStatusError, httpx.ConnectError)),
+)
+async def _hf_request(url: str, payload: dict) -> Any:
+    async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+        resp = await client.post(url, json=payload, headers=_HEADERS())
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def detect_ai_text(text: str) -> float:
+    """
+    Call AI text detector ensemble (primary + fallback).
+    Returns probability that text is AI-generated (0-1).
+    """
+    scores = []
+    for url in [settings.HF_DETECTOR_PRIMARY, settings.HF_DETECTOR_FALLBACK]:
+        try:
+            result = await _hf_request(url, {"inputs": text})
+            # HF classification returns [[{label, score}, ...]]
+            if isinstance(result, list) and len(result) > 0:
+                labels = result[0] if isinstance(result[0], list) else result
+                for item in labels:
+                    label = item.get("label", "").lower()
+                    if label in ("ai", "fake", "machine", "ai-generated", "generated"):
+                        scores.append(item["score"])
+                        break
+                else:
+                    # If no matching label found, use first score as proxy
+                    if labels:
+                        scores.append(labels[0].get("score", 0.5))
+        except Exception as e:
+            logger.warning("HF detector call failed", url=url, error=str(e))
+    if not scores:
+        raise HFServiceError("All AI detectors failed")
+    return sum(scores) / len(scores)
+
+
+async def get_embeddings(text: str) -> List[float]:
+    """Get text embeddings from HF sentence-transformers endpoint."""
+    for url in [settings.HF_EMBEDDINGS_PRIMARY, settings.HF_EMBEDDINGS_FALLBACK]:
+        try:
+            result = await _hf_request(url, {"inputs": text})
+            if isinstance(result, list) and len(result) > 0:
+                # Returns a list of floats (embedding vector)
+                if isinstance(result[0], float):
+                    return result
+                if isinstance(result[0], list):
+                    return result[0]
+            return result
+        except Exception as e:
+            logger.warning("HF embeddings call failed", url=url, error=str(e))
+    raise HFServiceError("All embedding endpoints failed")
+
+
+async def detect_harm(text: str) -> float:
+    """
+    Call harm/extremism classifier on HF.
+    Returns probability of harmful/extremist content (0-1).
+    """
+    try:
+        result = await _hf_request(settings.HF_HARM_CLASSIFIER, {"inputs": text})
+        if isinstance(result, list) and len(result) > 0:
+            labels = result[0] if isinstance(result[0], list) else result
+            for item in labels:
+                label = item.get("label", "").lower()
+                if label in ("hate", "toxic", "harmful", "extremist", "hateful"):
+                    return item["score"]
+            # Fallback: return highest score
+            if labels:
+                return max(item.get("score", 0.0) for item in labels)
+        return 0.0
+    except Exception as e:
+        logger.warning("HF harm classifier failed", error=str(e))
+        return 0.0

backend/app/services/stylometry.py

@@ -0,0 +1,137 @@
+"""
+Stylometry analysis service.
+Lightweight CPU-only feature extraction: char n-grams, function-word frequencies,
+punctuation patterns, and read-time heuristics.
+No external models required.
+"""
+import re
+import math
+from collections import Counter
+from typing import Dict
+
+# Common English function words
+FUNCTION_WORDS = {
+    "the", "be", "to", "of", "and", "a", "in", "that", "have", "i",
+    "it", "for", "not", "on", "with", "he", "as", "you", "do", "at",
+    "this", "but", "his", "by", "from", "they", "we", "say", "her", "she",
+    "or", "an", "will", "my", "one", "all", "would", "there", "their",
+    "what", "so", "up", "out", "if", "about", "who", "get", "which", "go",
+    "me", "when", "make", "can", "like", "time", "no", "just", "him",
+    "know", "take", "people", "into", "year", "your", "good", "some",
+}
+
+
+def _char_ngrams(text: str, n: int = 3) -> Dict[str, int]:
+    """Extract character n-gram frequency distribution."""
+    ngrams = Counter()
+    text_lower = text.lower()
+    for i in range(len(text_lower) - n + 1):
+        ngrams[text_lower[i:i + n]] += 1
+    return dict(ngrams)
+
+
+def _function_word_freq(text: str) -> float:
+    """Compute ratio of function words to total words."""
+    words = text.lower().split()
+    if not words:
+        return 0.0
+    fw_count = sum(1 for w in words if w.strip(".,!?;:\"'") in FUNCTION_WORDS)
+    return fw_count / len(words)
+
+
+def _punctuation_pattern(text: str) -> Dict[str, float]:
+    """Extract punctuation density and diversity metrics."""
+    if not text:
+        return {"density": 0.0, "diversity": 0.0}
+    puncts = re.findall(r"[^\w\s]", text)
+    density = len(puncts) / len(text)
+    diversity = len(set(puncts)) / max(len(puncts), 1)
+    return {"density": round(density, 4), "diversity": round(diversity, 4)}
+
+
+def _readability_score(text: str) -> float:
+    """Simple Automated Readability Index approximation."""
+    sentences = max(len(re.split(r"[.!?]+", text)), 1)
+    words = text.split()
+    word_count = max(len(words), 1)
+    char_count = sum(len(w) for w in words)
+    ari = 4.71 * (char_count / word_count) + 0.5 * (word_count / sentences) - 21.43
+    return max(0, min(20, ari))
+
+
+def _sentence_length_variance(text: str) -> float:
+    """Compute variance in sentence lengths (words per sentence)."""
+    sentences = re.split(r"[.!?]+", text)
+    lengths = [len(s.split()) for s in sentences if s.strip()]
+    if len(lengths) < 2:
+        return 0.0
+    mean = sum(lengths) / len(lengths)
+    variance = sum((l - mean) ** 2 for l in lengths) / len(lengths)
+    return round(math.sqrt(variance), 4)
+
+
+def compute_stylometry_score(text: str) -> float:
+    """
+    Compute a stylometry anomaly score (0-1).
+    Higher scores indicate more anomalous writing patterns
+    (potentially AI-generated or coordinated).
+
+    Uses a combination of features compared against typical human baselines.
+    """
+    if not text or len(text) < 20:
+        return 0.0
+
+    features = []
+
+    # Feature 1: Function word ratio (human ~0.4-0.55, AI tends to be more uniform)
+    fw_ratio = _function_word_freq(text)
+    fw_anomaly = abs(fw_ratio - 0.47) / 0.47  # Distance from typical human ratio
+    features.append(min(1.0, fw_anomaly))
+
+    # Feature 2: Punctuation patterns
+    punct = _punctuation_pattern(text)
+    # Very low or very high punctuation density is anomalous
+    punct_anomaly = abs(punct["density"] - 0.06) / 0.06 if punct["density"] > 0 else 0.5
+    features.append(min(1.0, punct_anomaly))
+
+    # Feature 3: Sentence length variance (low variance = more AI-like)
+    slv = _sentence_length_variance(text)
+    # Typical human variance is 5-15 words; very low suggests AI
+    slv_anomaly = max(0, 1.0 - slv / 10.0) if slv < 10 else 0.0
+    features.append(slv_anomaly)
+
+    # Feature 4: Readability consistency
+    ari = _readability_score(text)
+    # Very consistent readability (middle range) is more AI-like
+    ari_anomaly = max(0, 1.0 - abs(ari - 10) / 10)
+    features.append(ari_anomaly)
+
+    # Feature 5: Character n-gram entropy
+    ngrams = _char_ngrams(text, 3)
+    if ngrams:
+        total = sum(ngrams.values())
+        probs = [c / total for c in ngrams.values()]
+        entropy = -sum(p * math.log2(p) for p in probs if p > 0)
+        max_entropy = math.log2(max(len(ngrams), 1))
+        # Very high entropy = unusual; normalize
+        norm_entropy = entropy / max_entropy if max_entropy > 0 else 0
+        # AI text tends to have moderate-high entropy
+        features.append(max(0, norm_entropy - 0.5) * 2)
+    else:
+        features.append(0.0)
+
+    # Weighted average
+    weights = [0.25, 0.15, 0.25, 0.15, 0.20]
+    score = sum(f * w for f, w in zip(features, weights))
+    return round(min(1.0, max(0.0, score)), 4)
+
+
+def extract_features(text: str) -> Dict:
+    """Extract all stylometry features for analysis."""
+    return {
+        "function_word_ratio": _function_word_freq(text),
+        "punctuation": _punctuation_pattern(text),
+        "readability_ari": _readability_score(text),
+        "sentence_length_variance": _sentence_length_variance(text),
+        "stylometry_score": compute_stylometry_score(text),
+    }

backend/app/services/vector_db.py

@@ -0,0 +1,86 @@
+"""
+Vector DB integration using Qdrant for semantic embedding storage and similarity search.
+Env vars: QDRANT_URL, QDRANT_API_KEY, QDRANT_COLLECTION
+"""
+import httpx
+from typing import List, Optional, Dict
+from backend.app.core.config import settings
+from backend.app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+_TIMEOUT = httpx.Timeout(15.0, connect=5.0)
+
+
+def _headers() -> Dict[str, str]:
+    h = {"Content-Type": "application/json"}
+    if settings.QDRANT_API_KEY:
+        h["api-key"] = settings.QDRANT_API_KEY
+    return h
+
+
+async def ensure_collection(vector_size: int = 768):
+    """Create collection if it doesn't exist."""
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            resp = await client.get(
+                f"{settings.QDRANT_URL}/collections/{settings.QDRANT_COLLECTION}",
+                headers=_headers(),
+            )
+            if resp.status_code == 404:
+                await client.put(
+                    f"{settings.QDRANT_URL}/collections/{settings.QDRANT_COLLECTION}",
+                    json={"vectors": {"size": vector_size, "distance": "Cosine"}},
+                    headers=_headers(),
+                )
+                logger.info("Created Qdrant collection", collection=settings.QDRANT_COLLECTION)
+    except Exception as e:
+        logger.warning("Qdrant collection setup failed (non-fatal)", error=str(e))
+
+
+async def upsert_embedding(point_id: str, vector: List[float], payload: Optional[Dict] = None):
+    """Store an embedding vector in Qdrant."""
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            await client.put(
+                f"{settings.QDRANT_URL}/collections/{settings.QDRANT_COLLECTION}/points",
+                json={
+                    "points": [
+                        {"id": point_id, "vector": vector, "payload": payload or {}}
+                    ]
+                },
+                headers=_headers(),
+            )
+    except Exception as e:
+        logger.warning("Qdrant upsert failed (non-fatal)", error=str(e))
+
+
+async def search_similar(vector: List[float], top_k: int = 5) -> List[Dict]:
+    """Search for similar embeddings in Qdrant."""
+    try:
+        async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+            resp = await client.post(
+                f"{settings.QDRANT_URL}/collections/{settings.QDRANT_COLLECTION}/points/search",
+                json={"vector": vector, "limit": top_k, "with_payload": True},
+                headers=_headers(),
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            return data.get("result", [])
+    except Exception as e:
+        logger.warning("Qdrant search failed (non-fatal)", error=str(e))
+        return []
+
+
+async def compute_cluster_score(vector: List[float]) -> float:
+    """
+    Compute a cluster density score for the given vector.
+    Higher score = more similar to existing content (potential coordinated campaign).
+    Returns 0 if no similar items found.
+    """
+    similar = await search_similar(vector, top_k=10)
+    if not similar:
+        return 0.0
+    scores = [item.get("score", 0.0) for item in similar]
+    avg_similarity = sum(scores) / len(scores)
+    return round(min(1.0, avg_similarity), 4)

backend/app/workers/analysis_worker.py

@@ -0,0 +1,87 @@
+"""
+Async worker for processing analysis jobs via Redis queue.
+Handles heavy inference tasks that are offloaded from the main API.
+
+Run: python -m backend.app.workers.analysis_worker
+"""
+import asyncio
+import json
+
+import redis
+
+from backend.app.core.config import settings
+from backend.app.core.logging import setup_logging, get_logger
+from backend.app.services.hf_service import detect_ai_text, get_embeddings, detect_harm
+from backend.app.services.groq_service import compute_perplexity
+from backend.app.services.stylometry import compute_stylometry_score
+from backend.app.services.ensemble import compute_ensemble
+from backend.app.services.vector_db import compute_cluster_score, upsert_embedding
+
+setup_logging(settings.LOG_LEVEL)
+logger = get_logger(__name__)
+
+QUEUE_NAME = "analysis_jobs"
+
+
+def run_worker():
+    """Blocking worker loop that processes analysis jobs from Redis queue."""
+    r = redis.from_url(settings.REDIS_URL, decode_responses=True)
+    logger.info("Worker started, listening on queue", queue=QUEUE_NAME)
+
+    while True:
+        try:
+            _, raw = r.brpop(QUEUE_NAME, timeout=30)
+            if raw is None:
+                continue
+            job = json.loads(raw)
+            text = job.get("text", "")
+            job_id = job.get("id", "unknown")
+            logger.info("Processing job", job_id=job_id)
+
+            result = asyncio.run(_process_job(text))
+            r.setex(f"result:{job_id}", 3600, json.dumps(result))
+            logger.info("Job completed", job_id=job_id)
+        except Exception as e:
+            logger.error("Worker error", error=str(e))
+
+
+async def _process_job(text: str) -> dict:
+    """Process a single analysis job."""
+    try:
+        p_ai = await detect_ai_text(text)
+    except Exception:
+        p_ai = None
+
+    s_perp = None
+    if p_ai is not None and p_ai > settings.PERPLEXITY_THRESHOLD:
+        s_perp = await compute_perplexity(text)
+
+    s_embed_cluster = None
+    try:
+        embeddings = await get_embeddings(text)
+        s_embed_cluster = await compute_cluster_score(embeddings)
+        await upsert_embedding(f"worker_{hash(text)}", embeddings)
+    except Exception:
+        pass
+
+    p_ext = await detect_harm(text)
+    s_styl = compute_stylometry_score(text)
+
+    ensemble_result = compute_ensemble(
+        p_ai=p_ai, s_perp=s_perp, s_embed_cluster=s_embed_cluster,
+        p_ext=p_ext, s_styl=s_styl,
+    )
+
+    return {
+        "p_ai": p_ai,
+        "s_perp": s_perp,
+        "s_embed_cluster": s_embed_cluster,
+        "p_ext": p_ext,
+        "s_styl": s_styl,
+        "threat_score": ensemble_result["threat_score"],
+        "explainability": ensemble_result["explainability"],
+    }
+
+
+if __name__ == "__main__":
+    run_worker()

backend/migrations/env.py

@@ -0,0 +1,54 @@
+"""
+Alembic configuration for database migrations.
+"""
+from logging.config import fileConfig
+from sqlalchemy import pool
+from sqlalchemy.ext.asyncio import async_engine_from_config
+from alembic import context
+import asyncio
+import os
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+from backend.app.models.schemas import Base
+target_metadata = Base.metadata
+
+database_url = os.environ.get("DATABASE_URL", "postgresql+asyncpg://postgres:postgres@localhost:5432/sentinel")
+config.set_main_option("sqlalchemy.url", database_url)
+
+
+def run_migrations_offline():
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(url=url, target_metadata=target_metadata, literal_binds=True)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection):
+    context.configure(connection=connection, target_metadata=target_metadata)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations():
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+def run_migrations_online():
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/migrations/versions/001_initial.py

@@ -0,0 +1,49 @@
+"""
+Initial migration: create users and analysis_results tables.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "001_initial"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    op.create_table(
+        "users",
+        sa.Column("id", sa.String(), primary_key=True),
+        sa.Column("email", sa.String(255), unique=True, nullable=False),
+        sa.Column("hashed_password", sa.String(255), nullable=False),
+        sa.Column("is_active", sa.Boolean(), default=True),
+        sa.Column("created_at", sa.DateTime()),
+    )
+    op.create_index("ix_users_email", "users", ["email"])
+
+    op.create_table(
+        "analysis_results",
+        sa.Column("id", sa.String(), primary_key=True),
+        sa.Column("user_id", sa.String(), nullable=True),
+        sa.Column("input_text", sa.Text(), nullable=False),
+        sa.Column("text_hash", sa.String(64), nullable=False),
+        sa.Column("p_ai", sa.Float(), nullable=True),
+        sa.Column("s_perp", sa.Float(), nullable=True),
+        sa.Column("s_embed_cluster", sa.Float(), nullable=True),
+        sa.Column("p_ext", sa.Float(), nullable=True),
+        sa.Column("s_styl", sa.Float(), nullable=True),
+        sa.Column("p_watermark", sa.Float(), nullable=True),
+        sa.Column("threat_score", sa.Float(), nullable=True),
+        sa.Column("explainability", sa.JSON(), nullable=True),
+        sa.Column("status", sa.String(20), default="pending"),
+        sa.Column("created_at", sa.DateTime()),
+        sa.Column("completed_at", sa.DateTime(), nullable=True),
+        sa.Column("processing_time_ms", sa.Integer(), nullable=True),
+    )
+    op.create_index("ix_analysis_results_user_id", "analysis_results", ["user_id"])
+    op.create_index("ix_analysis_results_text_hash", "analysis_results", ["text_hash"])
+
+
+def downgrade():
+    op.drop_table("analysis_results")
+    op.drop_table("users")

backend/requirements.txt

@@ -0,0 +1,34 @@
+# Backend dependencies for LLM Misuse Detection System
+# Core
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+pydantic==2.10.4
+pydantic-settings==2.7.1
+
+# Firebase (Auth verification + Firestore)
+firebase-admin==6.5.0
+
+# Redis / Queue
+redis==5.2.1
+rq==2.1.0
+
+# HTTP client
+httpx==0.28.1
+tenacity==9.0.0
+
+# Observability
+structlog==24.4.0
+sentry-sdk[fastapi]==2.19.2
+prometheus-client==0.21.1
+
+# Security
+secure==1.0.1
+
+# Testing
+pytest==8.3.4
+pytest-asyncio==0.25.0
+pytest-cov==6.0.0
+
+# Utilities
+python-dotenv==1.0.1
+numpy==2.2.1

backend/scripts/seed.py

@@ -0,0 +1,60 @@
+"""
+Database seed script with sample data for testing.
+Run: python -m backend.scripts.seed
+"""
+import asyncio
+from backend.app.db.session import async_session, init_db
+from backend.app.models.schemas import User, AnalysisResult
+from backend.app.core.auth import hash_password
+
+
+SAMPLE_TEXTS = [
+    {
+        "text": "URGENT: Your account has been compromised! Click here immediately to verify your identity and prevent unauthorized access to your bank account.",
+        "label": "phishing",
+    },
+    {
+        "text": "According to multiple unnamed sources, the government has been secretly adding mind-control chemicals to the water supply since 2019. Mainstream media refuses to report on this.",
+        "label": "disinformation",
+    },
+    {
+        "text": "Join our movement. The time for peaceful protest is over. We must take direct action against those who oppress us. Armed resistance is the only path to true liberation.",
+        "label": "extremist_recruitment",
+    },
+    {
+        "text": "The Federal Reserve announced today that it will maintain current interest rates through the end of the quarter, citing stable employment numbers and moderate inflation indicators.",
+        "label": "benign_news",
+    },
+    {
+        "text": "I just saw the new movie and honestly it was pretty good. The acting was solid and the plot kept me engaged throughout. Would recommend to anyone who likes thrillers. Has anyone else seen it? What did you think?",
+        "label": "benign_discussion",
+    },
+]
+
+
+async def seed():
+    await init_db()
+    async with async_session() as session:
+        # Create demo user
+        demo_user = User(
+            email="demo@sentinel.dev",
+            hashed_password=hash_password("demo123456"),
+        )
+        session.add(demo_user)
+
+        # Create sample analysis results
+        for sample in SAMPLE_TEXTS:
+            result = AnalysisResult(
+                user_id=demo_user.id,
+                input_text=sample["text"],
+                text_hash=f"seed_{sample['label']}",
+                status="seed",
+            )
+            session.add(result)
+
+        await session.commit()
+        print(f"Seeded database with demo user and {len(SAMPLE_TEXTS)} samples")
+
+
+if __name__ == "__main__":
+    asyncio.run(seed())

backend/tests/test_api.py

@@ -0,0 +1,153 @@
+"""
+Integration tests for the API endpoints with mocked external services.
+Tests /api/analyze, /health, /metrics — no real Firebase, Firestore, or Redis needed.
+"""
+import pytest
+from unittest.mock import AsyncMock, patch, MagicMock
+from fastapi.testclient import TestClient
+
+
+def _make_client():
+    """Build a TestClient with Firebase init and Firestore writes mocked out."""
+    # Patch firebase_admin before app is imported to prevent SDK initialisation
+    with patch("backend.app.db.firestore.firebase_admin"), \
+         patch("backend.app.db.firestore.firestore"):
+        from backend.app.main import app
+
+    # Mock get_db() so Firestore document writes are no-ops
+    mock_db = MagicMock()
+    mock_collection = MagicMock()
+    mock_doc_ref = MagicMock()
+    mock_db.collection.return_value = mock_collection
+    mock_collection.document.return_value = mock_doc_ref
+    mock_doc_ref.set.return_value = None
+
+    # Mock get_result Firestore read
+    mock_existing_doc = MagicMock()
+    mock_existing_doc.exists = False
+    mock_doc_ref.get.return_value = mock_existing_doc
+
+    app.dependency_overrides = {}
+    with patch("backend.app.api.routes.get_db", return_value=mock_db), \
+         patch("backend.app.db.firestore.init_firebase"):
+        client = TestClient(app)
+    return client, mock_db
+
+
+@pytest.fixture
+def client():
+    c, _ = _make_client()
+    return c
+
+
+class TestHealthEndpoint:
+    def test_health_check(self, client):
+        response = client.get("/health")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["status"] == "ok"
+        assert data["version"] == "1.0.0"
+
+
+class TestMetricsEndpoint:
+    def test_metrics(self, client):
+        response = client.get("/metrics")
+        assert response.status_code == 200
+
+
+class TestAnalyzeEndpoint:
+    @patch("backend.app.api.routes.check_rate_limit", new_callable=AsyncMock, return_value=True)
+    @patch("backend.app.api.routes.detect_ai_text", new_callable=AsyncMock, return_value=0.85)
+    @patch("backend.app.api.routes.compute_perplexity", new_callable=AsyncMock, return_value=0.6)
+    @patch("backend.app.api.routes.get_embeddings", new_callable=AsyncMock, return_value=[0.1] * 768)
+    @patch("backend.app.api.routes.compute_cluster_score", new_callable=AsyncMock, return_value=0.3)
+    @patch("backend.app.api.routes.upsert_embedding", new_callable=AsyncMock)
+    @patch("backend.app.api.routes.detect_harm", new_callable=AsyncMock, return_value=0.2)
+    @patch("backend.app.api.routes.get_cached", new_callable=AsyncMock, return_value=None)
+    @patch("backend.app.api.routes.set_cached", new_callable=AsyncMock)
+    @patch("backend.app.api.routes.get_db")
+    def test_analyze_returns_scores(
+        self, mock_get_db, mock_set_cache, mock_get_cache, mock_harm, mock_upsert,
+        mock_cluster, mock_embed, mock_perp, mock_ai, mock_rate, client
+    ):
+        mock_db = MagicMock()
+        mock_db.collection.return_value.document.return_value.set.return_value = None
+        mock_get_db.return_value = mock_db
+
+        response = client.post(
+            "/api/analyze",
+            json={"text": "This is a test text that should be analyzed for potential misuse patterns."},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert "threat_score" in data
+        assert "signals" in data
+        assert "explainability" in data
+        assert data["status"] == "done"
+        assert data["signals"]["p_ai"] == 0.85
+
+    @patch("backend.app.api.routes.check_rate_limit", new_callable=AsyncMock, return_value=False)
+    def test_rate_limited(self, mock_rate, client):
+        response = client.post(
+            "/api/analyze",
+            json={"text": "Test text for rate limiting check."},
+        )
+        assert response.status_code == 429
+
+    def test_text_too_short(self, client):
+        response = client.post("/api/analyze", json={"text": "short"})
+        assert response.status_code == 422
+
+
+class TestAttackSimulations:
+
+    @patch("backend.app.api.routes.check_rate_limit", new_callable=AsyncMock, return_value=True)
+    @patch("backend.app.api.routes.detect_ai_text", new_callable=AsyncMock, return_value=0.95)
+    @patch("backend.app.api.routes.compute_perplexity", new_callable=AsyncMock, return_value=0.8)
+    @patch("backend.app.api.routes.get_embeddings", new_callable=AsyncMock, return_value=[0.1] * 768)
+    @patch("backend.app.api.routes.compute_cluster_score", new_callable=AsyncMock, return_value=0.7)
+    @patch("backend.app.api.routes.upsert_embedding", new_callable=AsyncMock)
+    @patch("backend.app.api.routes.detect_harm", new_callable=AsyncMock, return_value=0.9)
+    @patch("backend.app.api.routes.get_cached", new_callable=AsyncMock, return_value=None)
+    @patch("backend.app.api.routes.set_cached", new_callable=AsyncMock)
+    @patch("backend.app.api.routes.get_db")
+    def test_high_threat_detection(
+        self, mock_get_db, mock_set_cache, mock_get_cache, mock_harm, mock_upsert,
+        mock_cluster, mock_embed, mock_perp, mock_ai, mock_rate, client
+    ):
+        mock_db = MagicMock()
+        mock_db.collection.return_value.document.return_value.set.return_value = None
+        mock_get_db.return_value = mock_db
+
+        response = client.post(
+            "/api/analyze",
+            json={"text": "Simulated high-threat content for testing purposes only. This is a test."},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["threat_score"] > 0.5
+
+    @patch("backend.app.api.routes.check_rate_limit", new_callable=AsyncMock, return_value=True)
+    @patch("backend.app.api.routes.detect_ai_text", new_callable=AsyncMock, return_value=0.05)
+    @patch("backend.app.api.routes.get_embeddings", new_callable=AsyncMock, return_value=[0.1] * 768)
+    @patch("backend.app.api.routes.compute_cluster_score", new_callable=AsyncMock, return_value=0.1)
+    @patch("backend.app.api.routes.upsert_embedding", new_callable=AsyncMock)
+    @patch("backend.app.api.routes.detect_harm", new_callable=AsyncMock, return_value=0.02)
+    @patch("backend.app.api.routes.get_cached", new_callable=AsyncMock, return_value=None)
+    @patch("backend.app.api.routes.set_cached", new_callable=AsyncMock)
+    @patch("backend.app.api.routes.get_db")
+    def test_benign_text_low_threat(
+        self, mock_get_db, mock_set_cache, mock_get_cache, mock_harm, mock_upsert,
+        mock_cluster, mock_embed, mock_ai, mock_rate, client
+    ):
+        mock_db = MagicMock()
+        mock_db.collection.return_value.document.return_value.set.return_value = None
+        mock_get_db.return_value = mock_db
+
+        response = client.post(
+            "/api/analyze",
+            json={"text": "The weather today is sunny with clear skies and mild temperatures across the region."},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["threat_score"] < 0.3

backend/tests/test_auth.py

@@ -0,0 +1,60 @@
+"""
+Unit tests for Firebase token verification (auth.py).
+Mocks firebase_admin.auth so no real Firebase project is needed in CI.
+"""
+import pytest
+from unittest.mock import patch, MagicMock
+from fastapi import HTTPException
+from fastapi.security import HTTPAuthorizationCredentials
+
+
+class TestFirebaseTokenVerification:
+
+    @patch("backend.app.core.auth.firebase_auth")
+    async def test_valid_token_returns_uid(self, mock_fb_auth):
+        """A valid Firebase ID token should return the uid."""
+        from backend.app.core.auth import get_current_user
+
+        mock_fb_auth.verify_id_token.return_value = {"uid": "user-abc-123"}
+        mock_fb_auth.ExpiredIdTokenError = Exception
+        mock_fb_auth.InvalidIdTokenError = Exception
+
+        creds = HTTPAuthorizationCredentials(scheme="Bearer", credentials="fake-valid-token")
+        uid = await get_current_user(credentials=creds)
+        assert uid == "user-abc-123"
+        mock_fb_auth.verify_id_token.assert_called_once_with("fake-valid-token")
+
+    @patch("backend.app.core.auth.firebase_auth")
+    async def test_expired_token_raises_401(self, mock_fb_auth):
+        """An expired Firebase token should raise HTTP 401."""
+        from backend.app.core.auth import get_current_user
+
+        class FakeExpiredError(Exception):
+            pass
+
+        mock_fb_auth.ExpiredIdTokenError = FakeExpiredError
+        mock_fb_auth.InvalidIdTokenError = Exception
+        mock_fb_auth.verify_id_token.side_effect = FakeExpiredError("expired")
+
+        creds = HTTPAuthorizationCredentials(scheme="Bearer", credentials="expired-token")
+        with pytest.raises(HTTPException) as exc_info:
+            await get_current_user(credentials=creds)
+        assert exc_info.value.status_code == 401
+        assert "expired" in exc_info.value.detail.lower()
+
+    @patch("backend.app.core.auth.firebase_auth")
+    async def test_invalid_token_raises_401(self, mock_fb_auth):
+        """A tampered / invalid Firebase token should raise HTTP 401."""
+        from backend.app.core.auth import get_current_user
+
+        class FakeInvalidError(Exception):
+            pass
+
+        mock_fb_auth.ExpiredIdTokenError = Exception
+        mock_fb_auth.InvalidIdTokenError = FakeInvalidError
+        mock_fb_auth.verify_id_token.side_effect = FakeInvalidError("invalid")
+
+        creds = HTTPAuthorizationCredentials(scheme="Bearer", credentials="bad-token")
+        with pytest.raises(HTTPException) as exc_info:
+            await get_current_user(credentials=creds)
+        assert exc_info.value.status_code == 401

backend/tests/test_ensemble.py

@@ -0,0 +1,73 @@
+"""
+Unit tests for the ensemble scoring module.
+"""
+import pytest
+from backend.app.services.ensemble import compute_ensemble, calibrate_weights
+
+
+class TestComputeEnsemble:
+    def test_all_signals_provided(self):
+        result = compute_ensemble(
+            p_ai=0.8, s_perp=0.6, s_embed_cluster=0.4,
+            p_ext=0.3, s_styl=0.5, p_watermark=0.0
+        )
+        assert "threat_score" in result
+        assert "explainability" in result
+        assert 0.0 <= result["threat_score"] <= 1.0
+        assert len(result["explainability"]) == 6
+
+    def test_partial_signals(self):
+        result = compute_ensemble(p_ai=0.9, s_styl=0.3)
+        assert 0.0 <= result["threat_score"] <= 1.0
+        assert len(result["explainability"]) == 2
+
+    def test_no_signals(self):
+        result = compute_ensemble()
+        assert result["threat_score"] == 0.0
+        assert result["explainability"] == []
+
+    def test_watermark_reduces_score(self):
+        without_wm = compute_ensemble(p_ai=0.8, p_ext=0.5)
+        with_wm = compute_ensemble(p_ai=0.8, p_ext=0.5, p_watermark=1.0)
+        assert with_wm["threat_score"] < without_wm["threat_score"]
+
+    def test_high_threat_signals(self):
+        result = compute_ensemble(
+            p_ai=1.0, s_perp=1.0, s_embed_cluster=1.0,
+            p_ext=1.0, s_styl=1.0, p_watermark=0.0
+        )
+        assert result["threat_score"] > 0.8
+
+    def test_low_threat_signals(self):
+        result = compute_ensemble(
+            p_ai=0.0, s_perp=0.0, s_embed_cluster=0.0,
+            p_ext=0.0, s_styl=0.0, p_watermark=1.0
+        )
+        assert result["threat_score"] == 0.0
+
+    def test_explainability_structure(self):
+        result = compute_ensemble(p_ai=0.5, p_ext=0.3)
+        for item in result["explainability"]:
+            assert "signal" in item
+            assert "value" in item
+            assert "weight" in item
+            assert "contribution" in item
+            assert "description" in item
+
+
+class TestCalibrateWeights:
+    def test_empty_samples(self):
+        weights = calibrate_weights([])
+        assert "WEIGHT_AI_DETECT" in weights
+
+    def test_with_samples(self):
+        samples = [
+            {"p_ai": 0.9, "s_perp": 0.5, "p_ext": 0.1, "s_styl": 0.3},
+            {"p_ai": 0.1, "s_perp": 0.8, "p_ext": 0.9, "s_styl": 0.2},
+            {"p_ai": 0.5, "s_perp": 0.3, "p_ext": 0.5, "s_styl": 0.7},
+        ]
+        weights = calibrate_weights(samples)
+        total = sum(weights.values())
+        assert total > 0
+        for v in weights.values():
+            assert v >= 0

backend/tests/test_load.py

@@ -0,0 +1,79 @@
+"""
+Lightweight load test script for the API.
+Runs concurrent requests against the /api/analyze endpoint.
+
+Usage: python -m backend.tests.test_load [--url URL] [--concurrency N] [--requests N]
+"""
+import argparse
+import asyncio
+import time
+import httpx
+
+
+async def single_request(client: httpx.AsyncClient, url: str, text: str) -> dict:
+    start = time.time()
+    try:
+        resp = await client.post(
+            f"{url}/api/analyze",
+            json={"text": text},
+            timeout=30.0,
+        )
+        return {
+            "status": resp.status_code,
+            "latency_ms": int((time.time() - start) * 1000),
+            "success": resp.status_code == 200,
+        }
+    except Exception as e:
+        return {
+            "status": 0,
+            "latency_ms": int((time.time() - start) * 1000),
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def run_load_test(url: str, concurrency: int, total_requests: int):
+    text = (
+        "The Federal Reserve announced today that it will maintain current interest "
+        "rates through the end of the quarter, citing stable employment numbers."
+    )
+    results = []
+    semaphore = asyncio.Semaphore(concurrency)
+
+    async def bounded_request(client):
+        async with semaphore:
+            return await single_request(client, url, text)
+
+    start = time.time()
+    async with httpx.AsyncClient() as client:
+        tasks = [bounded_request(client) for _ in range(total_requests)]
+        results = await asyncio.gather(*tasks)
+    total_time = time.time() - start
+
+    successes = sum(1 for r in results if r["success"])
+    latencies = [r["latency_ms"] for r in results if r["success"]]
+
+    print(f"\n{'='*50}")
+    print(f"Load Test Results")
+    print(f"{'='*50}")
+    print(f"Total requests:  {total_requests}")
+    print(f"Concurrency:     {concurrency}")
+    print(f"Total time:      {total_time:.2f}s")
+    print(f"Successes:       {successes}/{total_requests}")
+    print(f"RPS:             {total_requests/total_time:.1f}")
+    if latencies:
+        latencies.sort()
+        print(f"Avg latency:     {sum(latencies)/len(latencies):.0f}ms")
+        print(f"P50 latency:     {latencies[len(latencies)//2]}ms")
+        print(f"P95 latency:     {latencies[int(len(latencies)*0.95)]}ms")
+        print(f"P99 latency:     {latencies[int(len(latencies)*0.99)]}ms")
+    print(f"{'='*50}\n")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--url", default="http://localhost:8000")
+    parser.add_argument("--concurrency", type=int, default=10)
+    parser.add_argument("--requests", type=int, default=50)
+    args = parser.parse_args()
+    asyncio.run(run_load_test(args.url, args.concurrency, args.requests))

backend/tests/test_services.py

@@ -0,0 +1,88 @@
+"""
+Integration tests for HF and Groq service modules (mocked).
+Tests retry behavior and error handling.
+"""
+import pytest
+from unittest.mock import patch, AsyncMock, MagicMock
+import httpx
+
+from backend.app.services.hf_service import detect_ai_text, get_embeddings, detect_harm
+from backend.app.services.groq_service import compute_perplexity
+
+
+class TestHFService:
+    @pytest.mark.asyncio
+    @patch("backend.app.services.hf_service._hf_request", new_callable=AsyncMock)
+    async def test_detect_ai_text_success(self, mock_request):
+        mock_request.return_value = [[
+            {"label": "AI", "score": 0.92},
+            {"label": "Human", "score": 0.08},
+        ]]
+        score = await detect_ai_text("Test text for detection")
+        assert 0.0 <= score <= 1.0
+
+    @pytest.mark.asyncio
+    @patch("backend.app.services.hf_service._hf_request", new_callable=AsyncMock)
+    async def test_detect_ai_text_fallback(self, mock_request):
+        """If primary fails, should try fallback."""
+        mock_request.side_effect = [
+            Exception("Primary failed"),
+            [[{"label": "FAKE", "score": 0.75}]],
+        ]
+        score = await detect_ai_text("Test text")
+        assert 0.0 <= score <= 1.0
+
+    @pytest.mark.asyncio
+    @patch("backend.app.services.hf_service._hf_request", new_callable=AsyncMock)
+    async def test_get_embeddings_success(self, mock_request):
+        mock_request.return_value = [0.1] * 768
+        result = await get_embeddings("Test text")
+        assert len(result) == 768
+
+    @pytest.mark.asyncio
+    @patch("backend.app.services.hf_service._hf_request", new_callable=AsyncMock)
+    async def test_detect_harm_success(self, mock_request):
+        mock_request.return_value = [[
+            {"label": "hate", "score": 0.15},
+            {"label": "not_hate", "score": 0.85},
+        ]]
+        score = await detect_harm("Test text")
+        assert 0.0 <= score <= 1.0
+
+
+class TestGroqService:
+    @pytest.mark.asyncio
+    @patch("backend.app.services.groq_service._groq_chat_completion", new_callable=AsyncMock)
+    async def test_compute_perplexity_with_logprobs(self, mock_groq):
+        mock_groq.return_value = {
+            "choices": [{
+                "logprobs": {
+                    "content": [
+                        {"logprob": -2.5},
+                        {"logprob": -1.8},
+                        {"logprob": -3.2},
+                    ]
+                }
+            }]
+        }
+        score = await compute_perplexity("Test text for perplexity")
+        assert score is not None
+        assert 0.0 <= score <= 1.0
+
+    @pytest.mark.asyncio
+    @patch("backend.app.services.groq_service._groq_chat_completion", new_callable=AsyncMock)
+    async def test_compute_perplexity_no_logprobs(self, mock_groq):
+        mock_groq.return_value = {
+            "choices": [{}],
+            "usage": {"prompt_tokens": 15},
+        }
+        score = await compute_perplexity("Test text without logprobs available")
+        # May return None or a heuristic value
+        assert score is None or 0.0 <= score <= 1.0
+
+    @pytest.mark.asyncio
+    @patch("backend.app.services.groq_service._groq_chat_completion", new_callable=AsyncMock)
+    async def test_compute_perplexity_error(self, mock_groq):
+        mock_groq.side_effect = Exception("Groq API error")
+        score = await compute_perplexity("Test text")
+        assert score is None

backend/tests/test_stylometry.py

@@ -0,0 +1,76 @@
+"""
+Unit tests for the stylometry analysis service.
+"""
+import pytest
+from backend.app.services.stylometry import (
+    compute_stylometry_score,
+    extract_features,
+    _function_word_freq,
+    _punctuation_pattern,
+    _readability_score,
+    _sentence_length_variance,
+)
+
+
+class TestStylometry:
+    def test_compute_score_normal_text(self):
+        text = (
+            "The Federal Reserve announced today that it will maintain current "
+            "interest rates through the end of the quarter, citing stable employment "
+            "numbers and moderate inflation indicators."
+        )
+        score = compute_stylometry_score(text)
+        assert 0.0 <= score <= 1.0
+
+    def test_compute_score_empty(self):
+        assert compute_stylometry_score("") == 0.0
+
+    def test_compute_score_short_text(self):
+        assert compute_stylometry_score("Hello") == 0.0
+
+    def test_function_word_frequency(self):
+        text = "the dog and the cat are on the mat"
+        ratio = _function_word_freq(text)
+        assert 0.0 <= ratio <= 1.0
+        assert ratio > 0.3  # High function word density
+
+    def test_punctuation_pattern(self):
+        text = "Hello, world! How are you? I'm fine."
+        result = _punctuation_pattern(text)
+        assert "density" in result
+        assert "diversity" in result
+        assert result["density"] > 0
+
+    def test_readability(self):
+        text = "This is a simple test sentence. It has easy words."
+        score = _readability_score(text)
+        assert score >= 0
+
+    def test_sentence_length_variance(self):
+        text = "Short. This is a longer sentence with more words. Tiny."
+        var = _sentence_length_variance(text)
+        assert var >= 0
+
+    def test_extract_features(self):
+        text = "This is a test of the feature extraction system for analysis."
+        features = extract_features(text)
+        assert "function_word_ratio" in features
+        assert "punctuation" in features
+        assert "readability_ari" in features
+        assert "stylometry_score" in features
+
+    def test_different_text_styles(self):
+        formal = (
+            "The comprehensive analysis of macroeconomic indicators suggests that "
+            "the prevailing monetary policy framework requires substantial revision "
+            "in light of unprecedented fiscal challenges."
+        )
+        casual = (
+            "yo so I was thinking maybe we should grab some food later? "
+            "idk what u want but pizza sounds good to me lol"
+        )
+        score_formal = compute_stylometry_score(formal)
+        score_casual = compute_stylometry_score(casual)
+        # Both should produce valid scores
+        assert 0.0 <= score_formal <= 1.0
+        assert 0.0 <= score_casual <= 1.0