jevmod 0.2.0__py3-none-any.whl

jevmod/adapters/telegram_bot.py

@@ -0,0 +1,206 @@
+"""Telegram adapter. Add the bot to a group as admin; it flags by replying in a private admin chat (or the group's
+log topic) and can delete or mute when you enable it. Commands for admins: /mod_status, /mod_set, /mod_rule, /mod_log.
+
+    TELEGRAM_TOKEN=... TYPESAFE_API_KEY=... python -m jevmod.adapters.telegram_bot
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from telegram import ChatPermissions, Update
+from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters
+
+from ..core import FREE_MONTHLY, Batcher, ModerationService, Store
+from ..judge import CATEGORIES, Message
+
+log = logging.getLogger("jevmod.telegram")
+store = Store(os.environ.get("JEVMOD_DB", "jevmod.sqlite"))
+service = ModerationService(store)
+
+
+def tenant_of(chat_id: int) -> str:
+    return f"telegram:{chat_id}"
+
+
+async def _is_admin(update: Update, context: ContextTypes.DEFAULT_TYPE) -> bool:
+    if not update.effective_chat or not update.effective_user:
+        return False
+    member = await context.bot.get_chat_member(update.effective_chat.id, update.effective_user.id)
+    return member.status in ("administrator", "creator")
+
+
+async def handle_batch(tenant: str, batch: list[tuple[Update, ContextTypes.DEFAULT_TYPE]]) -> None:
+    chat_id = batch[0][0].effective_chat.id  # type: ignore[union-attr]
+    context = batch[0][1]
+    admins = {m.user.id for m in await context.bot.get_chat_administrators(chat_id)}
+    msgs = []
+    for upd, _ in batch:
+        m = upd.effective_message
+        if m is None:
+            continue
+        msgs.append(
+            Message(
+                id=str(m.message_id),
+                text=m.text or m.caption or "",
+                author=m.from_user.full_name if m.from_user else "",
+                channel_topic=store.get_meta(tenant).get("topic", "group chat"),
+                author_trusted=bool(m.from_user and m.from_user.id in admins),
+            )
+        )
+    decisions = await asyncio.to_thread(service.moderate, tenant, msgs)
+    policy = service.policy(tenant)
+    for (upd, ctx), d in zip(batch, decisions, strict=True):
+        if d.reason == "quota":
+            if store.note_quota_hit(tenant):
+                await _log(
+                    ctx,
+                    tenant,
+                    chat_id,
+                    f"jevmod paused this month: the monthly quota of {FREE_MONTHLY:,} judged messages was reached.",
+                )
+            return
+        if d.action == "none":
+            continue
+        m = upd.effective_message
+        if m is None:
+            continue
+        note = ""
+        try:
+            if d.action in ("delete", "timeout"):
+                await m.delete()
+                note = "deleted"
+            if d.action == "timeout" and m.from_user:
+                until = datetime.now(timezone.utc) + timedelta(minutes=policy.timeout_minutes)
+                await ctx.bot.restrict_chat_member(
+                    chat_id, m.from_user.id, ChatPermissions(can_send_messages=False), until_date=until
+                )
+                note = f"deleted, muted {policy.timeout_minutes} min"
+        except Exception as exc:
+            note = f"could not act: {type(exc).__name__}"
+        top = " · ".join(f"{c} {p:.2f}" for c, p in sorted(d.scores.items(), key=lambda kv: -kv[1])[:3])
+        text = (
+            f"{d.category}  p={d.probability:.2f}  →  {d.action}" + (f" ({note})" if note else "") + "\n"
+            f"from {msgs[0].author if len(msgs) == 1 else (m.from_user.full_name if m.from_user else '?')}: "
+            f"{(m.text or m.caption or '')[:300]}\n{top}"
+        )
+        await _log(ctx, tenant, chat_id, text)
+
+
+async def _log(context: ContextTypes.DEFAULT_TYPE, tenant: str, chat_id: int, text: str) -> None:
+    target = store.get_meta(tenant).get("log_chat", chat_id)
+    try:
+        await context.bot.send_message(int(target), text, disable_web_page_preview=True)
+    except Exception as exc:
+        log.warning("cannot log to %s: %s", target, exc)
+
+
+batcher = Batcher(2.0, handle_batch)
+
+
+async def on_message(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    m = update.effective_message
+    if not m or not update.effective_chat or update.effective_chat.type == "private":
+        return
+    if not (m.text or m.caption) or (m.from_user and m.from_user.is_bot):
+        return
+    tenant = tenant_of(update.effective_chat.id)
+    if not service.policy(tenant).active():
+        return
+    batcher.add(tenant, (update, context))
+
+
+def _reply(update: Update) -> Any:
+    assert update.effective_message is not None
+    return update.effective_message.reply_text
+
+
+async def cmd_status(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    if not await _is_admin(update, context):
+        return
+    tenant = tenant_of(update.effective_chat.id)  # type: ignore[union-attr]
+    p = service.policy(tenant)
+    judged, requests, tokens = store.usage(tenant)
+    lines = [f"{c}: {p.actions.get(c, 'off')} at p ≥ {p.thresholds.get(c, 0.9):.2f}" for c in CATEGORIES]
+    lines += [f'rule {n}: {p.rule_actions.get(n, "flag")} · "{r}"' for n, r in p.rules.items()]
+    cap = f"/{FREE_MONTHLY:,}" if FREE_MONTHLY else ""
+    lines.append(f"\n{judged:,}{cap} judged this month · {requests} Jev requests · {tokens:,} tokens")
+    await _reply(update)("\n".join(lines))  # type: ignore[union-attr]
+
+
+async def cmd_set(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """/mod_set <category> <action> [threshold]"""
+    if not await _is_admin(update, context):
+        return
+    args = context.args or []
+    tenant = tenant_of(update.effective_chat.id)  # type: ignore[union-attr]
+    p = service.policy(tenant)
+    try:
+        p.set_category(args[0], args[1], float(args[2]) if len(args) > 2 else None)
+    except (IndexError, ValueError) as exc:
+        await _reply(update)(f"usage: /mod_set <category> <off|flag|delete|timeout> [0.5-0.99]\n{exc}")  # type: ignore[union-attr]
+        return
+    service.save_policy(tenant, p)
+    await _reply(update)(f"{args[0]} → {args[1]} at p ≥ {p.thresholds[args[0]]:.2f}")  # type: ignore[union-attr]
+
+
+async def cmd_rule(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """/mod_rule <name> <text...>   or   /mod_rule <name> remove"""
+    if not await _is_admin(update, context):
+        return
+    args = context.args or []
+    if not args:
+        await _reply(update)("usage: /mod_rule <name> <rule text> | /mod_rule <name> remove")  # type: ignore[union-attr]
+        return
+    tenant = tenant_of(update.effective_chat.id)  # type: ignore[union-attr]
+    p = service.policy(tenant)
+    text = " ".join(args[1:])
+    try:
+        p.set_rule(args[0], None if text.strip().lower() == "remove" else text)
+    except ValueError as exc:
+        await _reply(update)(str(exc))  # type: ignore[union-attr]
+        return
+    service.save_policy(tenant, p)
+    await _reply(update)(f"rules: {p.rules}")  # type: ignore[union-attr]
+
+
+async def cmd_log(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    """Run in the chat where you want decisions logged (a private admins group works well)."""
+    if not await _is_admin(update, context):
+        return
+    args = context.args or []
+    if not args:
+        await _reply(update)("usage: /mod_log <chat id of the group to moderate>  (run this in the log chat)")  # type: ignore[union-attr]
+        return
+    store.set_meta(tenant_of(int(args[0])), log_chat=update.effective_chat.id)  # type: ignore[union-attr]
+    await _reply(update)("decisions for that group will be logged here")  # type: ignore[union-attr]
+
+
+async def cmd_topic(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+    if not await _is_admin(update, context):
+        return
+    store.set_meta(tenant_of(update.effective_chat.id), topic=" ".join(context.args or [])[:200])  # type: ignore[union-attr]
+    await _reply(update)("topic saved")  # type: ignore[union-attr]
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+    token = os.environ.get("TELEGRAM_TOKEN")
+    if not token:
+        raise SystemExit("set TELEGRAM_TOKEN (@BotFather → /newbot)")
+    app = Application.builder().token(token).build()
+    app.add_handler(CommandHandler("mod_status", cmd_status))
+    app.add_handler(CommandHandler("mod_set", cmd_set))
+    app.add_handler(CommandHandler("mod_rule", cmd_rule))
+    app.add_handler(CommandHandler("mod_log", cmd_log))
+    app.add_handler(CommandHandler("mod_topic", cmd_topic))
+    app.add_handler(MessageHandler(filters.TEXT | filters.CAPTION, on_message))
+    app.run_polling(allowed_updates=Update.ALL_TYPES)
+
+
+if __name__ == "__main__":
+    main()

jevmod/api/demo.py

@@ -0,0 +1,199 @@
+"""Public demo endpoint for the landing page: one message in, one decision out, with the TypeSafe key kept on the
+server and a hard monthly budget so a stranger cannot spend more than you allow.
+
+    JEVMOD_DEMO_BUDGET_USD=0.5 JEVMOD_DEMO_ORIGINS=https://ohernandezdev.github.io jevmod demo
+
+Guards, in order: CORS allow-list → per-IP limits (per minute and per day) → text length → global monthly budget
+computed from measured input tokens at Jev's list price → cache (repeats cost nothing). Every judged demo message
+is logged (text, scores, hashed IP, country header if a proxy sets one) so you can see what people try:
+`GET /demo/stats` and `GET /demo/recent` need the admin token.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import sqlite3
+import threading
+import time
+from collections import defaultdict, deque
+from typing import Any
+
+from fastapi import FastAPI, Header, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+from ..core import Policy, decide
+from ..judge import CATEGORIES, Judge, Message, normalize
+
+JEV_USD_PER_M = 0.042
+BUDGET_USD = float(os.environ.get("JEVMOD_DEMO_BUDGET_USD", "0.5"))
+PER_MINUTE = int(os.environ.get("JEVMOD_DEMO_PER_MINUTE", "6"))
+PER_DAY = int(os.environ.get("JEVMOD_DEMO_PER_DAY", "40"))
+MAX_CHARS = int(os.environ.get("JEVMOD_DEMO_MAX_CHARS", "300"))
+ORIGINS = [o.strip() for o in os.environ.get("JEVMOD_DEMO_ORIGINS", "http://localhost:8000").split(",") if o.strip()]
+DB_PATH = os.environ.get("JEVMOD_DEMO_DB", "jevmod-demo.sqlite")
+SALT = os.environ.get("JEVMOD_DEMO_SALT", "jevmod-demo")
+CATS = [c for c in CATEGORIES if c != "offtopic"]
+
+app = FastAPI(title="jevmod demo", version="0.1.0", docs_url=None, redoc_url=None)
+app.add_middleware(CORSMiddleware, allow_origins=ORIGINS, allow_methods=["POST", "GET"], allow_headers=["Content-Type"])
+
+_judge: Judge | None = None
+_policy = Policy()
+for _c in CATS:
+    _policy.set_category(_c, "flag")
+_lock = threading.Lock()
+_minute: dict[str, deque[float]] = defaultdict(deque)
+_day: dict[str, deque[float]] = defaultdict(deque)
+_db = sqlite3.connect(DB_PATH, check_same_thread=False)
+_db.executescript(
+    """
+    CREATE TABLE IF NOT EXISTS demo (ts REAL, month TEXT, ip_hash TEXT, country TEXT, text TEXT, category TEXT,
+        p REAL, action TEXT, scores TEXT, tokens INTEGER, cached INTEGER);
+    CREATE INDEX IF NOT EXISTS demo_month ON demo (month);
+    """
+)
+_db.commit()
+
+
+class In(BaseModel):
+    text: str = Field(..., min_length=1, max_length=MAX_CHARS)
+
+
+def judge() -> Judge:
+    global _judge
+    if _judge is None:
+        _judge = Judge()
+    return _judge
+
+
+def month() -> str:
+    return time.strftime("%Y-%m")
+
+
+def spent_usd() -> float:
+    row = _db.execute("SELECT COALESCE(SUM(tokens), 0) FROM demo WHERE month=? AND cached=0", (month(),)).fetchone()
+    return float(row[0]) * JEV_USD_PER_M / 1e6
+
+
+def _ip(request: Request) -> str:
+    fwd = request.headers.get("cf-connecting-ip") or request.headers.get("x-forwarded-for", "")
+    ip = fwd.split(",")[0].strip() if fwd else (request.client.host if request.client else "?")
+    return hashlib.sha256(f"{SALT}|{ip}".encode()).hexdigest()[:16]
+
+
+def _allow(ip_hash: str) -> str | None:
+    now = time.time()
+    with _lock:
+        for bucket, window, limit in ((_minute[ip_hash], 60, PER_MINUTE), (_day[ip_hash], 86400, PER_DAY)):
+            while bucket and now - bucket[0] > window:
+                bucket.popleft()
+            if len(bucket) >= limit:
+                return "per-minute limit, try again in a moment" if window == 60 else "daily limit for this address"
+        _minute[ip_hash].append(now)
+        _day[ip_hash].append(now)
+    return None
+
+
+@app.get("/demo/health")
+def health() -> dict[str, Any]:
+    spent = spent_usd()
+    return {"ok": True, "budget_usd": BUDGET_USD, "spent_usd": round(spent, 4), "open": spent < BUDGET_USD}
+
+
+@app.post("/demo/check")
+def check(body: In, request: Request) -> dict[str, Any]:
+    ip_hash = _ip(request)
+    why = _allow(ip_hash)
+    if why:
+        raise HTTPException(429, why)
+    spent = spent_usd()
+    if spent >= BUDGET_USD:
+        raise HTTPException(
+            503, f"the demo budget for this month (${BUDGET_USD:.2f}) is used up; run the CLI with your own key"
+        )
+    j = judge()
+    before = j.input_tokens
+    verdicts = j.judge([Message("demo", normalize(body.text))], CATS)
+    v = verdicts[0]
+    tokens = j.input_tokens - before
+    d = decide(_policy, v)
+    with _lock:
+        _db.execute(
+            "INSERT INTO demo VALUES (?,?,?,?,?,?,?,?,?,?,?)",
+            (
+                time.time(),
+                month(),
+                ip_hash,
+                request.headers.get("cf-ipcountry", ""),
+                body.text[:MAX_CHARS],
+                d.category,
+                d.probability,
+                d.action,
+                json.dumps({k: round(x, 3) for k, x in d.scores.items()}),
+                tokens,
+                int(v.reason == "cache"),
+            ),
+        )
+        _db.commit()
+    out = d.to_dict()
+    out["reason"] = v.reason
+    out["budget_left_usd"] = round(max(BUDGET_USD - spent - tokens * JEV_USD_PER_M / 1e6, 0), 4)
+    return out
+
+
+def _admin(authorization: str) -> None:
+    admin = os.environ.get("JEVMOD_ADMIN_TOKEN", "")
+    given = authorization[7:].strip() if authorization.startswith("Bearer ") else ""
+    if not admin or not hmac.compare_digest(given, admin):
+        raise HTTPException(403, "admin token required")
+
+
+@app.get("/demo/stats")
+def stats(authorization: str = Header(default="")) -> dict[str, Any]:
+    _admin(authorization)
+    m = month()
+    rows = _db.execute(
+        "SELECT COUNT(*), COUNT(DISTINCT ip_hash), SUM(cached), COALESCE(SUM(tokens),0) FROM demo WHERE month=?", (m,)
+    ).fetchone()
+    by_cat = _db.execute(
+        "SELECT COALESCE(category,'none'), COUNT(*) FROM demo WHERE month=? GROUP BY 1 ORDER BY 2 DESC", (m,)
+    ).fetchall()
+    by_country = _db.execute(
+        "SELECT country, COUNT(*) FROM demo WHERE month=? AND country!='' GROUP BY 1 ORDER BY 2 DESC LIMIT 15", (m,)
+    ).fetchall()
+    return {
+        "month": m,
+        "checks": rows[0],
+        "distinct_visitors": rows[1],
+        "cache_hits": rows[2] or 0,
+        "input_tokens": rows[3],
+        "spent_usd": round(rows[3] * JEV_USD_PER_M / 1e6, 4),
+        "budget_usd": BUDGET_USD,
+        "by_category": dict(by_cat),
+        "by_country": dict(by_country),
+    }
+
+
+@app.get("/demo/recent")
+def recent(limit: int = 100, authorization: str = Header(default="")) -> list[dict[str, Any]]:
+    _admin(authorization)
+    rows = _db.execute(
+        "SELECT ts, country, text, category, p, action, scores FROM demo ORDER BY ts DESC LIMIT ?",
+        (max(1, min(limit, 1000)),),
+    ).fetchall()
+    return [
+        {
+            "ts": r[0],
+            "country": r[1],
+            "text": r[2],
+            "category": r[3],
+            "p": r[4],
+            "action": r[5],
+            "scores": json.loads(r[6]),
+        }
+        for r in rows
+    ]

