SentryText AI

SentryText AI is a multilingual toxicity analysis web platform with two analysis paths:

• Fast Analysis: low-latency, language-aware single-model prediction.
• Comparative Analysis: four-model evaluation with consensus + disagreement signals.

It also includes a rewrite workflow that can transform toxic text into safer phrasing and then re-analyze the rewritten result.

---

Table of Contents

• Overview
• Core Features
• Architecture
• Repository Structure
• Prerequisites
• Local Development
  • Option A: One-command startup (recommended)
  • Option B: Start backend and frontend manually
• Configuration
• Model Weights Workflow
• API Reference
• Manual Verification
• Troubleshooting

---

Overview

SentryText AI is designed for content moderation and text safety experimentation across multilingual inputs (English, Malay, Mandarin, bilingual, and multilingual mixes). The backend performs language-aware routing and model inference, while the frontend provides an interactive workflow for:

1. submitting text,
2. reviewing toxicity predictions,
3. optionally rewriting risky content,
4. re-checking toxicity after rewrite.

---

Core Features

1) Fast Analysis

• Endpoint: POST /api/v1/analyze/fast
• Uses detected language to route to the best model path.
• Returns a single prediction with probabilities, threshold, latency, and selected model.

2) Comparative Analysis

• Endpoint: POST /api/v1/analyze/comparative
• Evaluates multiple model families and returns:
  • per-model predictions,
  • consensus result,
  • disagreement level,
  • average toxicity signal.

3) Rewrite + Re-analysis

• Endpoint: POST /api/v1/rewrite
• Rewrites toxic input while preserving language and sentence structure constraints.
• Frontend supports immediate re-analysis of rewritten text (comparative first, with fast fallback in some flows).

---

Architecture

Frontend (webapp/frontend)

• Framework: Next.js + React + TypeScript
• UI pages:
  • app/fast-analysis/page.tsx
  • app/comparative-analysis/page.tsx
• Responsibilities:
  • collect user input,
  • invoke backend APIs,
  • display predictions, consensus, and rewrite outcomes.

Backend (webapp/backend)

• Framework: FastAPI
• Main app: webapp/backend/app/main.py
• Exposed API routes:
  • routes_fast_analysis.py
  • routes_comparative_analysis.py
  • routes_rewrite.py
• Responsibilities:
  • validation,
  • language detection and routing,
  • model inference orchestration,
  • rewrite orchestration,
  • structured error handling and request tracing.

Runtime metadata & artifacts

• Config and metadata live under webapp/metadata.
• Model binaries are expected under top-level weights/ (not committed to git).
• Startup validates runtime artifacts and can optionally fail on corrupted checkpoints.

---

Repository Structure

webapp/
  backend/
    app/
      api/
      core/
      model_runtime/
      schemas/
      services/
  frontend/
    app/
    components/
    hooks/
    lib/
  metadata/
    app_config.example.yaml
    model_registry.example.json
    thresholds.example.json
    weights_manifest.sample.json
  scripts/
    run_dev.sh
    download_weights.py

---

Prerequisites

• Node.js + npm (for frontend)
• Python 3.10+ (recommended) for backend
• OS with shell support for scripts (bash script included)

Backend Python dependencies are in:

webapp/backend/requirements.txt

---

Local Development

Option A: One-command startup (recommended)

From repository root:

bash webapp/scripts/run_dev.sh

This starts both backend and frontend. Press Ctrl + C once to stop both processes.

If ports are already occupied:

BACKEND_PORT=8010 FRONTEND_PORT=3010 bash webapp/scripts/run_dev.sh

If backend uses non-default port, keep frontend proxy aligned:

BACKEND_PORT=8010 BACKEND_ORIGIN=http://127.0.0.1:8010 bash webapp/scripts/run_dev.sh

If frontend is exposed via ngrok during dev:

ALLOWED_DEV_ORIGINS=https://<your-frontend-ngrok-domain> bash webapp/scripts/run_dev.sh

Option B: Start backend and frontend manually

1) Backend

From repository root:

