kea-cyberbully 0.1.0__tar.gz

kea_cyberbully-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KEA MINDZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kea_cyberbully-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include requirements.txt
+include pyproject.toml
+include LICENSE
+
+
+recursive-exclude models *
+recursive-exclude research *
+recursive-exclude tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * *.pt
+recursive-exclude * *.keras

kea_cyberbully-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: kea-cyberbully
+Version: 0.1.0
+Summary: Production-grade cyberbullying detection powered by transformer classifiers and nuance-aware multi-task learning.
+Author: KEA MINDZ
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KEA-Mindz/Cyberbully
+Project-URL: Repository, https://github.com/KEA-Mindz/Cyberbully
+Keywords: cyberbullying,nlp,transformers,pytorch,toxicity,moderation,deep-learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0.0
+Requires-Dist: transformers>=4.30.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: demoji>=1.1.0
+Requires-Dist: gdown>=5.0.0
+Requires-Dist: tqdm>=4.60.0
+Provides-Extra: eval
+Requires-Dist: scikit-learn>=1.0.0; extra == "eval"
+Requires-Dist: matplotlib>=3.5.0; extra == "eval"
+Requires-Dist: pandas>=1.4.0; extra == "eval"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# kea-cyberbully
+
+[![PyPI Version](https://img.shields.io/pypi/v/kea-cyberbully.svg)](https://pypi.org/project/kea-cyberbully/)
+[![Python Package](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://pypi.org/project/kea-cyberbully/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)
+[![Transformers](https://img.shields.io/badge/Transformers-HuggingFace-orange.svg)](https://huggingface.co/)
+
+Production-grade **Cyberbullying Text Detection** powered by transformer neural networks and nuance-aware multi-task learning. Developed by **KEA MINDZ**.
+
+Designed for social media moderation, chat moderation, comment screening, and trust & safety workflows.
+
+---
+
+## Key Features
+
+- **Multi-Task Neural Architecture**: Joint binary classifier (cyberbullying vs. safe) with a 20-way auxiliary intent head (threats, targeted insults, implicit mockery, backhanded compliments, sarcasm among friends, venting, etc.).
+- **Context & Nuance Aware**: Distinguishes harmful bullying from benign sarcasm among friends, self-venting, or constructive criticism.
+- **Adversarial Robustness**: Handles leetspeak (e.g. `@$$h0le`, `sna7ch`), typo variations, and emoji sentiment without breaking casing or punctuation.
+- **Lightweight Package (<15 KB)**: Compliant with PyPI upload limits by decoupling heavy 260MB model checkpoints and providing automatic background caching to `~/.cache/cyberbully/models/`.
+- **Flexible Interface**: Simple Python API and a rich interactive CLI.
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install kea-cyberbully
+```
+
+### From Source / Development
+
+```bash
+git clone https://github.com/KEA-Mindz/Cyberbully.git
+cd Cyberbully
+pip install -e .
+```
+
+### Optional Dependencies
+
+For running model evaluations and plotting metrics:
+```bash
+pip install -e ".[eval]"
+```
+
+For testing:
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Quickstart (Python API)
+
+### 1. Simple Boolean Check
+
+```python
+import cyberbully
+
+# True
+print(cyberbully.is_cyberbullying("Go jump off a cliff you loser"))
+
+# False
+print(cyberbully.is_cyberbullying("You are a wonderful person!"))
+```
+
+### 2. Detailed Prediction
+
+```python
+import cyberbully
+
+result = cyberbully.predict("Nobody likes you, you are ugly and pathetic")
+
+print(result.label)         # 'cyberbullying'
+print(result.score)         # 0.9996
+print(result.confidence)    # 0.9996
+print(result.category)      # 'targeted_insult_general'
+print(result.category_scores)
+# {
+#   'targeted_insult_general': 0.8227,
+#   'threat': 0.1511,
+#   ...
+# }
+```
+
+### 3. Explainability Diagnostics
+
+```python
+import cyberbully
+
+explanation = cyberbully.explain("You are so annoying")
+print(explanation)
+# {
+#   'text': 'You are so annoying',
+#   'prediction': 'cyberbullying',
+#   'cyberbullying_score': '0.9412',
+#   'threshold': '0.2300',
+#   'primary_intent_category': 'targeted_insult_general',
+#   'assessment': 'Flagged as cyberbullying (94.1% probability exceeds threshold 23.0%)'
+# }
+```
+
+### 4. Custom Model Instance & Batch Processing
+
+```python
+from cyberbully import CyberbullyingDetector
+
+# Automatically detects local models/ or downloads to cache on first use
+detector = CyberbullyingDetector()
+
+texts = [
+    "Have a fantastic day!",
+    "You are an idiot.",
+    "Can you please help review this PR?"
+]
+
+results = detector.predict(texts, batch_size=32)
+for res in results:
+    print(f"[{res.label.upper():17s}] ({res.score:.3f}) {res.text}")
+```
+
+---
+
+## Command-Line Interface (CLI)
+
+The package provides two alias commands: `kea-cyberbully` and `cyberbully`:
+
+### Classify Single or Multiple Texts
+
+```bash
+kea-cyberbully "You are a wonderful person"
+kea-cyberbully "Nobody likes you" --threshold 0.30
+```
+
+### Interactive Mode
+
+Launch an interactive evaluation console:
+
+```bash
+kea-cyberbully -i
+```
+
+### Batch Processing from CSV or Text Files
+
+```bash
+kea-cyberbully --file comments.csv --output flagged_results.csv
+```
+
+### Check Model Info & Cache
+
+```bash
+kea-cyberbully --info
+```
+
+### Pre-download Model Checkpoint
+
+```bash
+kea-cyberbully --download
+```
+
+---
+
+## Model Weights & Distribution
+
+The trained checkpoint (`best_model.pt`, ~265MB) is decoupled from the PyPI wheel for fast installation:
+
+1. **Local Search**: The detector first inspects:
+   - `models/cyberbully_v0.1_run`
+   - Explicit path specified via `--model-dir` or `CYBERBULLY_MODEL_DIR`
+2. **Cache Fallback**: If not found in local directories, it checks `~/.cache/cyberbully/models/cyberbully_v0.1_run`.
+3. **Auto-Download**: If missing, it downloads the checkpoint and tokenizer directly from Google Drive upon first execution.
+
+---
+
+## Repository Structure
+
+```text
+Cyberbully/
+├── .github/
+│   └── workflows/
+│       └── release.yaml          # Automated release & PyPI publishing workflow
+├── src/
+│   └── cyberbully/               # Core Python package
+│       ├── __init__.py           # Package exports & convenience API
+│       ├── __main__.py           # python -m cyberbully entrypoint
+│       ├── cli.py                # Command-line interface
+│       ├── detector.py           # CyberbullyingDetector engine
+│       ├── downloader.py         # Model downloader & cache management
+│       ├── model.py              # PyTorch MultiTaskClassifier architecture
+│       └── preprocessing.py      # Adversarial & social media text cleaner
+├── models/
+│   └── cyberbully_v0.1_run/      # Trained PyTorch model, tokenizer, and config
+├── tests/
+│   ├── test_detector.py          # Pytest suite for model inference
+│   └── test_preprocessing.py     # Unit tests for text normalization
+├── LICENSE                       # MIT License
+├── MANIFEST.in                   # Packaging exclusions
+├── pyproject.toml                # Modern PEP 621 / setuptools packaging
+├── requirements.txt              # Environment dependencies
+└── README.md                     # Documentation
+```
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

kea_cyberbully-0.1.0/README.md

@@ -0,0 +1,209 @@
+# kea-cyberbully
+
+[![PyPI Version](https://img.shields.io/pypi/v/kea-cyberbully.svg)](https://pypi.org/project/kea-cyberbully/)
+[![Python Package](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://pypi.org/project/kea-cyberbully/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)
+[![Transformers](https://img.shields.io/badge/Transformers-HuggingFace-orange.svg)](https://huggingface.co/)
+
+Production-grade **Cyberbullying Text Detection** powered by transformer neural networks and nuance-aware multi-task learning. Developed by **KEA MINDZ**.
+
+Designed for social media moderation, chat moderation, comment screening, and trust & safety workflows.
+
+---
+
+## Key Features
+
+- **Multi-Task Neural Architecture**: Joint binary classifier (cyberbullying vs. safe) with a 20-way auxiliary intent head (threats, targeted insults, implicit mockery, backhanded compliments, sarcasm among friends, venting, etc.).
+- **Context & Nuance Aware**: Distinguishes harmful bullying from benign sarcasm among friends, self-venting, or constructive criticism.
+- **Adversarial Robustness**: Handles leetspeak (e.g. `@$$h0le`, `sna7ch`), typo variations, and emoji sentiment without breaking casing or punctuation.
+- **Lightweight Package (<15 KB)**: Compliant with PyPI upload limits by decoupling heavy 260MB model checkpoints and providing automatic background caching to `~/.cache/cyberbully/models/`.
+- **Flexible Interface**: Simple Python API and a rich interactive CLI.
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install kea-cyberbully
+```
+
+### From Source / Development
+
+```bash
+git clone https://github.com/KEA-Mindz/Cyberbully.git
+cd Cyberbully
+pip install -e .
+```
+
+### Optional Dependencies
+
+For running model evaluations and plotting metrics:
+```bash
+pip install -e ".[eval]"
+```
+
+For testing:
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Quickstart (Python API)
+
+### 1. Simple Boolean Check
+
+```python
+import cyberbully
+
+# True
+print(cyberbully.is_cyberbullying("Go jump off a cliff you loser"))
+
+# False
+print(cyberbully.is_cyberbullying("You are a wonderful person!"))
+```
+
+### 2. Detailed Prediction
+
+```python
+import cyberbully
+
+result = cyberbully.predict("Nobody likes you, you are ugly and pathetic")
+
+print(result.label)         # 'cyberbullying'
+print(result.score)         # 0.9996
+print(result.confidence)    # 0.9996
+print(result.category)      # 'targeted_insult_general'
+print(result.category_scores)
+# {
+#   'targeted_insult_general': 0.8227,
+#   'threat': 0.1511,
+#   ...
+# }
+```
+
+### 3. Explainability Diagnostics
+
+```python
+import cyberbully
+
+explanation = cyberbully.explain("You are so annoying")
+print(explanation)
+# {
+#   'text': 'You are so annoying',
+#   'prediction': 'cyberbullying',
+#   'cyberbullying_score': '0.9412',
+#   'threshold': '0.2300',
+#   'primary_intent_category': 'targeted_insult_general',
+#   'assessment': 'Flagged as cyberbullying (94.1% probability exceeds threshold 23.0%)'
+# }
+```
+
+### 4. Custom Model Instance & Batch Processing
+
+```python
+from cyberbully import CyberbullyingDetector
+
+# Automatically detects local models/ or downloads to cache on first use
+detector = CyberbullyingDetector()
+
+texts = [
+    "Have a fantastic day!",
+    "You are an idiot.",
+    "Can you please help review this PR?"
+]
+
+results = detector.predict(texts, batch_size=32)
+for res in results:
+    print(f"[{res.label.upper():17s}] ({res.score:.3f}) {res.text}")
+```
+
+---
+
+## Command-Line Interface (CLI)
+
+The package provides two alias commands: `kea-cyberbully` and `cyberbully`:
+
+### Classify Single or Multiple Texts
+
+```bash
+kea-cyberbully "You are a wonderful person"
+kea-cyberbully "Nobody likes you" --threshold 0.30
+```
+
+### Interactive Mode
+
+Launch an interactive evaluation console:
+
+```bash
+kea-cyberbully -i
+```
+
+### Batch Processing from CSV or Text Files
+
+```bash
+kea-cyberbully --file comments.csv --output flagged_results.csv
+```
+
+### Check Model Info & Cache
+
+```bash
+kea-cyberbully --info
+```
+
+### Pre-download Model Checkpoint
+
+```bash
+kea-cyberbully --download
+```
+
+---
+
+## Model Weights & Distribution
+
+The trained checkpoint (`best_model.pt`, ~265MB) is decoupled from the PyPI wheel for fast installation:
+
+1. **Local Search**: The detector first inspects:
+   - `models/cyberbully_v0.1_run`
+   - Explicit path specified via `--model-dir` or `CYBERBULLY_MODEL_DIR`
+2. **Cache Fallback**: If not found in local directories, it checks `~/.cache/cyberbully/models/cyberbully_v0.1_run`.
+3. **Auto-Download**: If missing, it downloads the checkpoint and tokenizer directly from Google Drive upon first execution.
+
+---
+
+## Repository Structure
+
+```text
+Cyberbully/
+├── .github/
+│   └── workflows/
+│       └── release.yaml          # Automated release & PyPI publishing workflow
+├── src/
+│   └── cyberbully/               # Core Python package
+│       ├── __init__.py           # Package exports & convenience API
+│       ├── __main__.py           # python -m cyberbully entrypoint
+│       ├── cli.py                # Command-line interface
+│       ├── detector.py           # CyberbullyingDetector engine
+│       ├── downloader.py         # Model downloader & cache management
+│       ├── model.py              # PyTorch MultiTaskClassifier architecture
+│       └── preprocessing.py      # Adversarial & social media text cleaner
+├── models/
+│   └── cyberbully_v0.1_run/      # Trained PyTorch model, tokenizer, and config
+├── tests/
+│   ├── test_detector.py          # Pytest suite for model inference
+│   └── test_preprocessing.py     # Unit tests for text normalization
+├── LICENSE                       # MIT License
+├── MANIFEST.in                   # Packaging exclusions
+├── pyproject.toml                # Modern PEP 621 / setuptools packaging
+├── requirements.txt              # Environment dependencies
+└── README.md                     # Documentation
+```
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

kea_cyberbully-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kea-cyberbully"
+version = "0.1.0"
+
+description = "Production-grade cyberbullying detection powered by transformer classifiers and nuance-aware multi-task learning."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+keywords = ["cyberbullying", "nlp", "transformers", "pytorch", "toxicity", "moderation", "deep-learning"]
+authors = [
+    { name = "KEA MINDZ" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "torch>=2.0.0",
+    "transformers>=4.30.0",
+    "numpy>=1.20.0",
+    "demoji>=1.1.0",
+    "gdown>=5.0.0",
+    "tqdm>=4.60.0",
+]
+
+[project.optional-dependencies]
+eval = [
+    "scikit-learn>=1.0.0",
+    "matplotlib>=3.5.0",
+    "pandas>=1.4.0",
+]
+dev = [
+    "pytest>=7.0.0",
+    "flake8>=6.0.0",
+]
+
+[project.scripts]
+cyberbully = "cyberbully.cli:main"
+kea-cyberbully = "cyberbully.cli:main"
+
+
+[project.urls]
+Homepage = "https://github.com/KEA-Mindz/Cyberbully"
+Repository = "https://github.com/KEA-Mindz/Cyberbully"
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["cyberbully*"]

kea_cyberbully-0.1.0/requirements.txt

@@ -0,0 +1,33 @@
+
+
+gdown
+seaborn
+
+ 
+
+
+
+# ============================================================
+# Cyberbullying Detection - DistilBERT fine-tuning pipeline
+# Install with:  pip install -r requirements.txt
+# ============================================================
+
+# --- core deep learning ---
+torch>=2.1.0              # if you have an NVIDIA GPU, instead install the CUDA build from
+                           # https://pytorch.org/get-started/locally/ (pick your CUDA version)
+transformers>=4.38.0       # AutoTokenizer / AutoModel / get_linear_schedule_with_warmup
+
+# --- data + metrics ---
+pandas>=2.0.0
+numpy>=1.24.0
+scikit-learn>=1.3.0        # StratifiedGroupKFold, F1/precision/recall/ROC-AUC/PR-AUC
+
+# --- utilities used by the script ---
+tqdm>=4.66.0                # progress bars + ETA during training/eval
+demoji>=1.1.0                # emoji -> text description (optional but recommended, script
+                             # auto-detects if missing and just skips emoji handling)
+matplotlib>=3.7.0            # confusion_matrix.png and training_history.png
+
+# --- only needed if you switch --model to a deberta-v3 checkpoint ---
+# sentencepiece>=0.1.99
+# tiktoken>=0.5.0

kea_cyberbully-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kea_cyberbully-0.1.0/src/cyberbully/__init__.py

@@ -0,0 +1,70 @@
+"""Cyberbully: Production-ready Cyberbullying Text Detection package.
+
+Detects cyberbullying, toxic harassment, threats, and subtle mockery with
+adversarial leetspeak and nuance robustness.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+from cyberbully.detector import CyberbullyingDetector, PredictionResult
+from cyberbully.downloader import download_model
+from cyberbully.preprocessing import clean_text
+
+__version__ = "0.1.0"
+__all__ = [
+    "CyberbullyingDetector",
+    "PredictionResult",
+    "clean_text",
+    "download_model",
+    "predict",
+    "is_cyberbullying",
+    "explain",
+    "__version__",
+]
+
+_DEFAULT_DETECTOR: CyberbullyingDetector | None = None
+
+
+def get_default_detector() -> CyberbullyingDetector:
+    """Retrieve or lazily initialize the shared global detector instance."""
+    global _DEFAULT_DETECTOR
+    if _DEFAULT_DETECTOR is None:
+        _DEFAULT_DETECTOR = CyberbullyingDetector()
+    return _DEFAULT_DETECTOR
+
+
+def predict(
+    texts: str | Sequence[str],
+    threshold: float | None = None,
+    batch_size: int = 32,
+) -> PredictionResult | list[PredictionResult]:
+    """Classify text using the default detector instance.
+    
+    Example:
+        >>> import cyberbully
+        >>> res = cyberbully.predict("you are awesome!")
+        >>> print(res.label)
+        'not_cyberbullying'
+    """
+    detector = get_default_detector()
+    return detector.predict(texts, threshold=threshold, batch_size=batch_size)
+
+
+def is_cyberbullying(text: str, threshold: float | None = None) -> bool:
+    """Check if a text is cyberbullying using the default detector instance.
+    
+    Example:
+        >>> import cyberbully
+        >>> cyberbully.is_cyberbullying("you are so ugly")
+        True
+    """
+    detector = get_default_detector()
+    return detector.is_cyberbullying(text, threshold=threshold)
+
+
+def explain(text: str, threshold: float | None = None) -> dict[str, Any]:
+    """Generate detailed breakdown and top category scores for a text."""
+    detector = get_default_detector()
+    return detector.explain(text, threshold=threshold)

kea_cyberbully-0.1.0/src/cyberbully/__main__.py

@@ -0,0 +1,7 @@
+"""Module entry point for python -m cyberbully."""
+
+import sys
+from cyberbully.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())