Community moderation queue with policy scoring

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.

Deterministic mode (default)

Deterministic mode is the default and the only mode guaranteed to work offline. The engine scores each message against policy.example.json (terms + regex) and applies the review / hide / escalate thresholds. For ambiguous or veiled threat language that no regex covers, a prudence fallback flags the message for human review as category threat with a cautious, score-derived confidence, so borderline cases never fall into allow.

Offline tests

python3 test_agent.py
bash smoke_test.sh

Expected result: both commands exit 0 without network access.

Use a local model (Ollama)

The optional LLM step can also run on your own machine through Ollama, so no text leaves your server. No account and no API key.

ollama pull <model>               # any chat model you like
export PACK_LLM=ollama            # prefer Ollama even if a coding-agent CLI is installed
export PACK_OLLAMA_MODEL=<model>  # optional: default is the first chat model the server lists
python3 -c "import llm_adapter; print(llm_adapter.detect())"   # prints: ollama

• PACK_OLLAMA_HOST points to another server (default http://127.0.0.1:11434); OLLAMA_HOST is also read when PACK_LLM=ollama.
• PACK_OLLAMA_NUM_CTX sets the context size if your reports or prompts are long.
• Without PACK_LLM, a local Ollama server is used only when no Claude Code, Kimi Code or Codex CLI is found.
• If the server is down or the model is missing, the pack keeps working in its deterministic mode.

Learning memory (local and private)

Every LLM call this pack makes is journaled in ./.pack_memory/ next to the code, so the pack can improve for you. Nothing is ever sent anywhere.

• What is kept: the task name, the masked input, the masked answer, status and latency. Keys, tokens, e-mails, phone numbers, IP addresses, card and IBAN numbers and personal paths are masked before writing; the system prompt is never stored.
• Teach it: python3 pack_memory.py feedback last ok confirms a result, python3 pack_memory.py feedback last bad --fix "the right answer" corrects it. Confirmed and corrected runs are reused as validated examples when a similar input comes in. Unrated runs are never injected into a prompt.
• Find similar cases: python3 pack_memory.py similar "some text" and python3 pack_memory.py clusters (groups of near-identical failures) work in plain Python, no model needed. Optional meaning-based matching uses an embedding model you already run locally: python3 pack_memory.py enable-semantic (Ollama on this machine only).
• Share, only if you want: python3 pack_memory.py export writes an anonymised summary (counts, statuses, size buckets, no text) for you to review.
• Control: PACK_MEMORY=0 turns it off, PACK_MEMORY_STORE_TEXT=0 keeps fingerprints only, python3 pack_memory.py purge --yes wipes it.