moderators 0.1.3

Moderators: One package to moderate them all

Run open‑source content moderation models (NSFW, nudity, etc.) with one line — from Python or the CLI.

✨ Key Highlights

• One simple API and CLI
• Use any compatible Transformers model from the Hub or disk
• Normalized JSON output you can plug into your app
• Optional auto‑install of dependencies for a smooth first run

🚀 Performance

NSFW image detection performance on the LSPD test set. Models with nsfw-detection-2 prefix support 5-class classification (safe, porn, hentai, drawing, sexy). F_macro is the macro-averaged F1 score across all classes.

Model	F_macro	F_safe	F_porn	F_hentai	F_drawing	F_sexy	Params
nsfw-detection-2-nano	93.00%	96.82%	96.34%	93.43%	93.24%	85.15%	4M
nsfw-detection-2-mini	96.09%	98.59%	98.05%	96.06%	96.83%	90.92%	17M
nsfw-detection-1-mini	N/A	97.90%	N/A	N/A	N/A	N/A	17M
Azure AI	N/A	96.79%	N/A	N/A	N/A	N/A	N/A
Falconsai	N/A	89.52%	N/A	N/A	N/A	N/A	85M

📦 Installation

pip install moderators

For detailed installation options, see the Installation Guide.

🚀 Quickstart

Python API:

from moderators import AutoModerator

# Load from the Hugging Face Hub (e.g., NSFW image classifier)
moderator = AutoModerator.from_pretrained("viddexa/nsfw-detection-2-mini")

# Run on a local image path
result = moderator("/path/to/image.jpg")
print(result)

CLI:

# Image classification
moderators viddexa/nsfw-detection-2-mini /path/to/image.jpg

# Text classification
moderators distilbert/distilbert-base-uncased-finetuned-sst-2-english "I love this!"

📊 Real Output Example

Moderators normalized JSON output:

[
  {
    "source_path": "",
    "classifications": { "safe": 0.9998 },
    "detections": [],
    "raw_output": { "label": "safe", "score": 0.9998 }
  },
  {
    "source_path": "",
    "classifications": { "drawing": 0.0001 },
    "detections": [],
    "raw_output": { "label": "drawing", "score": 0.0001 }
  },
  {
    "source_path": "",
    "classifications": { "sexy": 0.0001 },
    "detections": [],
    "raw_output": { "label": "sexy", "score": 0.0001 }
  }
]

🔍 Comparison at a Glance

Feature	Transformers.pipeline()	Moderators
Usage	pipeline("task", model=...)	AutoModerator.from_pretrained(...)
Model configuration	Manual or model-specific	Automatic via config.json (task inference when possible)
Output format	Varies by model/pipe	Standardized PredictionResult / JSON
Requirements	Manual dependency setup	Optional automatic pip/uv install
CLI	None or project-specific	Built-in moderators CLI (JSON to stdout)
Extensibility	Mostly one ecosystem	Open to new integrations (same interface)
Error messages	Vary by model	Consistent, task/integration-guided
Task detection	User-provided	Auto-inferred from config when possible

🎯 Pick a Model

• From the Hub: Pass a model ID like viddexa/nsfw-detection-2-mini or any compatible Transformers model
• From disk: Pass a local folder that contains a config.json next to your weights

Moderators detects the task and integration from the config when possible, so you don't have to specify pipelines manually.

📚 Documentation

• Installation Guide - Detailed installation options and requirements
• CLI Reference - Complete command-line usage guide
• API Documentation - Python API reference and output formats
• FAQ - Frequently asked questions
• Troubleshooting - Common issues and solutions

📝 Examples

Small demos and benchmarking script: examples/README.md, examples/benchmarks.py

🗺️ Roadmap

• Ultralytics integration (YOLO family) via UltralyticsModerator
• Optional ONNX Runtime backend where applicable
• Simple backend switch (API/CLI flag, e.g., --backend onnx|torch)
• Expanded benchmarks: latency, throughput, memory on common tasks

📖 Citation

If you use this package in your work, please cite:

@article{akyon2023nudity,
  title={State-of-the-Art in Nudity Classification: A Comparative Analysis},
  author={Akyon, Fatih Cagatay and Temizel, Alptekin},
  booktitle={2023 IEEE International Conference on Acoustics, Speech, and Signal Processing Workshops (ICASSPW)},
  pages={1--5},
  year={2023},
  organization={IEEE},
  doi={10.1109/ICASSPW59220.2023.10193621},
  url={https://ieeexplore.ieee.org/abstract/document/10193621/}
}

@article{akyon2022contentmoderation,
  title={Deep Architectures for Content Moderation and Movie Content Rating},
  author={Akyon, Fatih Cagatay and Temizel, Alptekin},
  journal={arXiv preprint arXiv:2212.04533},
  year={2022},
  doi={10.48550/arXiv.2212.04533},
  url={https://arxiv.org/abs/2212.04533}
}

📄 License

Apache-2.0. See LICENSE.