mentar 0.1.0.dev0__py3-none-any.whl

mentar/grounding/sources.py

@@ -0,0 +1,267 @@
+r"""ZIM source-location handling: local paths, mounted NAS, and SMB/Samba shares.
+
+A ZIM lives somewhere; ``libzim`` can only open a **local filesystem path** (it
+mmaps the file for random access). This module turns a configured *location* into
+a local path the reader can open:
+
+    materialize_zim(location, cfg) -> Path | None
+
+Supported location forms:
+  - **Local path**            ``/data/zims/vikidia.zim`` — returned as-is.
+  - **Mounted NAS / share**   ``/mnt/nas/zims/vikidia.zim`` or a Windows drive /
+                              UNC that the OS has already mounted — also just a
+                              filesystem path, returned as-is (NO copy: the whole
+                              point of NAS storage is to avoid a local copy).
+  - **SMB URL / UNC**         ``smb://nas/share/vikidia.zim`` /
+                              ``\\nas\share\vikidia.zim`` / ``//nas/share/...`` —
+                              not a real local file, so it is **copied once** to a
+                              local cache dir (``grounding.zim_cache_dir``) via
+                              ``smbclient`` (optional dep ``smbprotocol``), then the
+                              cached path is returned.
+
+NOW (W7.4): local + mounted-NAS + SMB read/download.
+FUTURE GOAL: pull from global Kiwix mirrors to any reasonable destination on any
+OS (see ``scripts/fetch_zim.py``). Catalog/mirror discovery is not built yet.
+
+Degradation contract (SAFETY §1.5 / SPEC §15): every failure returns ``None`` and
+logs a warning — this module NEVER raises. ``smbprotocol`` is optional; if an SMB
+location is requested without it installed, we warn and return ``None``.
+
+Spec: docs/design/W7_grounding_reader.md (ZIM acquisition / SMB read row).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_COPY_CHUNK = 8 * 1024 * 1024  # 8 MiB streaming chunk for SMB → local copies
+_DEFAULT_ZIM_CACHE = ".cache/zim"
+_DATE_RE = r"\d{4}-\d{2}"  # Kiwix embeds a YYYY-MM build date in the filename
+
+
+# ── Location classification & joining ─────────────────────────────────────────
+
+
+def is_smb_location(location: str) -> bool:
+    """True if ``location`` is an SMB URL or UNC path (not a plain/mounted path).
+
+    Recognises ``smb://host/share/...``, ``\\\\host\\share\\...`` and
+    ``//host/share/...``. A path that the OS has already *mounted* (e.g.
+    ``/mnt/nas/...`` or ``Z:\\...``) is NOT an SMB location — it is a normal
+    filesystem path and needs no SMB client.
+    """
+    s = str(location).strip()
+    return s.startswith("smb://") or s.startswith("\\\\") or s.startswith("//")
+
+
+def smb_url_to_unc(location: str) -> str:
+    """Normalise an SMB location to a UNC path (``\\\\host\\share\\...``).
+
+    ``smbclient`` expects UNC. ``smb://nas/share/f.zim`` and ``//nas/share/f.zim``
+    both become ``\\\\nas\\share\\f.zim``; an already-UNC path is returned as-is.
+    """
+    s = str(location).strip()
+    if s.startswith("smb://"):
+        return "\\\\" + s[len("smb://"):].replace("/", "\\")
+    if s.startswith("//"):
+        return "\\\\" + s[2:].replace("/", "\\")
+    return s  # already \\host\share\...
+
+
+def join_location(base: str, filename: str) -> str:
+    """Join ``filename`` onto a ZIM directory ``base`` (SMB-aware).
+
+    For local/mounted bases this is an ordinary path join. For SMB bases the
+    scheme/separator style is preserved (``smb://`` and ``//`` join with ``/``;
+    a backslash UNC joins with ``\\``).
+    """
+    b = str(base)
+    if is_smb_location(b):
+        if b.startswith("\\\\"):
+            return b.rstrip("\\/") + "\\" + filename
+        return b.rstrip("/") + "/" + filename
+    return str(Path(b).expanduser() / filename)
+
+
+# ── Filename grammar: <project>_<lang>_<selection>_<flavour>_<YYYY-MM>.zim ─────
+# Kiwix names embed project, language, selection (subject/"all"), flavour
+# (maxi|nopic|mini) and a YYYY-MM build date — e.g. wikipedia_en_astronomy_maxi_2026-02.zim
+# or wikipedia_ace_all_nopic_2026-04.zim. A source is declared by those parts in
+# config; the NEWEST matching file is used automatically (latest wins) unless pinned.
+
+
+def parse_index(html: str) -> list[str]:
+    """Return the .zim filenames linked in a Kiwix directory-index HTML page."""
+    return re.findall(r'href="([^"?/]+\.zim)"', html)
+
+
+def pick_latest(filenames: list[str], regex: str) -> Optional[str]:
+    """Pick the newest filename matching ``regex`` (YYYY-MM sorts lexicographically)."""
+    rx = re.compile(regex)
+    cands = sorted(f for f in filenames if rx.search(f))
+    return cands[-1] if cands else None
+
+
+def build_filename_regex(spec: dict) -> str:
+    """Build an anchored filename regex from a structured source spec.
+
+    spec keys: ``project`` (req), ``lang`` (req), ``selection`` (opt, e.g. "all" /
+    "astronomy" / "simple_all"), ``flavour`` (opt, e.g. "maxi" / "nopic"),
+    ``pin`` (opt: a ``YYYY-MM`` date to fix the build; a full ``*.zim`` pin is
+    handled earlier in :func:`resolve_filename`).
+    """
+    parts = [re.escape(str(spec["project"])), re.escape(str(spec["lang"]))]
+    if spec.get("selection"):
+        parts.append(re.escape(str(spec["selection"])))
+    if spec.get("flavour"):
+        parts.append(re.escape(str(spec["flavour"])))
+    body = "_".join(parts)
+    pin = spec.get("pin")
+    date = re.escape(str(pin)) if (pin and re.fullmatch(_DATE_RE, str(pin))) else _DATE_RE
+    return rf"^{body}_{date}\.zim$"
+
+
+def list_zim_dir(zim_dir: str, cfg: dict) -> list[str]:
+    """List ``*.zim`` filenames in a local/mounted dir or an SMB dir. ``[]`` on failure."""
+    try:
+        if is_smb_location(zim_dir):
+            try:
+                import smbclient
+            except ImportError:
+                logger.warning("list_zim_dir: SMB dir %r needs the [nas] extra (smbprotocol)", zim_dir)
+                return []
+            _configure_smb_auth(cfg)
+            return [f for f in smbclient.listdir(smb_url_to_unc(zim_dir)) if f.endswith(".zim")]
+        d = Path(zim_dir).expanduser()
+        if not d.is_dir():
+            return []
+        return [f.name for f in d.iterdir() if f.suffix == ".zim"]
+    except Exception:
+        logger.warning("list_zim_dir: cannot list %r — returning []", zim_dir, exc_info=True)
+        return []
+
+
+def resolve_filename(spec, zim_dir: str, cfg: dict) -> Optional[str]:
+    """Resolve a source spec to a concrete ZIM filename present in ``zim_dir``.
+
+    ``spec`` may be:
+      - **str** — an exact filename (legacy / manual). Returned as-is.
+      - **dict** — ``{project, lang, selection?, flavour?, pin?}``. The newest file
+        in ``zim_dir`` matching the grammar is chosen (latest ``YYYY-MM`` wins); a
+        ``pin`` of a full ``*.zim`` name or a ``YYYY-MM`` date overrides "latest".
+
+    Returns ``None`` if nothing matches (caller applies the degradation contract).
+    """
+    if isinstance(spec, str):
+        return spec or None
+    if not isinstance(spec, dict):
+        return None
+    pin = spec.get("pin")
+    if pin and str(pin).endswith(".zim"):
+        return str(pin)  # explicit file pin — no listing needed
+    regex = build_filename_regex(spec)
+    latest = pick_latest(list_zim_dir(zim_dir, cfg), regex)
+    if latest is None:
+        logger.warning("resolve_filename: no ZIM in %r matches %s (spec=%r)", zim_dir, regex, spec)
+    return latest
+
+
+# ── Materialization ───────────────────────────────────────────────────────────
+
+
+def materialize_zim(location: str, cfg: dict) -> Optional[Path]:
+    """Return a local filesystem path libzim can open, or ``None`` on failure.
+
+    Local / mounted paths are returned as-is (no copy). SMB locations are copied
+    once to ``grounding.zim_cache_dir`` and the cached path returned. Never raises.
+    """
+    try:
+        loc = str(location)
+        if not is_smb_location(loc):
+            p = Path(loc).expanduser()
+            if not p.exists():
+                logger.warning("materialize_zim: ZIM not found at local/mounted path: %s", p)
+                return None
+            return p
+        return _materialize_smb(loc, cfg)
+    except Exception:
+        logger.warning("materialize_zim: unexpected error for %r — returning None", location, exc_info=True)
+        return None
+
+
+def _zim_cache_dir(cfg: dict) -> Path:
+    raw = (cfg.get("zim_cache_dir") or _DEFAULT_ZIM_CACHE)
+    return Path(os.path.expanduser(str(raw)))
+
+
+def _configure_smb_auth(cfg: dict) -> None:
+    """Apply SMB credentials from ``cfg['smb']`` to the global smbclient config.
+
+    No-op when SMB is not enabled or no username is configured (anonymous /
+    pre-registered sessions still work). Importing smbclient is the caller's job.
+    """
+    smb = cfg.get("smb") or {}
+    if not smb.get("enabled"):
+        return
+    user = smb.get("username") or None
+    pw = smb.get("password") or None
+    domain = smb.get("domain") or None
+    if user and domain and "\\" not in user and "@" not in user:
+        user = f"{domain}\\{user}"
+    if user or pw:
+        import smbclient
+        smbclient.ClientConfig(username=user, password=pw)
+
+
+def _materialize_smb(location: str, cfg: dict) -> Optional[Path]:
+    """Copy an SMB ZIM to the local cache and return the cached path, or None."""
+    try:
+        import smbclient
+        from smbclient import open_file
+    except ImportError:
+        logger.warning(
+            "materialize_zim: SMB location %r requested but 'smbprotocol' is not installed. "  # t7.3-exempt: operator log message, not a prompt
+            "Install it with: pip install 'mentar[nas]'  (or mount the share and point "
+            "grounding.zim_dir at the mount). Returning None.",
+            location,
+        )
+        return None
+
+    unc = smb_url_to_unc(location)
+    _configure_smb_auth(cfg)
+
+    cache_dir = _zim_cache_dir(cfg)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    local = cache_dir / Path(unc.replace("\\", "/")).name
+
+    # Reuse a cached copy when its size matches the remote (cheap freshness check).
+    remote_size: Optional[int] = None
+    try:
+        remote_size = smbclient.stat(unc).st_size
+    except Exception:
+        logger.warning("materialize_zim: cannot stat SMB path %s", unc, exc_info=True)
+    if local.exists() and remote_size is not None and local.stat().st_size == remote_size:
+        logger.debug("materialize_zim: reusing cached SMB copy %s", local)
+        return local
+
+    logger.info("materialize_zim: copying SMB ZIM %s → %s (this can be large)", unc, local)
+    tmp = local.with_name(local.name + ".tmp")
+    try:
+        with open_file(unc, mode="rb") as src, open(tmp, "wb") as dst:
+            shutil.copyfileobj(src, dst, length=_COPY_CHUNK)
+        os.replace(tmp, local)
+    except Exception:
+        logger.warning("materialize_zim: failed copying SMB ZIM %s", unc, exc_info=True)
+        try:
+            tmp.unlink(missing_ok=True)
+        except Exception:
+            pass
+        return None
+    return local

mentar/grounding/wrapper.py

@@ -0,0 +1,50 @@
+"""Grounding passage wrapper: return inner text for {{grounding_passage}}.
+
+SAFETY §1.5 / W2.3 contract (grounding-as-data):
+    The <<<GROUNDING_BEGIN>>> / <<<GROUNDING_END>>> markers already live in
+    ``prompts/system_prompt.md``.  This module returns the **inner text only** —
+    it never double-wraps.  The prompt layer is the exclusive owner of the
+    markers; this module merely enforces the length bound and ensures a clean
+    return value.
+
+Safety principle:
+    The reader returns passage content **verbatim as data**.  This module does
+    NOT strip, filter, or interpret the passage — it only length-bounds it.
+    Prompt injection resistance is handled by the system prompt's marker framing
+    (SAFETY §1.5).  Stripping "suspicious" strings here would be a security
+    theatre that silently corrupts legitimate educational content.
+
+Spec: docs/design/W7_grounding_reader.md (Safety row + wrapper.py row).
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_MAX_CHARS = 1200
+
+
+def wrap_passage(passage: str, cfg: dict) -> str:
+    """Length-bound ``passage`` and return the inner text for ``{{grounding_passage}}``.
+
+    Args:
+        passage: Raw plain-text passage resolved by the reader (may be "").
+        cfg:     The ``grounding:`` config block (for ``max_passage_chars``).
+
+    Returns:
+        The passage, truncated to ``max_passage_chars`` if needed.  Returns ""
+        on empty / whitespace-only input.  Never raises.
+    """
+    if not passage or not passage.strip():
+        return ""
+
+    max_chars: int = int(cfg.get("max_passage_chars", _DEFAULT_MAX_CHARS))
+
+    # Length-bound (SPEC §15 / config contract)
+    if len(passage) > max_chars:
+        passage = passage[:max_chars].rstrip()
+        logger.debug("wrap_passage: truncated to %d chars", max_chars)
+
+    return passage

