README.md

---
title: ToxiGuard AI
emoji: 🛡️
colorFrom: red
colorTo: purple
sdk: streamlit
sdk_version: "1.35.0"
app_file: app.py
pinned: false
license: mit
---

# 🛡️ ToxiGuard AI — Multi-label Toxic Comment Detection using BERT

ToxiGuard AI is an advanced NLP-based content moderation system that detects multiple categories of toxic comments using transformer-based deep learning models.  
The project uses HuggingFace Transformers, PyTorch, and BERT fine-tuning for real-time toxicity classification across six toxicity categories.

---

# 🚀 Project Overview

Online platforms face massive challenges in moderating harmful user-generated content.  
ToxiGuard AI solves this problem using a transformer-powered multi-label NLP pipeline capable of detecting:

- Toxic
- Severe Toxic
- Obscene
- Threat
- Insult
- Identity Hate

Unlike traditional text classification systems, this project uses contextual transformer embeddings to understand semantic meaning, contextual toxicity, and subtle hate speech patterns.

---

# 🎯 Problem Statement

Build a multi-label NLP system capable of classifying toxic social media comments into multiple toxicity categories simultaneously using deep learning transformers.

---

# 💡 Why This Project Matters

Content moderation is one of the largest real-world NLP applications today.

Companies actively working on moderation systems include:

- Meta
- Google
- YouTube
- Reddit
- ShareChat
- Koo
- Discord

This project demonstrates:

- Advanced NLP Engineering
- Transformer Fine-tuning
- Multi-label Deep Learning
- PyTorch Training Pipelines
- HuggingFace Ecosystem
- GPU Acceleration
- Model Deployment

---

# 🧠 Model Architecture

The project uses:

## BERT (bert-base-uncased)

Architecture:
- Transformer Encoder
- Self-Attention Mechanism
- Multi-label Sigmoid Output Layer

Loss Function:
- BCEWithLogitsLoss

Output Layer:
- 6-neuron sigmoid classification head

---

# 📊 Dataset

## Jigsaw Toxic Comment Classification Dataset

Dataset contains:
- 159,571 Wikipedia comments
- Multi-label annotations
- Real-world toxic language

### Labels

| Label | Description |
|---|---|
| toxic | General toxic content |
| severe_toxic | Extremely toxic content |
| obscene | Obscene language |
| threat | Threatening statements |
| insult | Insulting comments |
| identity_hate | Hate speech targeting identity |

---

# ⚙️ Tech Stack

## Machine Learning / NLP
- Python
- PyTorch
- HuggingFace Transformers
- Scikit-learn
- NumPy
- Pandas

## Visualization / Deployment
- Streamlit
- Matplotlib

## Model / Training
- BERT
- GPU Fine-tuning
- Mixed Precision Training (FP16)

---

# 🔬 Project Pipeline

## 1. Data Preprocessing
- Text cleaning
- Lowercasing
- Special character handling
- Comment length analysis

## 2. Exploratory Data Analysis
- Label distribution
- Toxicity co-occurrence
- Comment length statistics

## 3. Traditional NLP Baseline
- TF-IDF Vectorization
- Logistic Regression
- Binary Relevance Classification
- Threshold Optimization

## 4. Transformer Fine-tuning
- HuggingFace Tokenization
- BERT Fine-tuning
- Multi-label BCE Loss
- Dynamic Padding
- GPU Training

## 5. Evaluation
- Macro F1 Score
- Micro F1 Score
- ROC-AUC
- Per-label threshold tuning

## 6. Deployment
- Streamlit Web App
- Real-time Toxicity Detection
- Probability Visualization

---

# 📈 Model Performance

## TF-IDF Baseline

| Metric | Score |
|---|---|
| Macro F1 | 0.61 |
| Micro F1 | 0.73 |
| Macro ROC-AUC | 0.979 |

---

## BERT Fine-tuned Model

| Metric | Score |
|---|---|
| Macro F1 | 0.666 |
| Micro F1 | 0.801 |
| ROC-AUC | 0.992 |

---

# 🧪 Key Features

✅ Multi-label Toxicity Detection  
✅ Transformer-based NLP  
✅ Contextual Toxicity Understanding  
✅ Real-time Inference  
✅ Probability-based Predictions  
✅ Threshold Optimization  
✅ Streamlit UI Deployment  
✅ GPU Accelerated Training  

---

# 📂 Project Structure

```bash
ToxiGuard-BERT/
│
├── toxiguard-bert/
│   ├── config.json
│   ├── model.safetensors
│   ├── tokenizer.json
│   ├── tokenizer_config.json
│   └── special_tokens_map.json
│
├── app.py
├── utils.py
├── labels.py
├── style.css
├── requirements.txt
├── README.md
│
└── assets/
```

---

# ▶️ Installation

## Clone Repository

```bash
git clone https://github.com/MohdFaizan22/ToxiGuard-BERT.git
cd ToxiGuard-BERT
```

---

## Create Virtual Environment

### Windows

```bash
python -m venv venv
venv\Scripts\activate
```

### Linux / Mac

```bash
python3 -m venv venv
source venv/bin/activate
```

---

## Install Dependencies

```bash
pip install -r requirements.txt
```

---

# ▶️ Run Application

```bash
streamlit run app.py
```

---

# 🖥️ Web App Features

- Real-time toxicity prediction
- Toxicity confidence scores
- Multi-label classification
- Safe vs Toxic detection
- Interactive probability bars
- Modern dark UI

---

# 🧪 Example Predictions

## Input

```text
You are an absolute idiot and nobody likes you.
```

## Output

```python
{
 'toxic': 0.998,
 'severe_toxic': 0.42,
 'obscene': 0.71,
 'threat': 0.01,
 'insult': 0.96,
 'identity_hate': 0.02
}
```

---

# 🧠 Key NLP Concepts Used

- Transformer Architecture
- Self-Attention
- Contextual Embeddings
- Multi-label Classification
- BCEWithLogitsLoss
- Dynamic Padding
- Tokenization
- Threshold Optimization
- Mixed Precision Training

---

# 📌 Future Improvements

- RoBERTa / DeBERTa Upgrade
- Multilingual Toxicity Detection
- Explainable AI Attention Maps
- FastAPI Backend
- Docker Deployment
- ONNX Optimization
- Real-time Moderation Dashboard
- Toxic Span Detection

---

# 📚 Learning Outcomes

Through this project, I learned:

- Transformer Fine-tuning
- Multi-label NLP
- HuggingFace Ecosystem
- PyTorch Deep Learning
- GPU Training Optimization
- NLP Inference Pipelines
- Real-world Content Moderation Systems
- Streamlit Deployment

---


# 🤝 Acknowledgements

- Kaggle Jigsaw Toxic Comment Dataset
- HuggingFace Transformers
- PyTorch
- Streamlit

---