# Harmony v2 — Toxicity Classifier

> **Lightweight, context-aware toxicity detection that understands intent, not just keywords.**

Harmony v2 is a lightweight toxicity classifier fine-tuned from **gravitee-io/bert-tiny-toxicity** on **HarmonyDataset v2**, a custom dataset of **7,000 human-like chat messages**.

Unlike traditional keyword-based filters, Harmony v2 focuses on **who is being targeted, the intent behind the message, and conversational context**.

> **Profanity ≠ Toxicity**

---

# 🧠 Overview

Harmony v2 is designed for modern chat moderation, especially for Telegram communities, forums, games, and social platforms.

It distinguishes between:

### 🚨 Toxic
- Personal attacks
- Harassment
- Threats
- Humiliation
- Dehumanization
- Hate directed at another person

### ✅ Safe
- Emotional expression
- Frustration
- Profanity without a target
- Friendly banter
- Sarcasm
- Jokes
- Self-directed insults

Instead of blocking words, Harmony v2 evaluates **intent**.

---

# ✨ Features

| Feature | Value |
|----------|-------|
| Base model | gravitee-io/bert-tiny-toxicity |
| Dataset | HarmonyDataset v2 |
| Samples | 7,000 |
| Languages | Ukrainian, Russian, mixed UA/RU |
| Max sequence length | 512 tokens |
| Framework | Hugging Face Transformers |
| Model format | PyTorch |
| Quantized size | ~9 MB (INT8) |
| License | Apache-2.0 |

---

# ⚡ Performance

| Metric | Result |
|---------|--------|
| Evaluation Loss | **0.4255** |
| F1 Score | **98.4%** |
| CPU Inference | **~11 ms** |
| Precision | High |
| Recall | High |

---

# 📊 Dataset

HarmonyDataset v2 contains **7,000 balanced synthetic chat messages**.

| Category | Share |
|----------|------:|
| Safe | 15% |
| Friendly profanity | 10% |
| Frustration | 10% |
| Self-insult | 5% |
| Joke | 10% |
| Sarcasm | 10% |
| Criticism | 5% |
| Insult | 10% |
| Harassment | 15% |
| Threat | 10% |

Dataset philosophy:

- realistic conversations
- Telegram-like writing
- slang
- spelling mistakes
- emojis
- mixed Ukrainian/Russian
- contextual toxicity

---

# 🚀 Installation

Clone the repository:

```bash
git clone https://github.com/floxoris/harmony-v2
cd harmony-v2
```

Install dependencies:

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

---

# 📦 Load the Model

```python
from transformers import (
    AutoTokenizer,
    AutoModelForSequenceClassification
)

model_path = "./Harmony-v2"

tokenizer = AutoTokenizer.from_pretrained(model_path)
model = AutoModelForSequenceClassification.from_pretrained(model_path)
```

---

# 🔍 Prediction Example

```python
import torch

def predict(text):
    inputs = tokenizer(
        text,
        return_tensors="pt",
        truncation=True,
        max_length=512
    )

    with torch.no_grad():
        outputs = model(**inputs)

    probs = torch.softmax(outputs.logits, dim=1)
    toxic_score = probs[0][1].item()

    return toxic_score

text = "блін сервер впав, третій раз сьогодні"

score = predict(text)

label = "🚨 Toxic" if score > 0.5 else "✅ Safe"

print(f"""
Text: {text}

Score: {score:.3f}

Prediction: {label}
""")
```

Example output:

```text
Text: блін сервер впав, третій раз сьогодні

Score: 0.021

Prediction: ✅ Safe
```

---

# 🏗 Training

Train locally:

```bash
python train.py
```

Or inside Google Colab:

```python
!python train.py
```

---

# 📁 Repository Structure

```
Harmony-v2/
│
├── config.json
├── tokenizer.json
├── tokenizer_config.json
├── special_tokens_map.json
├── model.safetensors
├── train.py
├── requirements.txt
└── README.md
```

---

# 💡 Intended Use

Harmony v2 is suitable for:

- Telegram bots
- Discord moderation
- Forum moderation
- Live chat filtering
- AI assistants
- Comment moderation
- Social platforms
- Community management

---

# ❌ Not Intended For

Harmony v2 should **not** be used as the sole decision-maker for:

- legal decisions
- law enforcement
- employment screening
- medical applications

Human review is recommended for critical moderation.

---

# 📚 References

**Base model**

- gravitee-io/bert-tiny-toxicity

**Frameworks**

- Hugging Face Transformers
- Hugging Face Datasets
- PyTorch

---

# 📄 License

Licensed under the **Apache License 2.0**.

You are free to:

- ✅ use commercially
- ✅ modify
- ✅ redistribute
- ✅ include in proprietary software

Subject to the Apache-2.0 license terms.

---

# 🤝 Contributing

Pull requests, bug reports, and suggestions are welcome.

If you find a false positive or false negative, please open an issue.

---

# 🌸 Floxoris Labs

**Harmony v2** is developed by **Floxoris Labs**.

> *Lightweight AI. Maximum Intelligence.*