pip install -r webapp/backend/requirements.txt
uvicorn webapp.backend.app.main:app --reload --host 0.0.0.0 --port 8000

2) Frontend

In a separate terminal:

cd webapp/frontend
npm install
cp .env.example .env.local
npm run dev

Frontend runs at your configured dev port (default commonly 3000 for raw Next.js, script flow may use 3100).

---

Configuration

Primary backend config source:

• webapp/metadata/app_config.example.yaml

Config loader logic is in:

• webapp/backend/app/core/config.py

Notable behavior:

• API base path defaults to /api/v1.
• Default dev CORS allowlist includes:
  • http://127.0.0.1:3000
  • http://localhost:3000
• ngrok origins are allowed by regex (*.ngrok-free.app, *.ngrok.io).
• You can override config path with APP_CONFIG_PATH.

For rewrite flows using OpenAI-compatible providers, ensure required API keys are available in request payload or environment as your deployment expects.

---

Model Weights Workflow

Model binaries are intentionally excluded from git. Download them before running production-like inference.

1) Prepare manifest

Start from:

• webapp/metadata/weights_manifest.sample.json

For each file entry, provide:

• path (destination inside weights directory)
• url or gdrive_file_id
• sha256 checksum
• required flag (optional, defaults to true)

2) Download weights

From repository root:

python webapp/scripts/download_weights.py

Optional overrides:

WEIGHTS_MANIFEST_PATH=webapp/metadata/weights_manifest.sample.json \
WEIGHTS_DIR=weights \
python webapp/scripts/download_weights.py

Google Drive token (if required by your file hosting setup):

GDRIVE_ACCESS_TOKEN=<your_oauth_access_token> python webapp/scripts/download_weights.py

3) Start backend only after successful download

python webapp/scripts/download_weights.py && \
uvicorn webapp.backend.app.main:app --host 0.0.0.0 --port 8000

If checksum or download fails for required files, script exits non-zero so deployment fails fast.

---

API Reference

Base URL (local default):

http://127.0.0.1:8000/api/v1

POST /analyze/fast

Request body:

{
  "text": "Your input text",
  "llm_provider": "nvidia",
  "llm_api_key": "optional-key",
  "llm_base_url": "optional-url",
  "llm_model": "optional-model"
}

Returns FastAnalysisResponse with:

• detected_language
• selected_model
• prediction (label, probabilities, threshold, latency)
• timing

POST /analyze/comparative

Same request shape as fast analysis. Returns ComparativeAnalysisResponse with:

• models[] per-model predictions,
• consensus (final label, vote counts, avg toxicity, disagreement),
• timing.

POST /rewrite

Request body:

{
  "text": "Original text",
  "detected_language_group": "english",
  "mode": "fast",
  "rewrite_api_key": "optional-key",
  "rewrite_base_url": "optional-url",
  "rewrite_model": "optional-model",
  "llm_provider": "nvidia",
  "llm_api_key": "optional-key",
  "llm_base_url": "optional-url",
  "llm_model": "optional-model"
}

Returns RewriteResponse with:

• original vs rewritten text,
• language/sentence preservation flags,
• retry/grace-mode indicators,
• rewrite timing.

---

Manual Verification

Use these files for guided checks:

• webapp/scripts/e2e_checklist.md
• webapp/scripts/samples.json

You can also test backend endpoints directly via examples in:

• webapp/backend/README.md

---

Troubleshooting

• Port already in use

  • Set BACKEND_PORT / FRONTEND_PORT to unused values.

• One service exits and both stop in script mode

  • This is intentional behavior in run_dev.sh to avoid half-running environments.

• uvicorn not found

  • Install backend dependencies:
    pip install -r webapp/backend/requirements.txt

• Rewrite failures

  • Verify rewrite provider config and API key availability.

• Checkpoint/weights issues at startup

  • Re-run download_weights.py and verify manifest URLs/checksums.

---

Tech Stack

• Frontend: Next.js, React, TypeScript, TailwindCSS
• Backend: FastAPI, Pydantic
• ML Runtime: PyTorch, Transformers

---