jevmod 0.2.0__py3-none-any.whl

jevmod/__init__.py

@@ -0,0 +1,67 @@
+"""jevmod: moderation for communities and apps, powered by Jev.
+
+Developer API, three lines:
+
+    from jevmod import Moderator
+    mod = Moderator()                                  # TYPESAFE_API_KEY in the environment
+    d = mod.check("FREE NITRO click discord-gifts.ru")  # -> Decision(action="flag", category="scam", probability=0.97)
+
+`check_many([...])` judges a batch in one request. Thresholds and actions come from a `Policy` you can pass in.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .core import ACTIONS, Decision, ModerationService, Policy, Store, decide
+from .judge import CATEGORIES, Judge, Message, Verdict
+
+__all__ = [
+    "ACTIONS",
+    "CATEGORIES",
+    "Decision",
+    "Judge",
+    "Message",
+    "ModerationService",
+    "Moderator",
+    "Policy",
+    "Store",
+    "Verdict",
+    "decide",
+]
+
+try:
+    from importlib.metadata import version as _v
+
+    __version__ = _v("jevmod")
+except Exception:  # pragma: no cover
+    __version__ = "0.0.0+local"
+
+
+class Moderator:
+    """Stateless convenience wrapper for developers: no SQLite, no tenants, just judge + policy."""
+
+    def __init__(self, policy: Policy | None = None, judge: Judge | None = None) -> None:
+        self.policy = policy or Policy()
+        self.judge = judge or Judge()
+
+    def check(self, text: str, *, author: str = "", channel_topic: str = "", author_trusted: bool = False) -> Decision:
+        return self.check_many([text], author=author, channel_topic=channel_topic, author_trusted=author_trusted)[0]
+
+    def check_many(
+        self,
+        texts: Sequence[str],
+        *,
+        author: str = "",
+        channel_topic: str = "",
+        author_trusted: bool = False,
+        ids: Sequence[str] | None = None,
+    ) -> list[Decision]:
+        msgs = [
+            Message(
+                ids[i] if ids else str(i), t, author=author, channel_topic=channel_topic, author_trusted=author_trusted
+            )
+            for i, t in enumerate(texts)
+        ]
+        verdicts = self.judge.judge(msgs, self.policy.enabled_categories(), self.policy.rules)
+        return [decide(self.policy, v) for v in verdicts]

jevmod/__main__.py

@@ -0,0 +1,50 @@
+"""`python -m jevmod` / `jevmod`: `check` judges text from the terminal, `init` stores the key, `mcp` serves the
+MCP tools over stdio; `api`, `discord`, `telegram`, `reddit` start that role (default role from JEVMOD_ROLE, then
+`api`)."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def run_role(role: str) -> None:
+    role = role.lower()
+    if role == "api":
+        import uvicorn
+
+        uvicorn.run("jevmod.api.server:app", host="0.0.0.0", port=int(os.environ.get("PORT", "8080")), log_level="info")
+    elif role == "discord":
+        from .adapters.discord_bot import main as run
+
+        run()
+    elif role == "telegram":
+        from .adapters.telegram_bot import main as run
+
+        run()
+    elif role == "reddit":
+        from .adapters.reddit_bot import run
+
+        run()
+    elif role == "demo":
+        import uvicorn
+
+        uvicorn.run("jevmod.api.demo:app", host="0.0.0.0", port=int(os.environ.get("PORT", "8080")), log_level="info")
+    elif role == "mcp":
+        from .mcp_server import main as run
+
+        run()
+    else:
+        raise SystemExit(f"unknown role {role!r}; use check | init | mcp | api | demo | discord | telegram | reddit")
+
+
+def main() -> None:
+    if len(sys.argv) > 1:
+        from .cli import main as cli
+
+        sys.exit(cli(sys.argv[1:]))
+    run_role(os.environ.get("JEVMOD_ROLE", "api"))
+
+
+if __name__ == "__main__":
+    main()

jevmod/adapters/discord_bot.py

