Spaces:
Running
Running
| title: Wasla Feedback Moderation API | |
| emoji: 🛡️ | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| # Feedback Moderation API | |
| AI-powered microservice that detects toxic / abusive language in user-submitted text. | |
| Uses **local** Hugging Face transformer models — your data never leaves your infrastructure. | |
| ### Dual-Model Architecture | |
| | Language | Model | Labels | | |
| | -------- | ----- | ------ | | |
| | English, French, Italian (and more) | `citizenlab/distilbert-base-multilingual-cased-toxicity` | `toxic` / `not_toxic` | | |
| | Arabic | `Hate-speech-CNERG/dehatebert-mono-arabic` | `HATE` / `NON_HATE` | | |
| Arabic text is **automatically detected** using the [lingua](https://github.com/pemistahl/lingua-py) language-detection library and routed to the dedicated Arabic hate-speech model for significantly higher accuracy (~87.8 %). All other languages use the multilingual model. | |
| ### LLM Verification Layer (optional) | |
| When the local classifier's confidence falls in a configurable **grey zone** (default: 0.40 – 0.85), the text is forwarded to a free **Hugging Face Inference API** LLM (default: `mistralai/Mistral-7B-Instruct-v0.3`) for a second opinion. The LLM score is blended with the local score (40/60 weighting) to produce a refined verdict. | |
| - ⚡ **No extra latency** for clear-cut predictions (>95 % of requests) | |
| - 🆓 **Free** — uses HF Inference Providers with a free token | |
| - 🔒 **Graceful fallback** — if the LLM is unavailable, the local model result is used as-is | |
| Set `HF_TOKEN` in `.env` to enable. Leave it empty to disable. | |
| --- | |
| ## Quick Start | |
| ### 1. Clone & create a virtual environment | |
| ```bash | |
| git clone <your-repo-url> moderator-api | |
| cd moderator-api | |
| python -m venv venv | |
| # Windows | |
| .\venv\Scripts\Activate.ps1 | |
| # macOS / Linux | |
| source venv/bin/activate | |
| ``` | |
| ### 2. Install dependencies | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| ### 3. Configure | |
| Copy the example env file and set a strong API key: | |
| ```bash | |
| cp .env.example .env | |
| # then edit .env → MODERATOR_API_KEY=<your-secret> | |
| ``` | |
| ### 4. Run | |
| ```bash | |
| uvicorn main:app --reload | |
| ``` | |
| The server starts at **http://127.0.0.1:8000**. | |
| Interactive docs are at **http://127.0.0.1:8000/docs**. | |
| > **First launch** will download two models (~1 GB total). | |
| > Subsequent starts load from the local cache. | |
| --- | |
| ## API Reference | |
| ### `GET /health` | |
| Liveness probe. Returns `{"status": "ok", "model_loaded": true}`. | |
| ### `POST /api/v1/moderate` | |
| Analyse a piece of text for toxicity. | |
| **Headers** | |
| | Header | Required | Description | | |
| | ----------- | -------- | -------------------- | | |
| | `X-API-Key` | ✅ | Your secret API key | | |
| **Request body** | |
| ```json | |
| { | |
| "text": "This product is terrible and I hate everything about it!" | |
| } | |
| ``` | |
| **Response** | |
| ```json | |
| { | |
| "has_bad_words": true, | |
| "confidence": 0.9812, | |
| "label": "toxic", | |
| "detected_language": "en", | |
| "llm_verified": false | |
| } | |
| ``` | |
| --- | |
| ## Calling from an External App | |
| ```python | |
| import requests | |
| API_URL = "http://your-server:8000/api/v1/moderate" | |
| API_KEY = "your-secret-api-key" | |
| response = requests.post( | |
| API_URL, | |
| json={"text": "I absolutely love this!"}, | |
| headers={"X-API-Key": API_KEY}, | |
| ) | |
| result = response.json() | |
| if result["has_bad_words"]: | |
| print("⚠️ Feedback rejected — toxic content detected.") | |
| else: | |
| print("✅ Feedback is clean.") | |
| ``` | |
| --- | |
| ## Docker | |
| ### Build | |
| ```bash | |
| docker build -t moderator-api . | |
| ``` | |
| ### Run | |
| ```bash | |
| docker run -d \ | |
| -p 8000:8000 \ | |
| -e MODERATOR_API_KEY=your-secret-api-key \ | |
| --name moderator-api \ | |
| moderator-api | |
| ``` | |
| --- | |
| ## Deploy to Hugging Face Spaces (Free) | |
| ### 1. Create a Space | |
| Go to [huggingface.co/new-space](https://huggingface.co/new-space) and create a new Space: | |
| - **Space name**: `moderator-api` | |
| - **SDK**: Docker | |
| - **Visibility**: Private (recommended) | |
| ### 2. Add secrets | |
| In your Space → **Settings → Secrets**, add: | |
| | Secret | Value | | |
| | ------ | ----- | | |
| | `MODERATOR_API_KEY` | A strong random string | | |
| | `HF_TOKEN` | Your Hugging Face token | | |
| | `LLM_VERIFY_LOW` | `0.0` (or `0.40` for grey-zone only) | | |
| | `LLM_VERIFY_HIGH` | `1.0` (or `0.85` for grey-zone only) | | |
| ### 3. Push your code | |
| ```bash | |
| git init | |
| git remote add space https://huggingface.co/spaces/YOUR_USERNAME/moderator-api | |
| git add . | |
| git commit -m "Deploy moderator API" | |
| git push space main | |
| ``` | |
| ### 4. Access your API | |
| Once built, your API is live at: | |
| ``` | |
| https://YOUR_USERNAME-moderator-api.hf.space/api/v1/moderate | |
| ``` | |
| Interactive docs at: | |
| ``` | |
| https://YOUR_USERNAME-moderator-api.hf.space/docs | |
| ``` | |
| > ⚠️ First deploy takes ~5 minutes (model downloads ~1 GB). | |
| > Subsequent deploys use cached layers and are much faster. | |
| --- | |
| ## Configuration (Environment Variables) | |
| | Variable | Default | Description | | |
| | --------------------- | ------------------------------ | ------------------------------------------ | | |
| | `MODERATOR_API_KEY` | `change-me-before-production` | Secret key clients must send in headers | | |
| | `MODEL_NAME` | `citizenlab/distilbert-base-multilingual-cased-toxicity` | Multilingual Hugging Face model (en/fr/it) | | |
| | `ARABIC_MODEL_NAME` | `Hate-speech-CNERG/dehatebert-mono-arabic` | Dedicated Arabic hate-speech model | | |
| | `TOXICITY_THRESHOLD` | `0.70` | Confidence cutoff to flag text as toxic | | |
| | `ARABIC_TOXICITY_THRESHOLD` | `0.45` | Lower threshold for Arabic (model outputs lower scores) | | |
| | `HF_TOKEN` | *(empty — LLM disabled)* | Free HF token to enable LLM verification | | |
| | `LLM_MODEL_NAME` | `Qwen/Qwen2.5-72B-Instruct` | LLM used for grey-zone verification | | |
| | `LLM_VERIFY_LOW` | `0.40` | Lower bound of the grey zone | | |
| | `LLM_VERIFY_HIGH` | `0.85` | Upper bound of the grey zone | | |
| --- | |
| ## Project Structure | |
| ``` | |
| moderator-api/ | |
| ├── main.py # FastAPI application & moderation endpoint | |
| ├── requirements.txt # Python dependencies | |
| ├── Dockerfile # Production container image | |
| ├── .dockerignore # Files excluded from Docker build | |
| ├── .env # Local environment variables (git-ignored) | |
| ├── .env.example # Template for .env | |
| ├── .gitignore | |
| └── README.md | |
| ``` | |
| ## License | |
| MIT | |