Update README.md

README.md

@@ -1,108 +1,152 @@
-Harmony v2 — Toxicity Classifier
+# Harmony v2 — Toxicity Classifier
 
-Lightweight, context-aware toxicity detection that reads intent, not just keywords.
+> **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**.
 
-🧠 Model Overview
+> **Profanity ≠ Toxicity**
 
-Harmony v2 is a fine-tuned version of gravitee-io/bert-tiny-toxicity trained on a custom 7000-sample dataset (HarmonyDataset v2). It distinguishes between:
+---
 
+# 🧠 Overview
 
+Harmony v2 is designed for modern chat moderation, especially for Telegram communities, forums, games, and social platforms.
 
-Toxic: Direct personal attacks, harassment, threats, humiliation, dehumanization.
+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
 
-Safe: Emotional expression, profanity without a target, frustration, jokes, sarcasm, friendly banter.
+Instead of blocking words, Harmony v2 evaluates **intent**.
 
+---
 
+# ✨ Features
 
-Core philosophy:
+| 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 | ~184 MB (INT8) |
+| License | Apache-2.0 |
 
-Profanity ≠ toxicity.
+---
 
-The model learns to recognize intent and target, not just a list of "bad words."
+# ⚡ Performance
 
+| Metric | Result |
+|---------|--------|
+| Evaluation Loss | **0.4255** |
+| F1 Score | **98.4%** |
+| CPU Inference | **~11 ms** |
+| Precision | High |
+| Recall | High |
 
+---
 
-📊 Key Features
+# 📊 Dataset
 
-Feature	Details
+HarmonyDataset v2 contains **7,000 balanced synthetic chat messages**.
 
-Base model	gravitee-io/bert-tiny-toxicity
+| Category | Share |
+|----------|------:|
+| Safe | 15% |
+| Friendly profanity | 10% |
+| Frustration | 10% |
+| Self-insult | 5% |
+| Joke | 10% |
+| Sarcasm | 10% |
+| Criticism | 5% |
+| Insult | 10% |
+| Harassment | 15% |
+| Threat | 10% |
 
-Training data	7,000 human-like Telegram/chat messages
+Dataset philosophy:
 
-Context window	512 tokens
+- realistic conversations
+- Telegram-like writing
+- slang
+- spelling mistakes
+- emojis
+- mixed Ukrainian/Russian
+- contextual toxicity
 
-Format	PyTorch (Hugging Face compatible)
+---
 
-Size	\~184 MB (int8)
+# 🚀 Installation
 
-License	Apache-2.0
-
-⚡ Performance
-
-Metric	Value
-
-Evaluation loss	0.4255
-
-F1 score	98.4%
-
-Languages	Ukrainian, Russian, mixed (UA/RU)
-
-Inference latency	\~11 ms on CPU
-
-🚀 Quick Start
-
-1\. Clone \& install
-
-bash
+Clone the repository:
 
+```bash
 git clone https://github.com/your-username/harmony-v2
-
 cd harmony-v2
+```
 
-pip install -r requirements.txt
-
-2\. Load model in Python
-
-python
+Install dependencies:
 
-from transformers import AutoTokenizer, AutoModelForSequenceClassification
+```bash
+pip install -r requirements.txt
+```
 
+---
 
+# 📦 Load the Model
 
-model\_path = "./Harmony-v2"
+```python
+from transformers import (
+    AutoTokenizer,
+    AutoModelForSequenceClassification
+)
 
-tokenizer = AutoTokenizer.from\_pretrained(model\_path)
+model_path = "./Harmony-v2"
 
-model = AutoModelForSequenceClassification.from\_pretrained(model\_path)
+tokenizer = AutoTokenizer.from_pretrained(model_path)
+model = AutoModelForSequenceClassification.from_pretrained(model_path)
+```
 
-3\. Predict
+---
 
-python
+# 🔍 Prediction Example
 
+```python
 import torch
 
-
-
 def predict(text):
+    inputs = tokenizer(
+        text,
+        return_tensors="pt",
+        truncation=True,
+        max_length=512
+    )
 
-    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
+    with torch.no_grad():
+        outputs = model(**inputs)
 
+    probs = torch.softmax(outputs.logits, dim=1)
+    toxic_score = probs[0][1].item()
 
+    return toxic_score
 
 text = "блін сервер впав, третій раз сьогодні"
 
@@ -110,77 +154,127 @@ score = predict(text)
 
 label = "🚨 Toxic" if score > 0.5 else "✅ Safe"
 
-print(f"Text: {text}\\nScore: {score:.2f} → {label}")
+print(f"""
+Text: {text}
 
-📂 Dataset
+Score: {score:.3f}
 
-Trained on HarmonyDataset v2 — 7,000 synthetically generated samples with balanced categories:
+Prediction: {label}
+""")
+```
 
+Example output:
 
+```text
+Text: блін сервер впав, третій раз сьогодні
 
-Category	Share
+Score: 0.021
 
-Safe	15%
+Prediction: ✅ Safe
+```
 
-Friendly profanity	10%
+---
 
-Frustration	10%
+# 🏗 Training
 
-Self-insult	5%
+Train locally:
 
-Joke	10%
+```bash
+python train.py
+```
 
-Sarcasm	10%
+Or inside Google Colab:
 
-Criticism	5%
+```python
+!python train.py
+```
 
-Insult	10%
+---
 
-Harassment	15%
+# 📁 Repository Structure
 
-Threat	10%
+```
+Harmony-v2/
+│
+├── config.json
+├── tokenizer.json
+├── tokenizer_config.json
+├── special_tokens_map.json
+├── model.safetensors
+├── train.py
+├── requirements.txt
+└── README.md
+```
 
-🔧 Training
+---
 
-Run the training script:
+# 💡 Intended Use
 
+Harmony v2 is suitable for:
 
+- Telegram bots
+- Discord moderation
+- Forum moderation
+- Live chat filtering
+- AI assistants
+- Comment moderation
+- Social platforms
+- Community management
 
-bash
+---
 
-python train.py
+# ❌ Not Intended For
 
-Or use the provided Colab notebook:
+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.
 
-python
+---
 
-\# Launch training directly in Colab
+# 📚 References
 
-!python train.py
+**Base model**
 
-📄 License
+- gravitee-io/bert-tiny-toxicity
 
-Apache-2.0 — free for commercial and research use.
+**Frameworks**
 
+- Hugging Face Transformers
+- Hugging Face Datasets
+- PyTorch
 
+---
 
-🙋 Feedback / Contributions
+# 📄 License
 
-Open an issue or PR on GitHub — feedback welcome.
+Licensed under the **Apache License 2.0**.
 
+You are free to:
 
+- ✅ use commercially
+- ✅ modify
+- ✅ redistribute
+- ✅ include in proprietary software
 
-📎 References
+Subject to the Apache-2.0 license terms.
 
-Base model: gravitee-io/bert-tiny-toxicity
+---
 
+# 🤝 Contributing
 
+Pull requests, bug reports, and suggestions are welcome.
 
-Framework: Hugging Face transformers + datasets
+If you find a false positive or false negative, please open an issue.
 
+---
 
+# 🌸 Floxoris Labs
 
-Built by Floxoris Labs — lightweight AI, maximum intelligence.
+**Harmony v2** is developed by **Floxoris Labs**.
 
+> *Lightweight AI. Maximum Intelligence.*