paxmod-guard 0.1.0__tar.gz

paxmod_guard-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.aws-ml.env
+.aws-ml.instance
+.venv/
+train/models/
+train/data/
+bench/data/external/
+.gcp-ml.env
+.ml-ledger
+logs/
+.hf-token
+js/node_modules/
+
+# Large or regenerable outputs (labelled data, per-row results); suite files hold non-commercial benchmark text
+label/out/
+label/relabel/
+label/*.log
+bench/results/
+bench/data/suite*.jsonl
+*.tgz
+.ml-ledger-pending
+data_private/
+
+# v10 raw source downloads (licence-checked public data; regenerable)
+data_raw/
+data_pool/
+release/

paxmod_guard-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: paxmod-guard
+Version: 0.1.0
+Summary: Local safety classifier for AI companions, chatbots and kids' game chat: self-harm, grooming, sexual content, jailbreaks and more, on your own CPU in milliseconds.
+Author: Paxmod
+License-Expression: Apache-2.0
+Keywords: ai-safety,chatbot,child-safety,companion,guardrails,llm,moderation,onnx
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.24
+Requires-Dist: onnxruntime>=1.17
+Requires-Dist: tokenizers>=0.15
+Description-Content-Type: text/markdown
+
+# paxmod-guard
+
+Safety checks for AI companions, chatbots and kids' game chat, running on your own CPU. No API key, no network calls
+after the first model download, and no message ever leaves your server. The Python twin of the
+[`@paxmod/guard`](https://www.npmjs.com/package/@paxmod/guard) npm package: same model, same scores.
+
+```bash
+pip install paxmod-guard
+```
+
+```python
+from paxmod_guard import Guard
+
+guard = Guard()  # downloads the model once (about 220 MB) to ~/.cache/paxmod-guard
+
+# 1. Check what the user sent before your model sees it
+r = guard.check_input(user_message)
+if r.crisis_reply:
+    return r.crisis_reply          # self-harm risk: answer with crisis support, not the persona
+if "jailbreak" in r.labels:
+    return "Let's keep things friendly."
+
+# 2. Check what your bot wrote before the user sees it
+reply = llm.generate(user_message)
+if guard.check_output(reply).flagged:
+    return regenerate_or_refuse()
+```
+
+Needs about 1 GB of memory: run it in a container or on a server, not in small serverless functions.
+
+Game or community chat, with the messages before it, or a whole conversation (grooming and other patterns that no
+single message shows):
+
+```python
+guard.check_chat("wanna add me on snap", context=[{"role": "player", "speaker": "B", "text": "im 12"}])
+guard.check_conversation([{"role": "player", "speaker": "A", "text": "..."}, ...])
+```
+
+Each result has `flagged`, `labels`, `scores` (every label, 0 to 1) and `latency_ms`. Signal labels (grooming tactics,
+distress, swearing, age questions, romance) are always scored but only flag when enabled:
+`Guard(enable=["secrecy", "risk_check"])`. Thresholds can be overridden per label: `Guard(thresholds={"sexual": 0.7})`.
+
+Licence: Apache-2.0. Model card and labels: https://huggingface.co/paxmod/guard

paxmod_guard-0.1.0/README.md

@@ -0,0 +1,43 @@
+# paxmod-guard
+
+Safety checks for AI companions, chatbots and kids' game chat, running on your own CPU. No API key, no network calls
+after the first model download, and no message ever leaves your server. The Python twin of the
+[`@paxmod/guard`](https://www.npmjs.com/package/@paxmod/guard) npm package: same model, same scores.
+
+```bash
+pip install paxmod-guard
+```
+
+```python
+from paxmod_guard import Guard
+
+guard = Guard()  # downloads the model once (about 220 MB) to ~/.cache/paxmod-guard
+
+# 1. Check what the user sent before your model sees it
+r = guard.check_input(user_message)
+if r.crisis_reply:
+    return r.crisis_reply          # self-harm risk: answer with crisis support, not the persona
+if "jailbreak" in r.labels:
+    return "Let's keep things friendly."
+
+# 2. Check what your bot wrote before the user sees it
+reply = llm.generate(user_message)
+if guard.check_output(reply).flagged:
+    return regenerate_or_refuse()
+```
+
+Needs about 1 GB of memory: run it in a container or on a server, not in small serverless functions.
+
+Game or community chat, with the messages before it, or a whole conversation (grooming and other patterns that no
+single message shows):
+
+```python
+guard.check_chat("wanna add me on snap", context=[{"role": "player", "speaker": "B", "text": "im 12"}])
+guard.check_conversation([{"role": "player", "speaker": "A", "text": "..."}, ...])
+```
+
+Each result has `flagged`, `labels`, `scores` (every label, 0 to 1) and `latency_ms`. Signal labels (grooming tactics,
+distress, swearing, age questions, romance) are always scored but only flag when enabled:
+`Guard(enable=["secrecy", "risk_check"])`. Thresholds can be overridden per label: `Guard(thresholds={"sexual": 0.7})`.
+
+Licence: Apache-2.0. Model card and labels: https://huggingface.co/paxmod/guard

paxmod_guard-0.1.0/paxmod_guard/__init__.py

@@ -0,0 +1,219 @@
+"""paxmod-guard: a local safety classifier for AI companions, chatbots and kids' game chat.
+
+Runs Paxmod's Guard model on your own CPU with ONNX Runtime. No API calls; no message leaves the machine.
+A Python port of the @paxmod/guard npm SDK: same model files, same input format, same scores.
+
+    from paxmod_guard import Guard
+    guard = Guard()                      # downloads the model once (about 220 MB) to ~/.cache/paxmod-guard
+    r = guard.check_input(user_message)
+    if r.crisis_reply: ...               # self-harm risk: answer with crisis support, not the persona
+"""
+from __future__ import annotations
+
+import json
+import math
+import re
+import os
+import time
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Iterable, Optional
+
+import numpy as np
+import onnxruntime as ort
+from tokenizers import Tokenizer
+
+__all__ = ["Guard", "Result", "download_model", "MODEL_VERSION", "DEFAULT_CRISIS_REPLY"]
+
+MODEL_VERSION = "paxmodguard-v1"
+MODEL_FILES = ["model.int8.onnx", "tokenizer.json", "tokenizer_config.json", "guard.json"]
+DEFAULT_MODEL_URL = "https://huggingface.co/paxmod/guard/resolve/main"
+DEFAULT_CRISIS_REPLY = (
+    "It sounds like you're going through something really painful, and I'm glad you told me. "
+    "I'm an AI, so please reach out to someone who can help right now. In the US you can call or text 988 "
+    "(Suicide & Crisis Lifeline). Elsewhere, findahelpline.com lists free, confidential lines in your country."
+)
+# v10 renamed self_harm to self_harm_intent; either triggers the crisis reply.
+CRISIS = ("self_harm_intent", "self_harm")
+
+
+def _cache_dir() -> Path:
+    if os.environ.get("PAXMOD_GUARD_CACHE"):
+        return Path(os.environ["PAXMOD_GUARD_CACHE"])
+    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "paxmod-guard"
+
+
+def download_model(cache_dir: Optional[str] = None, model_url: Optional[str] = None,
+                   on_progress: Optional[Callable[[str], None]] = None) -> Path:
+    """Download the model files if they are not there yet. Returns the model directory."""
+    url = model_url or os.environ.get("PAXMOD_GUARD_MODEL_URL") or DEFAULT_MODEL_URL
+    d = Path(cache_dir) if cache_dir else _cache_dir() / MODEL_VERSION
+    d.mkdir(parents=True, exist_ok=True)
+    for f in MODEL_FILES:
+        dest = d / f
+        if dest.exists():
+            continue
+        if on_progress:
+            on_progress(f"Downloading {f}")
+        part = dest.with_suffix(dest.suffix + f".{os.getpid()}.part")
+        with urllib.request.urlopen(f"{url}/{MODEL_VERSION}/{f}") as res, open(part, "wb") as out:
+            while chunk := res.read(1 << 20):
+                out.write(chunk)
+        part.rename(dest)  # atomic: a half-written file is never mistaken for a finished one
+    return d
+
+
+@dataclass
+class Result:
+    flagged: bool
+    labels: list[str]
+    scores: dict[str, float]
+    latency_ms: float
+    direction: Optional[str] = None
+    crisis_reply: Optional[str] = None
+    turns: Optional[int] = None
+
+
+@dataclass
+class _Stats:
+    checks: int = 0
+    flagged: int = 0
+    crisis_referrals: int = 0
+    since: str = field(default_factory=lambda: time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()))
+
+
+class Guard:
+    """Load the Guard model. Downloads it on first use unless `model_dir` points at local files.
+
+    enable: signal labels (grooming tactics, distress, swearing, age questions, romance) to count towards flags;
+    they are always scored. include_unsafe: also count the general "unsafe" score.
+    """
+
+    def __init__(self, model_dir: Optional[str] = None, *, enable: Iterable[str] = (), include_unsafe: bool = False,
+                 thresholds: Optional[dict[str, float]] = None, threads: int = 2, window_tokens: int = 128,
+                 crisis_reply: str = DEFAULT_CRISIS_REPLY, on_crisis: Optional[Callable[[Result], None]] = None):
+        d = Path(model_dir) if model_dir else download_model()
+        meta = json.loads((d / "guard.json").read_text())
+        self.labels: list[str] = meta["labels"]
+        self.model: str = meta.get("version", MODEL_VERSION)
+        self.thresholds = {**meta.get("thresholds", {}), **(thresholds or {})}
+        self.max_length = meta.get("max_length", 256)
+        self.window_tokens = window_tokens
+        self.crisis_reply, self.on_crisis = crisis_reply, on_crisis
+        on = set(enable) | ({"unsafe"} if include_unsafe else set())
+        self._off = {l for l in meta.get("default_off", ["unsafe"]) if l not in on}
+        self.tokenizer = Tokenizer.from_file(str(d / "tokenizer.json"))
+        so = ort.SessionOptions(); so.intra_op_num_threads = threads
+        self.session = ort.InferenceSession(str(d / "model.int8.onnx"), so, providers=["CPUExecutionProvider"])
+        self.contextual = "grooming" in self.labels
+        self._stats = _Stats()
+
+    # Long messages are split into overlapping windows at two sizes, full-length for context and short so one bad
+    # sentence in a long message is not drowned out. A label's score is its highest across all windows.
+    def _windows(self, text: str, short: bool) -> list[list[int]]:
+        ids = self.tokenizer.encode(re.sub(" {2,}", " ", text)).ids  # as the npm SDK (its tokenizer splits space runs differently)
+        cls, sep, body = ids[0], ids[-1], ids[1:-1]
+        sizes = [self.max_length - 2]
+        small = min(self.max_length, self.window_tokens) - 2
+        if short and small < sizes[0] and len(body) > small:
+            sizes.append(small)
+        out = []
+        for size in sizes:
+            stride = int(size * 0.75)
+            i = 0
+            while True:
+                out.append([cls, *body[i:i + size], sep])
+                if i + size >= len(body):
+                    break
+                i += stride
+        return out
+
+    def _score(self, texts: list[str], short: bool = True) -> dict[str, float]:
+        wins = sorted((w for t in texts for w in self._windows(t, short)), key=len)
+        best = np.full(len(self.labels), -np.inf)
+        for k in range(0, len(wins), 8):  # small batches of similar length: little padding
+            batch = wins[k:k + 8]; n = len(batch[-1])
+            ids = np.zeros((len(batch), n), dtype=np.int64); mask = np.zeros_like(ids)
+            for b, w in enumerate(batch):
+                ids[b, :len(w)] = w; mask[b, :len(w)] = 1
+            logits = self.session.run(["logits"], {"input_ids": ids, "attention_mask": mask})[0]
+            best = np.maximum(best, logits.max(0))
+        return {l: 1 / (1 + math.exp(-float(v))) for l, v in zip(self.labels, best)}
+
+    @staticmethod
+    def _cut(t: str, n: int = 300) -> str:
+        return t if len(t) <= n else t[:n] + "…"  # as in training: 300 for earlier turns
+
+    @staticmethod
+    def _tag(turn: dict) -> str:
+        role = turn.get("role") or {"output": "ai", "chat": "player"}.get(turn.get("direction"), "user")
+        if role == "ai": return "[AI]"
+        if role == "player": return f"[CHAT:{turn['speaker']}]" if turn.get("speaker") else "[CHAT]"
+        return "[USER]"
+
+    def _with_context(self, text: str, direction: str, context: list[dict]) -> str:
+        target = f"[TARGET] {self._tag({'direction': direction})} {self._cut(text, 1000)}"  # the judged turn: 1000, as in training
+        earlier = [f"{self._tag(t)} {self._cut(t.get('text') or '')}" for t in context]
+        for k in range(len(earlier) + 1):
+            s = " ".join(earlier[k:] + [target])
+            if k == len(earlier) or len(self.tokenizer.encode(s).ids) <= self.max_length:
+                return s
+        return target
+
+    def _flags(self, scores: dict[str, float]) -> list[str]:
+        return [l for l in self.labels if l not in self._off and scores[l] >= self.thresholds.get(l, 0.5)]
+
+    def check(self, text: str, direction: str = "input", context: Optional[list[dict]] = None) -> Result:
+        """direction: "input" = a person writing to an AI, "output" = the AI, "chat" = a person writing to other people.
+        context: earlier turns, e.g. [{"role": "player", "speaker": "B", "text": "..."}] (role user / ai / player)."""
+        if not isinstance(text, str):
+            raise TypeError("paxmod_guard: text must be a string")
+        t0 = time.perf_counter()
+        if not self.contextual:
+            inp = f"{'[AI]' if direction == 'output' else '[USER]'} {text}"
+        elif context:
+            inp = self._with_context(text, direction, context)
+        else:
+            inp = f"{'[CHAT]' if direction == 'chat' else self._tag({'direction': direction})} {text}"  # read whole, in windows
+        scores = self._score([inp], not (self.contextual and context)) if text.strip() else {l: 0.0 for l in self.labels}
+        flags = self._flags(scores)
+        r = Result(bool(flags), flags, scores, round((time.perf_counter() - t0) * 1000, 1), direction)
+        self._stats.checks += 1; self._stats.flagged += bool(flags)
+        if direction != "output" and any(l in flags for l in CRISIS):
+            r.crisis_reply = self.crisis_reply; self._stats.crisis_referrals += 1
+            if self.on_crisis: self.on_crisis(r)
+        return r
+
+    def check_input(self, text: str, context: Optional[list[dict]] = None) -> Result:
+        """Check a message from the user before your bot sees it."""
+        return self.check(text, "input", context)
+
+    def check_output(self, text: str, context: Optional[list[dict]] = None) -> Result:
+        """Check your bot's reply before the user sees it."""
+        return self.check(text, "output", context)
+
+    def check_chat(self, text: str, context: Optional[list[dict]] = None) -> Result:
+        """Check a message one person wrote to others (game or community chat)."""
+        return self.check(text, "chat", context)
+
+    def check_conversation(self, turns: list[dict]) -> Result:
+        """Judge a whole stretch of conversation, e.g. a DM with both sides, including patterns no single message
+        shows (grooming). Read as in training: windows of up to 40 turns, overlapping by half."""
+        if not self.contextual:
+            raise RuntimeError("paxmod_guard: check_conversation needs a v9 or later model")
+        t0 = time.perf_counter()
+        parts, i = [], 0
+        while True:
+            parts.append("[CONVERSATION] " + " ".join(f"{self._tag(t)} {self._cut(t.get('text') or '')}" for t in turns[i:i + 40]))
+            if i + 40 >= len(turns):
+                break
+            i += 20
+        scores = self._score(parts, False)
+        flags = self._flags(scores)
+        self._stats.checks += 1; self._stats.flagged += bool(flags)
+        return Result(bool(flags), flags, scores, round((time.perf_counter() - t0) * 1000, 1), turns=len(turns))
+
+    def stats(self) -> dict:
+        """Counts since this guard was created: checks, flagged messages, crisis referrals (e.g. for SB 243 reports)."""
+        return dict(self._stats.__dict__)

paxmod_guard-0.1.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "paxmod-guard"
+version = "0.1.0"
+description = "Local safety classifier for AI companions, chatbots and kids' game chat: self-harm, grooming, sexual content, jailbreaks and more, on your own CPU in milliseconds."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+authors = [{ name = "Paxmod" }]
+keywords = ["guardrails", "ai-safety", "moderation", "companion", "chatbot", "llm", "onnx", "child-safety"]
+dependencies = ["onnxruntime>=1.17", "tokenizers>=0.15", "numpy>=1.24"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"