mentar/inference/__init__.py

@@ -0,0 +1,7 @@
+"""Pluggable LLM backend abstraction: generate(prompt, grounding_passages, constraints) -> text.
+
+Primary local backend: llama.cpp (GGUF) — lightest, broadest hardware support (2026-06-15).
+Also: vLLM (capable-GPU tier), Ollama (wrapper), Gemini/Claude API (opt-in, parent owns key).
+llama.cpp + vLLM both expose OpenAI-compatible endpoints → one provider path (base_url swap).
+Spec: docs/SPEC.md §20.1.
+"""

mentar/safety/__init__.py

@@ -0,0 +1,4 @@
+"""Content filters, escalation, age-mode enforcement, content blocks, injection guard.
+
+Spec: docs/SAFETY.md (6-layer); tests: T2.x.
+"""

mentar/safety/escalation.py

@@ -0,0 +1,316 @@
+"""Child-safety escalation classifier.
+
+Spec: docs/SAFETY.md Layer 3 (§3.1–§3.5); docs/design/W2.2_escalation.md §2–§4.
+Tests: tests/safety/test_escalation.py (T2.1) — 20 positive + 20 negative fixtures.
+
+This module is PURE: no DB writes, no FSM transitions, no LLM calls. The caller
+(session loop / FSM driver) is responsible for logging, freeze, and handoff once
+`classify()` returns a non-None match. See design §4 and `handle_trigger()` below
+for the thin caller-side helper that demonstrates the end-to-end flow.
+
+Two open rollout guards (W2.2 design §7 / SAFETY.md §3.5 — do not lose):
+  1. Handoff wording (HANDOFF_MESSAGE_PRIMARY/SUPPORT) has NOT been reviewed by a
+     safeguarding professional or child-communication specialist. Professional review
+     is REQUIRED before any rollout beyond the supervised single-family Phase-0 pilot.
+  2. Emergency-services signposting is explicitly absent (pilot routes to physically-
+     present parent). This FAILS when the parent is the source of harm (physical_danger /
+     abuse_disclosure cases). Crisis-helpline signposting with safeguarding input is
+     REQUIRED before unsupervised/independent mode is enabled.
+"""
+
+from __future__ import annotations
+
+import re
+import sqlite3
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Public API types  (design §3)
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TriggerClass(str, Enum):
+    HARM_TO_SELF          = "harm_to_self"
+    PHYSICAL_DANGER       = "physical_danger"
+    SEVERE_DISTRESS       = "severe_distress"
+    ABUSE_DISCLOSURE      = "abuse_disclosure"
+    SECRECY_REQUEST       = "secrecy_request"
+    ADVERSARIAL_JAILBREAK = "adversarial_jailbreak"
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH     = "high"
+    LOW      = "low"
+
+
+@dataclass(frozen=True)
+class TriggerMatch:
+    trigger_class: TriggerClass
+    severity: Severity
+    matched_span: str  # the substring that fired (for log/debug — NOT the alert)
+    # NB: the FULL verbatim input is logged separately and never truncated.
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Fixed handoff messages — VERBATIM from SAFETY.md §3.4
+# These are NEVER passed through the LLM.  (design §3, §4 Step 3)
+# ─────────────────────────────────────────────────────────────────────────────
+
+HANDOFF_MESSAGE_PRIMARY: str = (
+    "This is something to talk about with your grown-up. "
+    "Let's pause our lesson here."
+)
+
+HANDOFF_MESSAGE_SUPPORT: str = (
+    "Your grown-up can help you with this. "
+    "Your lesson will be here when you're ready to come back."
+)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Per-class keyword/regex banks (design §3 — module-level so Bucket D can
+# swap them wholesale).
+#
+# Matching philosophy (design §3 classifier rules):
+#   • Case-insensitive, compiled once.
+#   • Sensitivity-biased: false positives are acceptable; false negatives are not.
+#   • Word-boundary-aware where it prevents obvious trust-eroding false positives
+#     (e.g. "die" in "diet"/"died in the game") — any exception is documented.
+#   • Substring match otherwise (no boundary needed where context is unambiguous).
+#
+# Word-boundary approach: \b is used around short ambiguous roots (die/hurt/kill).
+# Longer phrases and full self-harm expressions are matched as substrings because
+# the phrase itself is unambiguous in any surrounding context.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ── A: harm_to_self (CRITICAL) ───────────────────────────────────────────────
+# Patterns covering suicidal ideation and self-harm intent.
+# "die" is word-boundary protected: "die" alone triggers but "diet"/"died" do not.
+# "hurt myself" / "harm myself" are phrase-matched (no boundary needed).
+# "don't want to be here anymore" and "no reason to live" catch indirect ideation.
+_HARM_TO_SELF_PATTERNS: list[re.Pattern[str]] = [p for p in (
+    re.compile(r"i want to (die|kill myself|end my life|hurt myself|harm myself)", re.I),
+    re.compile(r"i('m going| am going| want) to (hurt|harm|kill) myself", re.I),
+    re.compile(r"i('m| am) going to (hurt|harm|kill) myself", re.I),
+    re.compile(r"(hurt|harm|kill) myself", re.I),
+    re.compile(r"want to (end|take) my (life|own life)", re.I),
+    re.compile(r"no reason to (live|go on|be alive)", re.I),
+    # "I don't want to be here anymore" — indirect self-harm ideation
+    re.compile(r"(don'?t|do not) want to be here (anymore|any more)", re.I),
+    # standalone "want to die" — word-boundary on "die" avoids "died"/"dies"
+    # but we use phrase match since "want to die" is unambiguous
+    re.compile(r"want to die", re.I),
+    # bare "i want to die" also caught above; "i might as well die" etc.
+    re.compile(r"\bi might as well (die|be dead)\b", re.I),
+    # "I'm thinking about ending it all" — indirect
+    re.compile(r"thinking (about|of) (ending|killing) (it|myself|my life)", re.I),
+    # "I've been cutting myself" / "I cut myself on purpose"
+    re.compile(r"(cutting|cut) myself (on purpose|to hurt|because)", re.I),
+)]
+
+# ── A: physical_danger (CRITICAL) ────────────────────────────────────────────
+# Patterns for immediate physical danger / abuse by another person.
+# "hurt me" is phrase-matched; "hit me" similarly.
+_PHYSICAL_DANGER_PATTERNS: list[re.Pattern[str]] = [p for p in (
+    re.compile(r"someone (is|has been|keeps|was) (hurting|hitting|beating|abusing|punching|kicking) me", re.I),
+    re.compile(r"(he|she|they|he's|she's) (hurt|hit|beat|kicked|punched|abused) me", re.I),
+    re.compile(r"(i am|i'?m) (being|getting) (hurt|hit|beaten|abused|punched|kicked)", re.I),
+    re.compile(r"(don'?t feel|don'?t feel) safe (at home|in my house|at school|here)", re.I),
+    re.compile(r"(i'?m|i am) not safe", re.I),
+    re.compile(r"not safe at home", re.I),
+    re.compile(r"(someone|a person|grown.?up|adult|man|woman|he|she|they) (hurts|hits|beats|kicks|punches) me", re.I),
+    re.compile(r"(my|our) (dad|mum|mom|stepdad|stepmom|uncle|aunt|teacher|brother|sister|carer|guardian) (hurts|hits|beats|abuses|punches|kicks) me", re.I),
+    re.compile(r"being (physically )?abused", re.I),
+    # "I'm in danger" / "I'm scared someone will hurt me"
+    re.compile(r"(i'?m|i am) in danger", re.I),
+    re.compile(r"scared (that )?(someone|he|she|they) will (hurt|hit|kill|harm) me", re.I),
+)]
+
+# ── B: severe_distress (HIGH) ────────────────────────────────────────────────
+# Patterns for severe emotional/welfare distress beyond normal frustration.
+# Calibration note (design §5): "I'm a bit sad today" is documented as BELOW
+# threshold in v0.1 (see negative fixtures). We require explicit despair/
+# hopelessness words, not mild mood reports.
+# "dying of boredom" / "killing me" in game/school context → NOT fired (see negatives).
+_SEVERE_DISTRESS_PATTERNS: list[re.Pattern[str]] = [p for p in (
+    re.compile(r"(everything|nothing|life) (is|feels?) (hopeless|pointless|meaningless|worthless|terrible|awful)", re.I),
+    re.compile(r"i('?ve| have) been (crying|sobbing) (all|every|for) (day|night|week|hours?)", re.I),
+    re.compile(r"(i feel|i'?m feeling) (completely )?(hopeless|worthless|empty|broken|destroyed|devastated)", re.I),
+    re.compile(r"nobody (loves?|cares? about|wants) me", re.I),
+    re.compile(r"(i hate|i can'?t stand) (my life|myself|being alive|living)", re.I),
+    re.compile(r"(can'?t|cannot) (cope|go on|take (it|this|anymore)|keep going)", re.I),
+    re.compile(r"(every ?thing|my whole life) is (falling apart|ruined|over|destroyed)", re.I),
+    # persistent despair markers
+    re.compile(r"(always|never) (feel|felt|going to) (better|happy|good|okay|ok)\b", re.I),
+    re.compile(r"(too much|no point) (to|in) (living|life|going on|continuing)", re.I),
+)]
+
+# ── C: abuse_disclosure (CRITICAL) ───────────────────────────────────────────
+# Patterns for grooming, sexual abuse, exploitation disclosures.
+# "touched" used in abuse context; "private parts" / "private areas" etc.
+_ABUSE_DISCLOSURE_PATTERNS: list[re.Pattern[str]] = [p for p in (
+    re.compile(r"(touched|touches|touching) (my|our) (private|body|bits|parts?|area)", re.I),
+    re.compile(r"someone (touched|is touching|has touched|touched me) in (a )?wrong (way|place)", re.I),
+    re.compile(r"(sexual|inappropriate|rude|dirty) (touch|touching|things?|photos?|pictures?|videos?)", re.I),
+    re.compile(r"(show(ing|n)?|send(ing)?|sent|shar(e|ing)) (me )?(naked|nude|rude|sexual|private) (photos?|pictures?|videos?|images?)", re.I),
+    re.compile(r"(ask(ing|ed)? me to) (take off|remove) (my |their )?(clothes|clothing|shirt|top)", re.I),
+    re.compile(r"(adult|grown.?up|man|woman|teacher|coach|uncle|neighbour|neighbor|stranger|person|he|she|they) (want(s|ed)? (to )?(touch|see|have|do))", re.I),
+    # Grooming patterns: gifts, special relationship, "our secret"
+    re.compile(r"(he|she|they|it) (is|was) (being|getting) (really )?(special|nice|friendly|close) (to me|with me) but", re.I),
+    re.compile(r"(sexual|sexually) (abused?|assault(ed)?|exploit(ed)?|harass(ed)?)", re.I),
+    re.compile(r"abuse(d)? (me|my body|sexually)", re.I),
+    # Euphemistic disclosures — simplified to catch the span that matters
+    re.compile(r"(a grown.?up|an adult|someone older) (did|does|made|makes) (something|things?) (to me|with me)", re.I),
+    re.compile(r"(he|she|they) (made|make|asked|ask|told|tell) me (to )?(do|touch|show) (something|things?|myself|them)", re.I),
+)]
+
+# ── C: secrecy_request (HIGH) ────────────────────────────────────────────────
+# Patterns where the child tries to enlist the AI in keeping secrets from parents.
+# Also covers disclosure that another adult has demanded secrecy.
+_SECRECY_REQUEST_PATTERNS: list[re.Pattern[str]] = [p for p in (
+    re.compile(r"(don'?t|do not|please don'?t) (tell|let|show) (my )?(mum|mom|mummy|mommy|dad|daddy|father|mother|parent|carer|guardian|teacher|anyone|grown.?up)", re.I),
+    re.compile(r"(keep|kept) (this |it )?(a )?secret (from|between)", re.I),
+    re.compile(r"(it'?s|this is) (just )?our secret", re.I),
+    re.compile(r"(promise|swear) (me )?(you )?(won'?t|never|not) tell", re.I),
+    re.compile(r"(he|she|they) (told|said|told me|says) (not to|to never|to not) tell (anyone|anyone|my mum|my mom|my dad|my parent)", re.I),
+    re.compile(r"(told|said|asked) me (not|never) to (say|tell|talk about) (anything|this|it)", re.I),
+    re.compile(r"(nobody|no one|don'?t let anyone) (must|should|can) know (about this|about it)", re.I),
+)]
+
+# ── D: adversarial_jailbreak (LOW) ───────────────────────────────────────────
+# Patterns for jailbreak / safety-override attempts (Layer 1 §1.4 already blocks
+# inline; this class ensures they reach the escalation log for audit).
+_ADVERSARIAL_JAILBREAK_PATTERNS: list[re.Pattern[str]] = [p for p in (
+    re.compile(r"(ignore|disregard|forget|bypass|override) (your |all )?(previous |your |the )?(instructions?|rules?|guidelines?|safety|system prompt|restrictions?)", re.I),
+    re.compile(r"(pretend|act|behave|imagine) (like |as if )?(you (are|have) no |you don'?t have |you'?re |you are )(a different|rules?|restrictions?|guidelines?|an? (uncensored|unrestricted|free|evil|jailbroken))", re.I),
+    re.compile(r"(you are now|you'?re now|from now on (you are|you'?re|act as)) (a |an )?(?!a tutor|helping|assisting)", re.I),
+    re.compile(r"(jailbreak|dan mode|developer mode|god mode|unrestricted mode)", re.I),
+    re.compile(r"(your new (instructions?|rules?|system prompt)|new system prompt)", re.I),
+    re.compile(r"(pretend you have no rules|pretend you'?re a different ai|pretend (there are|you have) no (rules|restrictions|limits?))", re.I),
+    re.compile(r"(do anything now|say anything|no (rules|limits?|restrictions?))\b", re.I),
+)]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Severity + ordering table  (design §2 — precedence: A > B > C > D)
+# ─────────────────────────────────────────────────────────────────────────────
+
+# List of (TriggerClass, Severity, patterns) in descending priority order.
+# For ties in severity, the order here decides (A critical > A critical again,
+# then B high > C high; D low is last).
+_CLASSIFIER_BANKS: list[tuple[TriggerClass, Severity, list[re.Pattern[str]]]] = [
+    (TriggerClass.HARM_TO_SELF,          Severity.CRITICAL, _HARM_TO_SELF_PATTERNS),
+    (TriggerClass.PHYSICAL_DANGER,        Severity.CRITICAL, _PHYSICAL_DANGER_PATTERNS),
+    (TriggerClass.ABUSE_DISCLOSURE,       Severity.CRITICAL, _ABUSE_DISCLOSURE_PATTERNS),
+    (TriggerClass.SEVERE_DISTRESS,        Severity.HIGH,     _SEVERE_DISTRESS_PATTERNS),
+    (TriggerClass.SECRECY_REQUEST,        Severity.HIGH,     _SECRECY_REQUEST_PATTERNS),
+    (TriggerClass.ADVERSARIAL_JAILBREAK,  Severity.LOW,      _ADVERSARIAL_JAILBREAK_PATTERNS),
+]
+
+# Severity rank for precedence comparison (higher = higher priority).
+_SEVERITY_RANK: dict[Severity, int] = {
+    Severity.CRITICAL: 3,
+    Severity.HIGH:     2,
+    Severity.LOW:      1,
+}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Classifier (design §3)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def classify(text: str) -> Optional[TriggerMatch]:
+    """Single-turn classifier. Returns the HIGHEST-severity match, or None.
+
+    Sensitivity-biased: when in doubt, fire. False positives are acceptable and
+    expected (SAFETY.md §3.2); false negatives are not.
+
+    Precedence on multiple matches: highest Severity wins; ties broken by the
+    category order A > B > C > D (i.e., the order in _CLASSIFIER_BANKS).
+    The list is already sorted in descending priority so the first higher-or-
+    equal severity match found in a linear scan is returned.
+    """
+    if not text or not text.strip():
+        return None
+
+    best: Optional[TriggerMatch] = None
+
+    for trigger_class, severity, patterns in _CLASSIFIER_BANKS:
+        # Early exit: nothing can beat a CRITICAL already found, and the banks
+        # are ordered so subsequent banks are equal-or-lower severity.
+        if best is not None and _SEVERITY_RANK[severity] < _SEVERITY_RANK[best.severity]:
+            break
+
+        for pattern in patterns:
+            m = pattern.search(text)
+            if m:
+                candidate = TriggerMatch(
+                    trigger_class=trigger_class,
+                    severity=severity,
+                    matched_span=m.group(0),
+                )
+                if best is None or _SEVERITY_RANK[severity] > _SEVERITY_RANK[best.severity]:
+                    best = candidate
+                break  # one match per class is sufficient; move to next class
+
+    return best
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Thin caller helper — demonstrates the §4 flow end-to-end
+# (classify stays pure/separate; this is the caller side)
+# ─────────────────────────────────────────────────────────────────────────────
+
+def handle_trigger(
+    text: str,
+    learner_id: int,
+    conn: sqlite3.Connection,
+) -> Optional[TriggerMatch]:
+    """Run the §4 flow for one child turn against a live SQLite connection.
+
+    Returns the TriggerMatch if triggered (caller should enter ESCALATION_FREEZE
+    for all classes except adversarial_jailbreak per §4.3), or None if no match.
+
+    Steps performed (design §4):
+      1. classify() — pure; no side effects.
+      2. LOG — insert escalation_log row with full untruncated verbatim text.
+         For adversarial_jailbreak: session_outcome='logged_only' (design §4.3).
+         For all others: session_outcome='frozen'.
+      3. HANDOFF — render HANDOFF_MESSAGE_PRIMARY + _SUPPORT (returned in log
+         row comment; caller is responsible for display).
+      4. ALERT — on-screen flag + log row (pilot: log row already written above;
+         alert carries trigger_class only, NOT verbatim text per §4 Step 4).
+      FREEZE + WAIT + RESUMPTION GATE are FSM responsibilities (not this helper).
+
+    Note: adversarial_jailbreak is logged_only — do NOT enter ESCALATION_FREEZE.
+    """
+    match = classify(text)
+    if match is None:
+        return None
+
+    # §4.3 — adversarial_jailbreak is logged-only, not frozen
+    if match.trigger_class == TriggerClass.ADVERSARIAL_JAILBREAK:
+        session_outcome = "logged_only"
+    else:
+        session_outcome = "frozen"
+
+    # §4 Step 2 — LOG: full verbatim text, never truncated
+    conn.execute(
+        """
+        INSERT INTO escalation_log
+            (learner_id, trigger_class, trigger_text_verbatim, session_outcome)
+        VALUES (?, ?, ?, ?)
+        """,
+        (learner_id, match.trigger_class.value, text, session_outcome),
+    )
+    conn.commit()
+
+    # §4 Step 3 — HANDOFF (caller renders these; we return the match so caller knows)
+    # §4 Step 4 — ALERT: the log row IS the pilot alert (on-screen flag in parent view)
+    #             The alert surfaces trigger_class + timestamp ONLY — never verbatim text.
+
+    return match

mentar/tools/__init__.py

@@ -0,0 +1,4 @@
+"""CLI utilities: template validator, eval harness driver, etc.
+
+Tests: T3.1 (validator).
+"""