Chat Moderator - LOCAL AI

Chat Moderator – AI-Assisted Chat Moderation for Paper 1.21

A lightweight, free, AI-assisted chat moderation plugin for Paper 1.21 Minecraft servers. ChatMod combines fast regex/language filtering with an optional offline ONNX-based classifier to accurately moderate toxic, hateful, sexual, and harassing messages without paid APIs.

Features

- Hybrid moderation: regex + optional RoBERTa ONNX AI - Identity-aware hate detection (no API keys required) - Language detection and blocking - Tunable thresholds, punishments, and strict mode - Admin tools for review, training, and status - Persistent stats with autosave (SQLite/MySQL) and auto-migration - File/DB logging and review tools - Performance-optimized with async classification and caching - Works fully offline (no paid APIs) - Highly configurable and extensible

Installation

1. Drop `ChatModer.jar` into your server `plugins/` directory 2. Restart the server to generate `plugins/ChatModer/config.yml` 3. (Optional) Add an ONNX model folder under `plugins/ChatModer/models/` and point the config to the ONNX file

AI Model Setup (Hugging Face RoBERTa)

ChatModer supports Hugging Face RoBERTa ONNX models, e.g. `protectai/unbiased-toxic-roberta-onnx`.

Create a folder like: ``` plugins/ChatModer/models/unbiased-toxic-roberta-onnx/ ``` Put these files inside: - `model_quantized.onnx` (recommended) or `model.onnx` - `config.json` (contains id2label/label2id) - `tokenizer.json` (preferred), or `vocab.json` + `merges.txt` - Optional: `tokenizer_config.json`, `special_tokens_map.json`

Config snippet: ```yaml moderation: ai: enabled: true model_path: plugins/ChatModer/models/unbiased-toxic-roberta-onnx/model_quantized.onnx max_sequence_length: 128 async_threads: 2 timeout_ms: 500 ``` The tokenizer/config are auto-loaded from the same folder as the ONNX.

Label Mapping

- `obscene` -> `profanity` - `insult`/`threat` -> `harassment` - `sexual_explicit` -> `sexual` - `identity_attack` -> `hate` - `toxicity`/`severe_toxicity` boost profanity/harassment slightly - Identity-only labels (e.g., `black`, `muslim`) are not flagged by themselves; they serve as context when combined with insult/toxicity

Modes

- __regex__: Only regex/wordlist heuristics - __ai-only__: Only ONNX model (if enabled); still uses language blocking and whitelist - __hybrid__ (recommended): Combine regex + AI; AI score can be weighted via `moderation.ai.weight`

```yaml moderation: enabled: true mode: hybrid # regex | ai-only | hybrid ai: enabled: true weight: 0.8 ```

Database & Autosave

Stats are persisted to SQLite by default or MySQL if configured. The plugin can auto-migrate existing SQLite stats to MySQL.

```yaml database: type: sqlite sqlite_file: plugins/ChatModer/data.db mysql: host: 127.0.0.1 port: 3306 database: chatmoder user: root password: "secret" useSSL: false sqlite_migrate_file: plugins/ChatModer/data.db

stats: autosave_seconds: 300 ```

Thresholds & Punishments

Fine-tune moderation sensitivity and actions per category.

```yaml thresholds: profanity: 0.7 harassment: 0.6 hate: 0.6 sexual: 0.7 spam: 0.8

punishments: profanity: block # warn | tempmute | kick | tempban | block | command:<cmd> harassment: warn hate: tempmute sexual: block spam: block ```

Logging & Review

- __File logs__: JSONL written to `plugins/ChatModer/logs/flags.log` - __DB logs__: SQLite/MySQL `flags` table (optional) - __Review__: `/chatmod review <player>` reads from DB if enabled, else file logs. Supports legacy pretty-printed logs and compact JSONL.

Commands

- `/chatmod toggle` — Enable/disable moderation. - `/chatmod status` — Live stats overview. - `/chatmod review <player>` — Review recent flagged messages. - `/chatmod whitelist add|remove <word>` — Manage whitelist. - `/chatmod strict reload` — Reload strict list. - `/chatmod train add|capture|fromlog|words|stats|export` — Dataset tools. - `/chatmod stats reset confirm` — Clear in-memory stats and persist immediately.

Training Workflow (Optional)

- __Capture__: record recent messages as context for training - __From log__: mine flagged logs into a dataset - __Words__: word frequency analysis - __Stats__: training dataset stats - __Export__: outputs `dataset.jsonl` ready for fine-tuning

All tools are available under `/chatmod train ...`.

Strict Mode

For immediate blocks (e.g., high-severity tokens), enable strict rules and reload them without a restart:

``` /chatmod strict reload ```

Permissions

- `chatmod.admin` — Access to admin commands - `chatmod.bypass` — Bypass moderation - `chatmod.review` — Access review tools

Performance

- Regex-only mode for minimal overhead - AI runs asynchronously and uses a quantized ONNX model on CPU - Token and message caching to reduce repeated work

Privacy

All processing is local. No external API calls are made unless you enable webhooks.

Compatibility

- Paper 1.21 (most modern forks should work) - Java 17+ - SQLite included; MySQL requires valid credentials

Troubleshooting

- __ONNX model not loading__: Check `moderation.ai.model_path` and ensure `config.json` and `tokenizer.json` (or `vocab.json` + `merges.txt`) are in the same directory. - __Classification timeout__: Increase `moderation.ai.timeout_ms` or reduce `max_sequence_length`. - __High CPU__: Use `model_quantized.onnx` and keep `max_sequence_length` at 128/256. - __Review shows no entries__: Ensure logging is enabled (file or DB) and that your logs aren’t empty.

Support

Open an issue on the project repository with logs, configs, and steps to reproduce. Provide model details if you use a custom model.