jevmod 0.2.0__py3-none-any.whl

jevmod/judge.py

@@ -0,0 +1,189 @@
+"""The judgment core: a batch of messages in, one Jev request, a probability per category per message out.
+
+Cost controls live here, not in the bot: local pre-filters decide what is worth judging, a cache reuses verdicts
+for repeated text, and only the categories a server enabled are asked.
+
+Findings from the adversarial red team that shaped this file (tests/data/redteam.csv):
+- Messages go to Jev as a dict keyed by position (`messages.m3.text`), not a list. With a list, probabilities
+  leaked between neighbouring positions in multilingual batches (a clean German message inherited harassment 0.95).
+- Text is NFKC-normalised and stripped of combining marks before judging and caching: fullwidth, enclosed
+  alphanumerics and zalgo were slipping under the thresholds or the pre-filter.
+- The pre-filter counts characters, not space-separated words: Japanese and Chinese never have spaces.
+- Every question carries `criteria`, otherwise "offtopic" measured "undesirable" and "spam" caught one-off sales.
+
+Against the TypeSafe docs (checked 2026-09-18): one Noul per hazard with true/false criteria is the pattern of the
+`llm_guardrails` cookbook. Judging several messages in one request is NOT a documented pattern (the cookbooks send
+one item per request, or many questions about one document); it is our own cost trade-off, kept only because
+`tests/test_redteam.py::test_batch_matches_single_verdicts_in_multilingual_batch` shows batch and single verdicts
+agree once the state is a dict. 429/529 are retried with exponential backoff and Retry-After, as the API asks.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import json
+import re
+import time
+import unicodedata
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from typesafe_sdk import Noul, NoulAnswer, RetryPolicy, TypeSafeClient
+
+from .keys import get_api_key
+
+# The questions live in categories.json so every implementation (Python, npm, MCP) asks Jev exactly the same thing.
+CATEGORIES: dict[str, dict[str, Any]] = json.loads(
+    (Path(__file__).with_name("categories.json")).read_text(encoding="utf-8")
+)["categories"]
+
+LINK_RE = re.compile(
+    r"(https?://|hxxps?://|www\.|\S+\[\.\]\S+|\b[\w-]+\.(?:gg|com|net|org|ru|io|xyz|fr|de|jp|br)\b/?)", re.I
+)
+
+
+# Enclosed Alphanumeric Supplement (🄰 🅐 🅰 …) has no NFKC decomposition; map the three A-Z rows by hand.
+_ENCLOSED = {cp + k: chr(ord("A") + k) for cp in (0x1F130, 0x1F150, 0x1F170) for k in range(26)}
+
+
+def normalize(text: str) -> str:
+    """HTML entities → text (scraped comments carry `'`), NFKC (fullwidth, enclosed letters, ligatures → plain),
+    drop combining marks (zalgo), collapse whitespace."""
+    t = unicodedata.normalize("NFKC", html.unescape(text).translate(_ENCLOSED))
+    # drop combining marks (zalgo) and format characters (zero-width spaces/joiners used to split words, BOM)
+    t = "".join(ch for ch in t if not unicodedata.combining(ch) and unicodedata.category(ch) != "Cf")
+    return " ".join(t.split())
+
+
+@dataclass
+class Message:
+    id: str
+    text: str
+    author: str = ""
+    channel_topic: str = ""
+    author_trusted: bool = False
+
+
+@dataclass
+class Verdict:
+    message_id: str
+    scores: dict[str, float]  # category -> probability
+    judged: bool  # False when a pre-filter skipped Jev
+    reason: str = ""  # why it was skipped, or "cache" / "jev"
+    custom: dict[str, float] = field(default_factory=dict)  # server-defined rules -> probability
+
+    def top(self) -> tuple[str, float] | None:
+        allscores = {**self.scores, **self.custom}
+        if not allscores:
+            return None
+        k = max(allscores, key=lambda c: allscores[c])
+        return k, allscores[k]
+
+
+def prefilter(m: Message, min_chars: int = 8) -> str | None:
+    """Return a reason to skip judging, or None to judge. Counts letters/digits in any script, not words."""
+    if m.author_trusted:
+        return "trusted author"
+    text = normalize(m.text)
+    if not text:
+        return "empty"
+    if LINK_RE.search(text):
+        return None  # a link is never too short
+    letters = sum(1 for ch in text if ch.isalnum())
+    if letters < min_chars:
+        return "too short"
+    return None
+
+
+class Judge:
+    def __init__(self, client: TypeSafeClient | None = None, cache_ttl_s: int = 86400, timeout_s: float = 20.0) -> None:
+        self.client = client or TypeSafeClient(
+            api_key=get_api_key(),
+            retry=RetryPolicy(
+                max_retries=3, backoff_initial=0.5, backoff_max=8.0, http_statuses={429, 500, 502, 503, 504, 529}
+            ),
+            timeout=timeout_s,
+        )
+        self.cache: dict[str, tuple[float, dict[str, float], dict[str, float]]] = {}
+        self.cache_ttl = cache_ttl_s
+        self.requests = 0
+        self.input_tokens = 0
+        self.judged_messages = 0
+
+    def judge(
+        self,
+        messages: list[Message],
+        categories: list[str],
+        custom_rules: dict[str, str] | None = None,
+    ) -> list[Verdict]:
+        """One Jev request for every message that passes the pre-filter and is not cached."""
+        custom_rules = custom_rules or {}
+        cats = [c for c in categories if c in CATEGORIES]
+        out: dict[str, Verdict] = {}
+        to_judge: list[tuple[Message, str]] = []
+        now = time.time()
+        for m in messages:
+            why = prefilter(m)
+            if why:
+                out[m.id] = Verdict(m.id, {}, False, why)
+                continue
+            text = normalize(m.text)
+            key = _key(text, m.channel_topic, cats, custom_rules)
+            hit = self.cache.get(key)
+            if hit and now - hit[0] < self.cache_ttl:
+                out[m.id] = Verdict(m.id, dict(hit[1]), True, "cache", dict(hit[2]))
+                continue
+            to_judge.append((m, text))
+
+        if to_judge and (cats or custom_rules):
+            # only the text and the channel topic reach Jev: no author names, no ids beyond the position
+            state: dict[str, Any] = {
+                "messages": {
+                    f"m{i}": {"text": text, "channel_topic": m.channel_topic or "general chat"}
+                    for i, (m, text) in enumerate(to_judge)
+                },
+                "custom_rules": custom_rules,
+            }
+            questions: dict[str, Noul] = {}
+            for i, _ in enumerate(to_judge):
+                path = f"messages.m{i}"
+                for c in cats:
+                    questions[f"{c}_{i}"] = Noul(
+                        instructions=CATEGORIES[c]["instructions"].format(m=path), criteria=CATEGORIES[c]["criteria"]
+                    )
+                for name, rule in custom_rules.items():
+                    questions[f"custom__{name}_{i}"] = Noul(
+                        instructions=f"Does `{path}.text` break this community rule: `custom_rules.{name}` ({rule!r})?",
+                        criteria={
+                            "true": "the message does what the rule forbids, as a moderator who wrote it would read it",
+                            "false": "the message is ordinary conversation, or the rule does not clearly cover it; "
+                            "when the rule lists exceptions, those are allowed",
+                        },
+                    )
+            resp = self.client.system_one(state=state, questions=questions)
+            self.requests += 1
+            self.input_tokens += getattr(getattr(resp, "usage", None), "input_tokens", 0) or 0
+            self.judged_messages += len(to_judge)
+            for i, (m, text) in enumerate(to_judge):
+                scores = {c: _p(resp.answers[f"{c}_{i}"]) for c in cats}
+                custom = {name: _p(resp.answers[f"custom__{name}_{i}"]) for name in custom_rules}
+                self.cache[_key(text, m.channel_topic, cats, custom_rules)] = (now, scores, custom)
+                out[m.id] = Verdict(m.id, scores, True, "jev", custom)
+        elif to_judge:
+            for m, _ in to_judge:
+                out[m.id] = Verdict(m.id, {}, False, "no categories enabled")
+        return [out[m.id] for m in messages]
+
+
+def _p(answer: Any) -> float:
+    if not isinstance(answer, NoulAnswer):
+        raise TypeError(f"expected a Noul answer, got {type(answer).__name__}")
+    return float(answer.noul)
+
+
+def _key(text: str, topic: str, cats: list[str], rules: dict[str, str]) -> str:
+    norm = text.lower()
+    h = hashlib.sha256(f"{norm}|{topic}|{','.join(cats)}|{sorted(rules.items())}".encode()).hexdigest()
+    return h[:32]

jevmod/keys.py

@@ -0,0 +1,146 @@
+"""Where the TypeSafe key comes from, in this order: `TYPESAFE_API_KEY` in the environment, the OS keyring, `.env` in
+the current directory. `jevmod init` stores it (keyring first, `.env` with mode 600 as the fallback). Nothing here
+ever prints or logs the key.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+SERVICE = "jevmod"
+ACCOUNT = "TYPESAFE_API_KEY"
+ENV_VAR = "TYPESAFE_API_KEY"
+
+
+def get_api_key(cwd: Path | None = None) -> str | None:
+    """Environment -> keyring -> .env: an explicit variable always wins over what `jevmod init` stored, so a
+    container, a CI job or a test can override the machine's key. None when nothing is set (TypeSafeClient then
+    raises its own error)."""
+    return os.environ.get(ENV_VAR, "").strip() or _from_keyring() or read_dotenv(cwd or Path.cwd()).get(ENV_VAR)
+
+
+def _from_keyring() -> str | None:
+    try:
+        import keyring
+    except ImportError:
+        return None
+    try:
+        value = keyring.get_password(SERVICE, ACCOUNT)
+    except Exception:  # no backend (headless Linux), locked vault, broken install: fall through
+        return None
+    return value.strip() if value and value.strip() else None
+
+
+def store_in_keyring(key: str) -> bool:
+    """True when the key is now in the OS keyring, False when keyring is missing or refused."""
+    try:
+        import keyring
+    except ImportError:
+        return False
+    try:
+        keyring.set_password(SERVICE, ACCOUNT, key)
+        return keyring.get_password(SERVICE, ACCOUNT) == key
+    except Exception:
+        return False
+
+
+def read_dotenv(directory: Path) -> dict[str, str]:
+    """Minimal `.env` parser: KEY=value lines, optional `export `, quotes stripped, `#` comments ignored."""
+    path = directory / ".env"
+    out: dict[str, str] = {}
+    if not path.is_file():
+        return out
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[7:]
+        k, _, v = line.partition("=")
+        v = v.strip()
+        if v[:1] in ("'", '"') and v.find(v[0], 1) > 0:
+            v = v[1 : v.find(v[0], 1)]
+        elif " #" in v:
+            v = v.split(" #", 1)[0].rstrip()
+        if v:
+            out[k.strip()] = v
+    return out
+
+
+def write_dotenv(key: str, directory: Path) -> Path:
+    """Set TYPESAFE_API_KEY in `.env` (other lines kept), mode 600, and make sure `.gitignore` lists `.env`."""
+    path = directory / ".env"
+    lines = path.read_text(encoding="utf-8").splitlines() if path.is_file() else []
+    entry = f"{ENV_VAR}={key}"
+    replaced = False
+    for i, line in enumerate(lines):
+        if line.strip().removeprefix("export ").startswith(f"{ENV_VAR}="):
+            lines[i] = entry
+            replaced = True
+    if not replaced:
+        lines.append(entry)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+    gitignore = directory / ".gitignore"
+    if gitignore.is_file():
+        entries = [ln.strip() for ln in gitignore.read_text(encoding="utf-8").splitlines()]
+        if ".env" not in entries:
+            with gitignore.open("a", encoding="utf-8") as fh:
+                fh.write("\n.env\n")
+    return path
+
+
+def validate_key(key: str) -> None:
+    """One tiny Jev call; raises TypeSafeError when the key is rejected or the API is unreachable."""
+    from typesafe_sdk import Noul, RetryPolicy, TypeSafeClient
+
+    with TypeSafeClient(api_key=key, retry=RetryPolicy(max_retries=1), timeout=15.0) as client:
+        client.system_one(state={"text": "hello"}, questions={"ok": Noul(instructions="Is `text` a greeting?")})
+
+
+def forget() -> int:
+    """`jevmod init --forget`: remove the key from the OS keyring. `.env` files are yours to delete."""
+    try:
+        import keyring
+        from keyring.errors import PasswordDeleteError
+    except ImportError:
+        print("keyring is not installed; nothing stored there. Delete .env by hand if you wrote one.")
+        return 0
+    try:
+        keyring.delete_password(SERVICE, ACCOUNT)
+        print("key removed from the OS keyring (service 'jevmod')")
+    except PasswordDeleteError:
+        print("no key stored in the OS keyring")
+    return 0
+
+
+def init(directory: Path | None = None, *, prefer_env_file: bool = False, prompt: bool = True) -> int:
+    """`jevmod init`: ask for the key without echo, validate it, store it. Returns an exit code."""
+    import sys
+    from getpass import getpass
+
+    from typesafe_sdk import TypeSafeError
+
+    directory = directory or Path.cwd()
+    try:
+        key = getpass("TypeSafe API key (input hidden): ").strip() if prompt else os.environ.get(ENV_VAR, "").strip()
+    except (EOFError, KeyboardInterrupt):
+        print("cancelled", file=sys.stderr)
+        return 2
+    if not key:
+        print("no key given", file=sys.stderr)
+        return 2
+    try:
+        validate_key(key)
+    except TypeSafeError as exc:
+        print(f"key rejected: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 2
+    if not prefer_env_file and store_in_keyring(key):
+        print("key verified and stored in the OS keyring (service 'jevmod')")
+        return 0
+    path = write_dotenv(key, directory)
+    why = "" if prefer_env_file else " (keyring unavailable)"
+    print(f"key verified and written to {path} with mode 600{why}; .env is git-ignored when a .gitignore exists")
+    return 0

jevmod/mcp_server.py

@@ -0,0 +1,76 @@
+"""MCP server over stdio: `jevmod mcp`. Two tools, no state, no database.
+
+    moderate(texts, channel_topic="", rules=None) -> one decision dict per text (action, category, probability, scores)
+    categories() -> what each category means and its default action and threshold
+
+Register it in Claude Code, Cursor or Codex as a stdio server with command `jevmod` and args `["mcp"]`; the key
+comes from `TYPESAFE_API_KEY`, the OS keyring or `.env`, in that order (see `jevmod init`). Built on the MCP Python SDK
+(`mcp>=2`, where FastMCP became `MCPServer`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+
+from . import Moderator, Policy
+from .core.policy import DEFAULT_ACTIONS, DEFAULT_THRESHOLDS
+from .judge import CATEGORIES, Judge
+
+server = MCPServer(
+    "jevmod",
+    instructions="Moderation decisions for user text: spam, scam, harassment, nsfw, offtopic, selfharm, doxxing, "
+    "minors and plain-language rules. Every category is on (flag) with default thresholds; offtopic only when a "
+    "channel_topic is given. Nothing is stored.",
+)
+_judge: Judge | None = None  # one client and one verdict cache per process; policy is rebuilt per call
+
+
+def _moderator(channel_topic: str, rules: dict[str, str] | None) -> Moderator:
+    global _judge
+    if _judge is None:
+        _judge = Judge()
+    policy = Policy()
+    for c in CATEGORIES:
+        policy.set_category(c, "off" if c == "offtopic" and not channel_topic else "flag")
+    for name, text in (rules or {}).items():
+        policy.set_rule(name, text)
+    return Moderator(policy=policy, judge=_judge)
+
+
+@server.tool()
+def moderate(texts: list[str], channel_topic: str = "", rules: dict[str, str] | None = None) -> list[dict[str, Any]]:
+    """Judge up to 50 texts in one Jev request. Returns one decision per text, in order: action ("none" | "flag"),
+    category (the winning one, or "rule:<name>"), probability, scores for every category, judged (false when a
+    pre-filter skipped it: too short, empty) and reason. `rules` maps a name to a rule in plain language, up to 5."""
+    if not texts:
+        return []
+    if len(texts) > 50:
+        raise ValueError("up to 50 texts per call")
+    mod = _moderator(channel_topic, rules)
+    return [d.to_dict() for d in mod.check_many(texts, channel_topic=channel_topic)]
+
+
+@server.tool()
+def categories() -> list[dict[str, Any]]:
+    """The moderation categories: name, label, when they are true or false, default action and threshold."""
+    return [
+        {
+            "name": name,
+            "label": spec["label"],
+            "true_when": spec["criteria"]["true"],
+            "false_when": spec["criteria"]["false"],
+            "default_action": DEFAULT_ACTIONS.get(name, "flag"),
+            "default_threshold": DEFAULT_THRESHOLDS.get(name, 0.8),
+        }
+        for name, spec in CATEGORIES.items()
+    ]
+
+
+def main() -> None:
+    server.run("stdio")
+
+
+if __name__ == "__main__":
+    main()