jevmod/api/server.py

@@ -0,0 +1,185 @@
+"""HTTP API for developers and for any chatbot: POST a batch of messages, get decisions.
+
+    JEVMOD_ADMIN_TOKEN=... TYPESAFE_API_KEY=... uvicorn jevmod.api.server:app --port 8080
+
+Auth: `Authorization: Bearer <api key>`. Keys are created with the admin token (`POST /v1/keys`) and stored hashed.
+Every response carries the request id; every judged decision is in the tenant's audit log.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import secrets
+import time
+import uuid
+from typing import Any
+
+from fastapi import Depends, FastAPI, Header, HTTPException, Request, Response
+from fastapi.responses import PlainTextResponse
+from pydantic import BaseModel, Field
+
+from ..core import ModerationService, Store
+from ..judge import CATEGORIES, Message
+
+app = FastAPI(
+    title="jevmod",
+    version="0.2.0",
+    description="Moderation decisions for user content: spam, scam, harassment, adult, off-topic and your own rules. "
+    "Powered by Jev (TypeSafe). Probabilities, thresholds you own, decisions you can audit.",
+)
+store = Store(os.environ.get("JEVMOD_DB", "jevmod.sqlite"))
+service = ModerationService(store)
+STARTED = time.time()
+_metrics = {"requests": 0, "messages": 0, "errors": 0}
+
+
+# ------------------------------------------------------------------ models
+class InMessage(BaseModel):
+    id: str = Field(default="", description="your id for the message; echoed back")
+    text: str = Field(..., max_length=8000)
+    author: str = ""
+    channel_topic: str = Field(default="", description="what the channel/thread is about; used by offtopic")
+    author_trusted: bool = Field(default=False, description="true skips judgment (moderators, verified staff)")
+
+
+class ModerateRequest(BaseModel):
+    messages: list[InMessage] = Field(..., min_length=1, max_length=50)
+
+
+class DecisionOut(BaseModel):
+    message_id: str
+    action: str
+    category: str | None
+    probability: float
+    scores: dict[str, float]
+    judged: bool
+    reason: str
+
+
+class ModerateResponse(BaseModel):
+    request_id: str
+    decisions: list[DecisionOut]
+    usage: dict[str, int]
+
+
+class PolicyIn(BaseModel):
+    thresholds: dict[str, float] | None = None
+    actions: dict[str, str] | None = None
+    rules: dict[str, str] | None = None
+    rule_actions: dict[str, str] | None = None
+    timeout_minutes: int | None = None
+
+
+class KeyRequest(BaseModel):
+    tenant: str = Field(..., min_length=1, max_length=80)
+    label: str = ""
+
+
+# ------------------------------------------------------------------ auth
+def _hash(key: str) -> str:
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+def tenant_from_auth(authorization: str = Header(default="")) -> str:
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(401, "missing bearer token")
+    tenant = store.tenant_for_key(_hash(authorization[7:].strip()))
+    if not tenant:
+        raise HTTPException(401, "unknown api key")
+    return tenant
+
+
+def admin_only(authorization: str = Header(default="")) -> None:
+    admin = os.environ.get("JEVMOD_ADMIN_TOKEN", "")
+    given = authorization[7:].strip() if authorization.startswith("Bearer ") else ""
+    if not admin or not hmac.compare_digest(given, admin):
+        raise HTTPException(403, "admin token required")
+
+
+# ------------------------------------------------------------------ routes
+@app.get("/v1/health")
+def health() -> dict[str, Any]:
+    return {"ok": True, "uptime_s": int(time.time() - STARTED), "categories": list(CATEGORIES)}
+
+
+@app.get("/metrics", response_class=PlainTextResponse)
+def metrics() -> str:
+    j = service.judge if service._judge else None
+    lines = [
+        f"jevmod_http_requests_total {_metrics['requests']}",
+        f"jevmod_messages_total {_metrics['messages']}",
+        f"jevmod_http_errors_total {_metrics['errors']}",
+        f"jevmod_jev_requests_total {j.requests if j else 0}",
+        f"jevmod_jev_input_tokens_total {j.input_tokens if j else 0}",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+@app.post("/v1/moderate", response_model=ModerateResponse)
+def moderate(
+    req: ModerateRequest, request: Request, response: Response, tenant: str = Depends(tenant_from_auth)
+) -> ModerateResponse:
+    rid = request.headers.get("x-request-id") or uuid.uuid4().hex[:12]
+    response.headers["X-Request-Id"] = rid
+    _metrics["requests"] += 1
+    _metrics["messages"] += len(req.messages)
+    msgs = [
+        Message(m.id or str(i), m.text, author=m.author, channel_topic=m.channel_topic, author_trusted=m.author_trusted)
+        for i, m in enumerate(req.messages)
+    ]
+    try:
+        decisions = service.moderate(tenant, msgs, request_id=rid)
+    except Exception as exc:
+        _metrics["errors"] += 1
+        raise HTTPException(502, f"judgment failed: {type(exc).__name__}") from exc
+    judged, requests, tokens = store.usage(tenant)
+    return ModerateResponse(
+        request_id=rid,
+        decisions=[DecisionOut(**{k: v for k, v in d.to_dict().items() if k != "policy_version"}) for d in decisions],
+        usage={"judged_this_month": judged, "jev_requests_this_month": requests, "input_tokens_this_month": tokens},
+    )
+
+
+@app.get("/v1/policy")
+def get_policy(tenant: str = Depends(tenant_from_auth)) -> dict[str, Any]:
+    return service.policy(tenant).to_dict()
+
+
+@app.put("/v1/policy")
+def put_policy(body: PolicyIn, tenant: str = Depends(tenant_from_auth)) -> dict[str, Any]:
+    p = service.policy(tenant)
+    try:
+        for c, a in (body.actions or {}).items():
+            p.set_category(c, a, (body.thresholds or {}).get(c))
+        for c, t in (body.thresholds or {}).items():
+            if c in CATEGORIES and c not in (body.actions or {}):
+                p.set_category(c, p.actions.get(c, "flag"), t)
+        for n, text in (body.rules or {}).items():
+            p.set_rule(n, text, (body.rule_actions or {}).get(n, p.rule_actions.get(n, "flag")))
+        if body.timeout_minutes is not None:
+            p.timeout_minutes = max(1, min(int(body.timeout_minutes), 1440))
+    except ValueError as exc:
+        raise HTTPException(422, str(exc)) from exc
+    service.save_policy(tenant, p)
+    return p.to_dict()
+
+
+@app.get("/v1/decisions")
+def decisions(limit: int = 50, tenant: str = Depends(tenant_from_auth)) -> list[dict[str, Any]]:
+    return store.recent_decisions(tenant, max(1, min(limit, 500)))
+
+
+@app.delete("/v1/tenant")
+def delete_tenant(tenant: str = Depends(tenant_from_auth)) -> dict[str, bool]:
+    """GDPR: forget this tenant's policy, usage and decision log."""
+    store.delete_tenant(tenant)
+    return {"deleted": True}
+
+
+@app.post("/v1/keys", dependencies=[Depends(admin_only)])
+def create_key(body: KeyRequest) -> dict[str, str]:
+    key = "jm_" + secrets.token_urlsafe(32)
+    store.create_api_key(body.tenant, _hash(key), body.label)
+    return {"tenant": body.tenant, "api_key": key, "note": "shown once; stored hashed"}

