README.md

# 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.*