@@ -0,0 +1,324 @@
+"""Discord adapter on top of ModerationService.
+
+Plug and play: invite it, it flags into a private #jevmod-log; tune with /mod.
+
+DISCORD_TOKEN=... TYPESAFE_API_KEY=... python -m jevmod.adapters.discord_bot
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+from datetime import timedelta
+
+import discord
+from discord import app_commands
+
+from ..core import FREE_MONTHLY, RULE_THRESHOLD, Batcher, Decision, ModerationService, Store
+from ..judge import CATEGORIES, Message
+
+log = logging.getLogger("jevmod.discord")
+
+intents = discord.Intents.default()
+intents.message_content = True  # the only privileged intent we need
+bot = discord.Client(intents=intents)
+tree = app_commands.CommandTree(bot)
+store = Store(os.environ.get("JEVMOD_DB", "jevmod.sqlite"))
+service = ModerationService(store)
+
+
+def tenant_of(guild_id: int) -> str:
+    return f"discord:{guild_id}"
+
+
+async def handle_batch(tenant: str, batch: list[discord.Message]) -> None:
+    guild = batch[0].guild
+    if guild is None:
+        return
+    meta = store.get_meta(tenant)
+    trusted = set(meta.get("trusted_roles", []))
+    topics = meta.get("channel_topics", {})
+    msgs = [
+        Message(
+            id=str(m.id),
+            text=m.content,
+            author=str(m.author.id),  # kept only in your local log for erasure requests; never sent to Jev
+            channel_topic=topics.get(str(m.channel.id), getattr(m.channel, "topic", "") or "general chat"),
+            author_trusted=_trusted(m.author, trusted),
+        )
+        for m in batch
+    ]
+    decisions = await asyncio.to_thread(service.moderate, tenant, msgs)
+    for m, d in zip(batch, decisions, strict=True):
+        if d.reason == "quota":
+            await _notify_quota_once(guild, tenant)
+            return
+        if d.action != "none":
+            await act(guild, m, d)
+
+
+def _trusted(author: discord.User | discord.Member, trusted_roles: set[int]) -> bool:
+    if not isinstance(author, discord.Member):
+        return False
+    return author.guild_permissions.manage_messages or bool(trusted_roles & {r.id for r in author.roles})
+
+
+batcher = Batcher(2.0, handle_batch)
+
+
+@bot.event
+async def on_ready() -> None:
+    await tree.sync()
+    log.info("discord ready as %s in %d guilds", bot.user, len(bot.guilds))
+
+
+@bot.event
+async def on_message(msg: discord.Message) -> None:
+    if msg.author.bot or not msg.guild or not msg.content:
+        return
+    tenant = tenant_of(msg.guild.id)
+    if not service.policy(tenant).active():
+        return
+    batcher.add(tenant, msg)
+
+
+async def act(guild: discord.Guild, m: discord.Message, d: Decision) -> None:
+    tenant = tenant_of(guild.id)
+    policy = service.policy(tenant)
+    note = ""
+    try:
+        if d.action in ("delete", "timeout"):
+            await m.delete()
+            note = "deleted"
+        if d.action == "timeout" and isinstance(m.author, discord.Member):
+            await m.author.timeout(
+                timedelta(minutes=policy.timeout_minutes), reason=f"jevmod: {d.category} p={d.probability:.2f}"
+            )
+            note = f"deleted, timed out {policy.timeout_minutes} min"
+    except discord.Forbidden:
+        note = "missing permissions to act"
+    if d.action in ("delete", "timeout") and "missing" not in note:
+        with contextlib.suppress(Exception):  # DMs closed
+            await m.author.send(
+                f"Your message in **{guild.name}** #{m.channel} was removed by an automated moderation system "
+                f"(reason: {d.category}, confidence {d.probability:.0%}). If you think this was a mistake, contact the "
+                "server's moderators; they can review the decision and adjust the rules."
+            )
+    channel = await log_channel(guild, tenant)
+    if channel:
+        top = " · ".join(f"{c} {p:.2f}" for c, p in sorted(d.scores.items(), key=lambda kv: -kv[1])[:3])
+        embed = discord.Embed(
+            title=f"{d.category}  p={d.probability:.2f}  →  {d.action}" + (f" ({note})" if note else ""),
+            description=m.content[:500],
+            colour=0x2FBF83 if d.action == "flag" else 0xD9A441,
+        )
+        embed.add_field(name="author", value=m.author.mention, inline=True)
+        embed.add_field(name="channel", value=getattr(m.channel, "mention", str(m.channel)), inline=True)
+        embed.set_footer(text=f"{top}   ·   ❌ false positive (raises threshold)  ·  ✅ correct (lowers it a notch)")
+        sent = await channel.send(embed=embed)
+        await sent.add_reaction("❌")
+        await sent.add_reaction("✅")
+
+
+async def log_channel(guild: discord.Guild, tenant: str) -> discord.TextChannel | None:
+    meta = store.get_meta(tenant)
+    if meta.get("log_channel"):
+        ch = guild.get_channel(int(meta["log_channel"]))
+        if isinstance(ch, discord.TextChannel):
+            return ch
+    existing = discord.utils.get(guild.text_channels, name="jevmod-log")
+    if existing:
+        store.set_meta(tenant, log_channel=existing.id)
+        return existing
+    try:
+        overwrites: dict[discord.Role | discord.Member | discord.Object, discord.PermissionOverwrite] = {
+            guild.default_role: discord.PermissionOverwrite(read_messages=False)
+        }
+        ch = await guild.create_text_channel("jevmod-log", overwrites=overwrites, reason="jevmod decisions log")
+        store.set_meta(tenant, log_channel=ch.id)
+        return ch
+    except discord.Forbidden:
+        return None
+
+
+async def _notify_quota_once(guild: discord.Guild, tenant: str) -> None:
+    if not store.note_quota_hit(tenant):
+        return
+    ch = await log_channel(guild, tenant)
+    if ch:
+        await ch.send(
+            f"jevmod paused for this month: the monthly quota of {FREE_MONTHLY:,} judged messages was reached "
+            "(JEVMOD_MONTHLY_QUOTA). Messages are not being judged until next month. Nothing is deleted while paused."
+        )
+
+
+@bot.event
+async def on_raw_reaction_add(payload: discord.RawReactionActionEvent) -> None:
+    """❌ = false positive (threshold up), ✅ = confirmed (threshold down a notch, floor 0.5)."""
+    emoji = str(payload.emoji)
+    if emoji not in ("❌", "✅") or (bot.user and payload.user_id == bot.user.id) or not payload.guild_id:
+        return
+    guild = bot.get_guild(payload.guild_id)
+    if not guild:
+        return
+    tenant = tenant_of(guild.id)
+    meta = store.get_meta(tenant)
+    if str(payload.channel_id) != str(meta.get("log_channel")):
+        return
+    channel = guild.get_channel(payload.channel_id)
+    if not isinstance(channel, discord.TextChannel):
+        return
+    msg = await channel.fetch_message(payload.message_id)
+    if not msg.embeds or not msg.embeds[0].title:
+        return
+    category = msg.embeds[0].title.split()[0]
+    policy = service.policy(tenant)
+    if category in policy.thresholds or category.startswith("rule:"):
+        new = policy.nudge(category, 0.03 if emoji == "❌" else -0.02)
+        service.save_policy(tenant, policy)
+        await msg.reply(f"noted: threshold for **{category}** is now {new:.2f}", mention_author=False)
+
+
+@bot.event
+async def on_guild_remove(guild: discord.Guild) -> None:
+    """Kicked or left: forget everything about that server."""
+    store.delete_tenant(tenant_of(guild.id))
+    log.info("left guild %s; data deleted", guild.id)
+
+
+# ------------------------------------------------------------------ /mod
+mod = app_commands.Group(
+    name="mod", description="jevmod settings", default_permissions=discord.Permissions(manage_guild=True)
+)
+
+
+@mod.command(name="status", description="Settings and this month's usage")
+async def status(itx: discord.Interaction) -> None:
+    tenant = tenant_of(itx.guild_id or 0)
+    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()]
+    plan = store.plan(tenant)
+    quota = (
+        f"{judged:,}/{FREE_MONTHLY:,} judged this month (quota)"
+        if plan == "free" and FREE_MONTHLY
+        else f"{judged:,} judged this month"
+    )
+    lines.append(f"\n{quota} · {requests} Jev requests · {tokens:,} tokens")
+    await itx.response.send_message("\n".join(lines), ephemeral=True)
+
+
+@mod.command(name="set", description="Action and threshold for a category")
+@app_commands.describe(
+    category="spam, scam, harassment, nsfw, offtopic", action="off, flag, delete, timeout", threshold="0.5 to 0.99"
+)
+async def set_cmd(itx: discord.Interaction, category: str, action: str, threshold: float | None = None) -> None:
+    tenant = tenant_of(itx.guild_id or 0)
+    p = service.policy(tenant)
+    try:
+        p.set_category(category, action, threshold)
+    except ValueError as exc:
+        await itx.response.send_message(str(exc), ephemeral=True)
+        return
+    service.save_policy(tenant, p)
+    await itx.response.send_message(f"**{category}** → {action} at p ≥ {p.thresholds[category]:.2f}", ephemeral=True)
+
+
+@mod.command(name="rule", description="Add or remove a rule in plain language")
+@app_commands.describe(
+    name="short name",
+    text="the rule as you would tell a member, exceptions included; empty to remove",
+    action="flag, delete, timeout",
+    threshold="0.5 to 0.99 (default 0.80)",
+)
+async def rule_cmd(
+    itx: discord.Interaction, name: str, text: str | None = None, action: str = "flag", threshold: float | None = None
+) -> None:
+    tenant = tenant_of(itx.guild_id or 0)
+    p = service.policy(tenant)
+    try:
+        p.set_rule(name, text, action, threshold)
+    except ValueError as exc:
+        await itx.response.send_message(str(exc), ephemeral=True)
+        return
+    service.save_policy(tenant, p)
+    key = name.strip().lower().replace(" ", "_")[:30]
+    if key in p.rules:
+        th = p.rule_thresholds.get(key, RULE_THRESHOLD)
+        await itx.response.send_message(
+            f'rule **{key}** → {p.rule_actions[key]} at p ≥ {th:.2f}: "{p.rules[key]}"', ephemeral=True
+        )
+    else:
+        await itx.response.send_message(f"rule **{key}** removed", ephemeral=True)
+
+
+@mod.command(name="trust", description="Toggle a role whose messages are never judged")
+async def trust_cmd(itx: discord.Interaction, role: discord.Role) -> None:
+    tenant = tenant_of(itx.guild_id or 0)
+    roles = list(store.get_meta(tenant).get("trusted_roles", []))
+    if role.id in roles:
+        roles.remove(role.id)
+        msg = f"{role.mention} is judged again"
+    else:
+        roles.append(role.id)
+        msg = f"{role.mention} is trusted: never judged"
+    store.set_meta(tenant, trusted_roles=roles)
+    await itx.response.send_message(msg, ephemeral=True)
+
+
+@mod.command(name="topic", description="What this channel is for (used by the offtopic check)")
+async def topic_cmd(itx: discord.Interaction, topic: str) -> None:
+    tenant = tenant_of(itx.guild_id or 0)
+    topics = dict(store.get_meta(tenant).get("channel_topics", {}))
+    topics[str(itx.channel_id)] = topic.strip()[:200]
+    store.set_meta(tenant, channel_topics=topics)
+    await itx.response.send_message(f"this channel is about: {topic}", ephemeral=True)
+
+
+@mod.command(name="log", description="Log decisions in this channel")
+async def log_cmd(itx: discord.Interaction) -> None:
+    store.set_meta(tenant_of(itx.guild_id or 0), log_channel=itx.channel_id)
+    await itx.response.send_message("decisions will be logged here", ephemeral=True)
+
+
+@mod.command(name="recent", description="Last decisions with probabilities")
+async def recent_cmd(itx: discord.Interaction) -> None:
+    rows = store.recent_decisions(tenant_of(itx.guild_id or 0), 10)
+    if not rows:
+        await itx.response.send_message("no decisions yet", ephemeral=True)
+        return
+    await itx.response.send_message(
+        "\n".join(f"`{r['category']} {r['p']:.2f} {r['action']}` {r['text'][:80]}" for r in rows), ephemeral=True
+    )
+
+
+@mod.command(name="forget", description="Delete everything jevmod stored about this server (GDPR)")
+async def forget_cmd(itx: discord.Interaction) -> None:
+    store.delete_tenant(tenant_of(itx.guild_id or 0))
+    await itx.response.send_message(
+        "all settings, usage and decision logs for this server were deleted", ephemeral=True
+    )
+
+
+@mod.command(name="forget_user", description="Delete this member's entries from the decision log (erasure request)")
+async def forget_user_cmd(itx: discord.Interaction, member: discord.Member) -> None:
+    n = store.delete_user(tenant_of(itx.guild_id or 0), str(member.id))
+    await itx.response.send_message(f"deleted {n} log entries for {member.mention}", ephemeral=True)
+
+
+tree.add_command(mod)
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+    token = os.environ.get("DISCORD_TOKEN")
+    if not token:
+        raise SystemExit("set DISCORD_TOKEN (Developer Portal → Bot → Reset Token)")
+    bot.run(token, log_handler=None)
+
+
+if __name__ == "__main__":
+    main()

jevmod/adapters/reddit_bot.py

@@ -0,0 +1,91 @@
+"""Reddit adapter over the official API (PRAW). Streams new comments and posts of the subreddits you moderate;
+`flag` reports the item to the mod queue with the probabilities, `delete` removes it. Runs as a moderator account.
+
+    REDDIT_CLIENT_ID=... REDDIT_CLIENT_SECRET=... REDDIT_USERNAME=... REDDIT_PASSWORD=... REDDIT_SUBREDDITS=sub1,sub2
+    TYPESAFE_API_KEY=... python -m jevmod.adapters.reddit_bot
+
+Reddit's API rules apply (OAuth, user agent, 100 requests/min for OAuth clients). This adapter reads the stream and
+acts on items only; it never posts content.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+
+import praw
+
+from ..core import ModerationService, Store
+from ..judge import Message
+
+log = logging.getLogger("jevmod.reddit")
+store = Store(os.environ.get("JEVMOD_DB", "jevmod.sqlite"))
+service = ModerationService(store)
+BATCH_WINDOW_S = 5.0
+
+
+def tenant_of(subreddit: str) -> str:
+    return f"reddit:{subreddit.lower()}"
+
+
+def act(item, d) -> None:
+    top = ", ".join(f"{c} {p:.2f}" for c, p in sorted(d.scores.items(), key=lambda kv: -kv[1])[:3])
+    reason = f"jevmod: {d.category} p={d.probability:.2f} ({top})"[:100]
+    try:
+        if d.action == "flag":
+            item.report(reason)
+        elif d.action in ("delete", "timeout"):
+            item.mod.remove(mod_note=reason)
+            if d.action == "timeout" and getattr(item, "author", None):
+                item.subreddit.banned.add(item.author, duration=1, ban_reason=reason[:100], note="jevmod timeout")
+    except Exception as exc:
+        log.warning("cannot act on %s: %s", item.id, exc)
+
+
+def run() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+    reddit = praw.Reddit(
+        client_id=os.environ["REDDIT_CLIENT_ID"],
+        client_secret=os.environ["REDDIT_CLIENT_SECRET"],
+        username=os.environ["REDDIT_USERNAME"],
+        password=os.environ["REDDIT_PASSWORD"],
+        user_agent=os.environ.get("REDDIT_USER_AGENT", "jevmod/0.2 moderation bot"),
+    )
+    subs = [s.strip() for s in os.environ["REDDIT_SUBREDDITS"].split(",") if s.strip()]
+    multi = reddit.subreddit("+".join(subs))
+    mods = {s: {m.name for m in reddit.subreddit(s).moderator()} for s in subs}
+    log.info("streaming %s", subs)
+    pending: dict[str, list] = {}
+    last_flush = time.time()
+    for item in multi.stream.comments(skip_existing=True, pause_after=0):
+        now = time.time()
+        if item is not None:
+            sub = item.subreddit.display_name
+            tenant = tenant_of(sub)
+            if service.policy(tenant).active():
+                pending.setdefault(tenant, []).append(item)
+        if now - last_flush >= BATCH_WINDOW_S and pending:
+            for tenant, items in pending.items():
+                sub = items[0].subreddit.display_name
+                msgs = [
+                    Message(
+                        id=i.id,
+                        text=getattr(i, "body", None) or f"{getattr(i, 'title', '')}\n{getattr(i, 'selftext', '')}",
+                        author=str(i.author) if i.author else "",
+                        channel_topic=store.get_meta(tenant).get("topic", f"r/{sub}"),
+                        author_trusted=bool(i.author and i.author.name in mods.get(sub, set())),
+                    )
+                    for i in items
+                ]
+                for i, d in zip(items, service.moderate(tenant, msgs), strict=True):
+                    if d.action != "none":
+                        act(i, d)
+            pending = {}
+            last_flush = now
+        if item is None:
+            time.sleep(1)
+
+
+if __name__ == "__main__":
+    run()