jevmod/categories.json

@@ -0,0 +1,69 @@
+{
+  "version": 1,
+  "categories": {
+    "spam": {
+      "label": "spam / advertising",
+      "instructions": "Is `{m}.text` spam: unsolicited mass promotion, referral or invite farming, repeated offers, link drops with no conversational purpose, or mass mentions to get attention?",
+      "criteria": {
+        "true": "advertising or promotion pushed at the community, repeated or copy-pasted offers, referral/affiliate/invite links, mass @mentions, bare shortened links with no context",
+        "false": "a normal conversational message; a one-off personal sale or trade between members; sharing a guide, video or project once; quoting spam in order to report it"
+      }
+    },
+    "scam": {
+      "label": "scam / phishing",
+      "instructions": "Is `{m}.text` a scam or phishing attempt aimed at the reader's money, account or credentials?",
+      "criteria": {
+        "true": "fake giveaways (free Nitro, free skins, crypto doubling), links to domains imitating a service (discord-gifts, steampowerd, discord-secure), impersonation of staff or support, 'DM me for a deal', urgent account-verification threats, requests for money or credentials under false pretenses, in any language or script",
+        "false": "a legitimate link to a well-known site, a genuine question about a deal or price, warning others about a scam, ordinary trading between members"
+      }
+    },
+    "harassment": {
+      "label": "harassment / abuse",
+      "instructions": "Does `{m}.text` harass, insult, threaten or demean a person or group?",
+      "criteria": {
+        "true": "insults, slurs, threats, telling someone to leave or hurt themselves, dehumanising or targeted abuse, in any language (judge the meaning of the words, not the language they are written in)",
+        "false": "friendly banter, competitive trash talk with no target, disagreement, criticism of ideas, an ordinary question or invitation to play"
+      }
+    },
+    "nsfw": {
+      "label": "adult / graphic content",
+      "instructions": "Does `{m}.text` contain sexual or graphically violent content inappropriate for a general audience community?",
+      "criteria": {
+        "true": "explicit sexual content or solicitation (trading nudes, 'DM for pics'), sexual content involving minors, graphic gore",
+        "false": "insults or profanity with no sexual content, romance or dating talk, medical or health talk, game violence"
+      }
+    },
+    "offtopic": {
+      "label": "off-topic for the channel",
+      "instructions": "Given `{m}.channel_topic`, is `{m}.text` clearly about something unrelated to that topic?",
+      "criteria": {
+        "true": "a message whose subject has nothing to do with the channel topic (a recipe in a gaming channel, job hunting in a support channel) and is not a brief aside",
+        "false": "on-topic content, greetings, questions, short asides and reactions. Spam, insults or rule violations are NOT off-topic by themselves: judge only the subject"
+      }
+    },
+    "selfharm": {
+      "label": "self-harm / crisis",
+      "instructions": "Does `{m}.text` express that the author is considering suicide or self-harm, or is in an acute personal crisis? (Meant to alert moderators so they can reach out, not to punish.)",
+      "criteria": {
+        "true": "statements of wanting to die, disappear or hurt oneself, saying goodbye, describing a plan, hopelessness about one's own life, asking how to self-harm, in any language",
+        "false": "telling someone else to hurt themselves (that is harassment), hyperbole about a game ('this boss makes me want to die lol'), song lyrics, discussing the topic in general, venting about a bad day"
+      }
+    },
+    "doxxing": {
+      "label": "doxxing / personal data",
+      "instructions": "Does `{m}.text` reveal or try to obtain private identifying information about a real person without their consent?",
+      "criteria": {
+        "true": "home address, phone number, real full name behind a username, workplace, school, ID or financial numbers, photos' locations, or asking others to find or share such data about someone",
+        "false": "the author sharing their own city or first name, public figures' public information, business contact details, fictional characters, generic talk about privacy"
+      }
+    },
+    "minors": {
+      "label": "sexual content involving minors / grooming",
+      "instructions": "Does `{m}.text` sexualise a minor, solicit sexual content from or about a minor, or show grooming behaviour (an adult building private trust with a child for sexual purposes)?",
+      "criteria": {
+        "true": "sexual comments about someone stated or clearly implied to be under 18, requests for their photos or private contact, offers of gifts or secrecy to a child, age-checking followed by sexual intent, in any language",
+        "false": "adults talking about adults (that is nsfw), parents discussing their kids' games, child safety advice, mentions of age with no sexual element"
+      }
+    }
+  }
+}