Autonomous community moderation pack for operators who receive recurring user messages, comments, chat exports, forum posts, marketplace reviews, or support side conversations and need a repeatable triage lane before a human moderator spends time on them.

The pack does not promise perfect safety decisions. It provides a practical offline core that classifies messages, records evidence, proposes actions, and keeps an escalation queue. If a local BYO-LLM CLI is available, the agent can use the prompts in PROMPTS.md to enrich the reasoning, while the deterministic rules remain the fallback path.

Who it is for

Community operators running Discord, Slack, forums, comments, or review queues.
LLM app owners who need predictable moderation before publishing user text.
Support teams that want abuse, spam, privacy, and escalation signals separated.
Solo founders who need an audit trail without wiring a moderation SaaS first.

What it does

Reads JSONL messages from a watch file.
Applies policy rules from policy.example.json or your own policy file.
Scores each message across spam, abuse, privacy, self-harm, and escalation.
Writes decisions to SQLite and JSON reports.
Exposes --help, ingest, run, status, review, and export commands.
Runs offline with no API key and no network dependency.

Quick start

python3 agent.py --help
python3 agent.py ingest --input sample_messages.jsonl
python3 agent.py run --once --deterministic
python3 agent.py status
python3 agent.py export --output moderation_report.json

One-shot Debian install:

sudo bash install.sh

Local venv only:

bash install.sh --no-service
./venv/bin/python agent.py ingest --input sample_messages.jsonl
./venv/bin/python agent.py run --once

Architecture

          JSONL comments / chats / posts
                         |
                         v
               +-------------------+
               | ingest queue      |
               | SQLite tasks      |
               +---------+---------+
                         |
                         v
               +-------------------+
               | observe           |
               | normalize text    |
               +---------+---------+
                         |
                         v
               +-------------------+
               | orient            |
               | policy matching   |
               +---------+---------+
                         |
                         v
               +-------------------+
               | decide            |
               | allow / review    |
               | hide / escalate   |
               +---------+---------+
                         |
                         v
               +-------------------+
               | act               |
               | audit + report    |
               +-------------------+

Message format

Each line is one JSON object:

{"message_id":"m-001","author":"user-17","channel":"general","text":"Buy now at spam.example","created_at":"2026-06-20T10:00:00Z"}

Required fields: message_id, text.

Optional fields: author, channel, created_at, thread_id, metadata.

Action model

allow: no configured rule reached a review threshold.
review: suspicious enough for a human queue.
hide: high-confidence spam or abuse under the local policy.
escalate: safety, privacy, threat, or legal pattern requiring urgent review.

BYO-LLM mode

The pack imports llm_adapter.py. If one of claude, kimi-code, or codex is installed and logged in, the agent can call it locally. No API key is required. If no CLI is available, the agent keeps running in deterministic mode.

Offline tests

python3 test_agent.py
bash smoke_test.sh

Expected result: both commands exit 0 without network access.

Agent Moderation Pack v1.0

What's inside