SafeSpeech

SafeSpeech is a pipeline for hate/offensive text moderation and mitigation in Indic languages.

For the live Hindi flow, the system does this:

1. Classify input text as hate or non-hate
2. If non-hate: return original text unchanged
3. If hate: return influential words and a mitigation attempt

What You Get

• Live API (FastAPI) for Hindi moderation
• Simple web UI at /
• Runtime metrics endpoint at /metrics
• End-to-end smoke script: scripts/test_full_flow.py

---

Local Setup (Step-by-Step)

1. Prerequisites

• Python 3.11+ (3.12 also works)
• git
• Optional: docker (for container run)

2. Clone and enter project

git clone https://github.com/neeraj1909/safespeech-indic-hate-mitigation.git
cd safespeech-indic-hate-mitigation

3. Create virtual environment

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip

4. Install dependencies

pip install -e .

5. Ensure checkpoints are available

The live API requires both paths:

• Classifier checkpoint directory
• MLM checkpoint directory

Example paths used in this repo:

• ./muril_supervised_hasoc2019_macd_hindi/final
• ./mlm_muril/finetuned_google_muril_mlm

If either path is missing, server startup fails fast with a clear error.

---

Start the Hindi Live Server

python3 scripts/run_api.py \
  --classifier-path ./muril_supervised_hasoc2019_macd_hindi/final \
  --mlm-path ./mlm_muril/finetuned_google_muril_mlm \
  --device cpu \
  --port 8000

After startup:

• Web UI: http://localhost:8000/
• Health: http://localhost:8000/health
• Metrics: http://localhost:8000/metrics

---

API Usage

Health

curl http://localhost:8000/health

Moderation endpoint

curl -X POST http://localhost:8000/v1/moderate-hindi \
  -H "Content-Type: application/json" \
  -d '{"text":"यह पाठ घृणित नहीं है"}'

Expected behavior:

• Non-hate input: unchanged output_text, mitigation=null
• Hate input: influential_words populated and mitigation attempted

Metrics

curl http://localhost:8000/metrics

Metrics include:

• request_count
• hate_rate
• mitigation_success_rate
• latency (latency_p50_ms, latency_p95_ms, latency_max_ms)

---

Run Full End-to-End Smoke Test

Option A: test already running server

python3 scripts/test_full_flow.py --base-url http://localhost:8000

Option B: let script start server and test flow

python3 scripts/test_full_flow.py \
  --start-server \
  --classifier-path ./muril_supervised_hasoc2019_macd_hindi/final \
  --mlm-path ./mlm_muril/finetuned_google_muril_mlm \
  --device cpu \
  --base-url http://localhost:8000

If server is not running for Option A, script exits cleanly with:

• API is not reachable ... Start the server first, or rerun with --start-server.

---

Docker Run

Build image

docker build -t safespeech-live .

Run container (mount local checkpoints)

docker run --rm -p 8000:8000 \
  -v /absolute/path/to/classifier:/models/classifier:ro \
  -v /absolute/path/to/mlm:/models/mlm:ro \
  safespeech-live

Then test:

curl http://localhost:8000/health
curl -X POST http://localhost:8000/v1/moderate-hindi \
  -H "Content-Type: application/json" \
  -d '{"text":"यह पाठ घृणित नहीं है"}'

---

Useful Commands

Unit tests

timeout 60 uv run pytest -m unit --no-cov

Integration tests

timeout 60 uv run pytest -m integration --no-cov

Lint

uv run ruff check --fix .

---

Troubleshooting

Connection refused on localhost:8000

• Server is not running.
• Start with scripts/run_api.py, or use scripts/test_full_flow.py --start-server.

Startup error: missing checkpoint path

• Verify both --classifier-path and --mlm-path exist and point to directories.

Docker build/export slow or stuck

• Free disk/cache:

docker system prune -af

High latency for hate samples

• Hate flow runs explainability + mitigation and is heavier than non-hate flow.
• CPU inference is slower than GPU.

---

Notes

• Runtime fine-tuning is out of scope for live serving.
• Existing trained checkpoints are expected to be reused.
• For research details, see the paper:
  • Ghosh et al., SafeSpeech: a three-module pipeline for hate intensity mitigation of social media texts in Indic languages (Social Network Analysis and Mining, 2024).

License

MIT