mentar 0.1.0.dev0__py3-none-any.whl

mentar/__init__.py

@@ -0,0 +1,6 @@
+"""Mentar — OSS-first, local-first AI tutor for children.
+
+See docs/SPEC.md for the project specification and docs/ARCHITECTURE.md for module layout.
+"""
+
+__version__ = "0.1.0.dev0"

mentar/cli/__init__.py

@@ -0,0 +1 @@
+"""Mentar CLI entry: `mentar serve`, `mentar eval`, `mentar validate-template`."""

mentar/cli/__main__.py

@@ -0,0 +1,62 @@
+"""CLI entry point. Wired in pyproject.toml [project.scripts].
+
+Subcommands:
+  serve            — Start a pilot tutoring session (stub).
+  eval             — Run the eval harness (stub).
+  validate-template — Validate a curriculum template against the W3.1 schema.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="mentar")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("serve", help="Start a pilot tutoring session (stub).")
+    sub.add_parser("eval", help="Run the eval harness (stub).")
+    vt = sub.add_parser(
+        "validate-template",
+        help="Validate a curriculum template against the W3.1 schema.",
+    )
+    vt.add_argument("path", help="Path to curriculum template Markdown file.")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "validate-template":
+        from mentar.tools.validate_template import validate
+
+        result = validate(args.path)
+
+        for w in result.warnings:
+            print(f"WARNING: {w}", file=sys.stderr)
+
+        for e in result.errors:
+            print(f"ERROR: {e}", file=sys.stderr)
+
+        if result.ok:
+            n = len(result.concept_ids)
+            print(
+                f"OK: {args.path} — {n} concept(s); "
+                f"roots={result.roots}; leaves={result.leaves}",
+                file=sys.stdout,
+            )
+            if result.warnings:
+                print(f"  {len(result.warnings)} warning(s) — see stderr.", file=sys.stdout)
+        else:
+            print(
+                f"FAIL: {args.path} — {len(result.errors)} error(s).",
+                file=sys.stdout,
+            )
+
+        return 0 if result.ok else 1
+
+    # stubs
+    print(f"mentar: '{args.cmd}' not implemented yet (stub).", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mentar/db/__init__.py

@@ -0,0 +1,4 @@
+"""Local SQLite store: learner profile, BKT state, response log, Help/probe/escalation events, transcripts.
+
+Spec: docs/PHASE0.md W3.6; tests: T3.6.
+"""

mentar/db/store.py

@@ -0,0 +1,416 @@
+"""LearnerStore — minimal SQLite wrapper for Mentar learner data.
+
+Spec: docs/PHASE0.md W3.6
+Safety: docs/SAFETY.md Layer 4 (data/privacy), Layer 5 (parental oversight)
+Tests: tests/db/test_datamodel.py (T3.6)
+
+Design notes:
+- Stdlib sqlite3 only; no ORM.
+- Row factory = sqlite3.Row (dict-like access by column name).
+- All queries are parameterised; no string interpolation.
+- Schema applied from schema.sql on first open (user_version == 0).
+- user_version == 1 after schema applied; future migrations bump this.
+- Transcript immutability is enforced by DB triggers; this layer does not
+  add a second guard — the trigger is the authority.
+- Multi-learner namespacing: every write method accepts learner_id and
+  every read method filters by learner_id.  Never query without it.
+- export/backup = file copy at OS level; call close() first so WAL is
+  checkpointed (see export note below).
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Union
+
+# Path to the schema DDL file alongside this module.
+_SCHEMA_PATH = Path(__file__).parent / "schema.sql"
+
+_EXPECTED_VERSION = 1
+
+
+class LearnerStore:
+    """Local SQLite store for one Mentar installation (one .db file per device).
+
+    Multi-learner support is achieved via the learner_id column present on
+    every table — each method scopes queries to a single learner.
+
+    Thread safety: sqlite3 connections are NOT thread-safe by default.
+    For the pilot (single-process, single-thread) this is fine.  A future
+    multi-threaded web tier would need one connection per thread or a pool.
+    """
+
+    def __init__(self, db_path: Union[str, Path]) -> None:
+        """Open (or create) the SQLite database at *db_path*.
+
+        If the database is new (user_version == 0), the schema DDL in
+        schema.sql is applied and user_version is set to 1.
+        """
+        self._path = Path(db_path)
+        self._conn = sqlite3.connect(str(self._path))
+        self._conn.row_factory = sqlite3.Row
+        # Enable FK enforcement for this connection (must be per-connection).
+        self._conn.execute("PRAGMA foreign_keys = ON;")
+        self._apply_schema_if_needed()
+
+    # ── Schema management ────────────────────────────────────────────────────
+
+    def _apply_schema_if_needed(self) -> None:
+        """Apply schema.sql if the DB is uninitialised (user_version == 0)."""
+        version = self._user_version()
+        if version == 0:
+            ddl = _SCHEMA_PATH.read_text(encoding="utf-8")
+            self._conn.executescript(ddl)
+            self._conn.commit()
+        elif version < _EXPECTED_VERSION:
+            # Future migration hook: run incremental ALTER TABLE statements here,
+            # then bump user_version to _EXPECTED_VERSION.
+            # For now (schema v1 is the only version) this branch is unreachable.
+            raise RuntimeError(
+                f"Database schema version {version} is older than expected "
+                f"{_EXPECTED_VERSION}. Run the migration script."
+            )
+        # version == _EXPECTED_VERSION: nothing to do.
+
+    def _user_version(self) -> int:
+        row = self._conn.execute("PRAGMA user_version;").fetchone()
+        return int(row[0])
+
+    def schema_version(self) -> int:
+        """Return the current PRAGMA user_version of the database."""
+        return self._user_version()
+
+    # ── Learner profile ──────────────────────────────────────────────────────
+
+    def create_learner(
+        self,
+        name: str,
+        year_level: str,
+        country: str,
+        age_mode: str,
+    ) -> int:
+        """Insert a learner profile row and return the new learner_id (int)."""
+        cur = self._conn.execute(
+            """
+            INSERT INTO learner_profile (name, year_level, country, age_mode)
+            VALUES (?, ?, ?, ?)
+            """,
+            (name, year_level, country, age_mode),
+        )
+        self._conn.commit()
+        return cur.lastrowid  # type: ignore[return-value]
+
+    def get_learner(self, learner_id: int) -> sqlite3.Row | None:
+        """Return the learner_profile row for *learner_id*, or None."""
+        return self._conn.execute(
+            "SELECT * FROM learner_profile WHERE id = ?;",
+            (learner_id,),
+        ).fetchone()
+
+    # ── Session ──────────────────────────────────────────────────────────────
+
+    def create_session(self, learner_id: int, session_id: str) -> None:
+        """Insert a session row.  session_id is caller-supplied (e.g. UUID)."""
+        self._conn.execute(
+            "INSERT INTO session (id, learner_id) VALUES (?, ?);",
+            (session_id, learner_id),
+        )
+        self._conn.commit()
+
+    def end_session(self, learner_id: int, session_id: str, ended_reason: str) -> None:
+        """Mark a session as ended."""
+        self._conn.execute(
+            """
+            UPDATE session
+               SET ended_at = strftime('%Y-%m-%dT%H:%M:%SZ', 'now'),
+                   ended_reason = ?
+             WHERE id = ? AND learner_id = ?;
+            """,
+            (ended_reason, session_id, learner_id),
+        )
+        self._conn.commit()
+
+    def get_session(self, learner_id: int, session_id: str) -> sqlite3.Row | None:
+        """Return a session row, scoped to the given learner."""
+        return self._conn.execute(
+            "SELECT * FROM session WHERE id = ? AND learner_id = ?;",
+            (session_id, learner_id),
+        ).fetchone()
+
+    # ── Skill state ──────────────────────────────────────────────────────────
+
+    def update_skill_state(
+        self,
+        learner_id: int,
+        skill_id: str,
+        p_mastery: float,
+        priors_used: bool,
+    ) -> None:
+        """Upsert the BKT mastery estimate for one skill.
+
+        Only p_mastery and prior_mode are updated here because the BKT
+        parameters (p_guess, p_slip, p_learns, p_forgets) are set once at
+        cold-start from the priors table and not changed until the fitted
+        model supersedes them (W3.3: N >= 100 scored responses per skill).
+        """
+        self._conn.execute(
+            """
+            INSERT INTO skill_state (learner_id, skill_id, p_mastery, prior_mode,
+                                     updated_at)
+            VALUES (?, ?, ?, ?,
+                    strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+            ON CONFLICT (learner_id, skill_id) DO UPDATE
+               SET p_mastery  = excluded.p_mastery,
+                   prior_mode = excluded.prior_mode,
+                   updated_at = excluded.updated_at;
+            """,
+            (learner_id, skill_id, p_mastery, int(priors_used)),
+        )
+        self._conn.commit()
+
+    def get_skill_state(self, learner_id: int, skill_id: str) -> sqlite3.Row | None:
+        """Return the skill_state row for one (learner, skill) pair."""
+        return self._conn.execute(
+            "SELECT * FROM skill_state WHERE learner_id = ? AND skill_id = ?;",
+            (learner_id, skill_id),
+        ).fetchone()
+
+    def all_skill_states(self, learner_id: int) -> list[sqlite3.Row]:
+        """Return all skill_state rows for a learner."""
+        return self._conn.execute(
+            "SELECT * FROM skill_state WHERE learner_id = ? ORDER BY skill_id;",
+            (learner_id,),
+        ).fetchall()
+
+    # ── Response log ─────────────────────────────────────────────────────────
+
+    def write_response(
+        self,
+        learner_id: int,
+        session_id: str,
+        skill_id: str,
+        prompt_ref: str,
+        answer: str,
+        scored: int,
+        hinted: int,
+        check_result: str | None = None,
+    ) -> int:
+        """Insert a response_log row and return the new response id."""
+        cur = self._conn.execute(
+            """
+            INSERT INTO response_log
+                (learner_id, session_id, skill_id, prompt_ref, answer,
+                 scored, hinted, check_result)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?);
+            """,
+            (learner_id, session_id, skill_id, prompt_ref, answer,
+             scored, hinted, check_result),
+        )
+        self._conn.commit()
+        return cur.lastrowid  # type: ignore[return-value]
+
+    def session_responses(self, learner_id: int, session_id: str) -> list[dict]:
+        """Return all response_log rows for one (learner, session) pair as dicts."""
+        rows = self._conn.execute(
+            """
+            SELECT * FROM response_log
+             WHERE learner_id = ? AND session_id = ?
+             ORDER BY id;
+            """,
+            (learner_id, session_id),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ── Help events ──────────────────────────────────────────────────────────
+
+    def write_help_event(
+        self,
+        learner_id: int,
+        session_id: str,
+        skill_id: str,
+        modality: str,
+        response_log_id: int,
+    ) -> int:
+        """Insert a help_event row and return the new id."""
+        cur = self._conn.execute(
+            """
+            INSERT INTO help_event
+                (learner_id, session_id, skill_id, modality, response_log_id)
+            VALUES (?, ?, ?, ?, ?);
+            """,
+            (learner_id, session_id, skill_id, modality, response_log_id),
+        )
+        self._conn.commit()
+        return cur.lastrowid  # type: ignore[return-value]
+
+    def session_help_events(self, learner_id: int, session_id: str) -> list[dict]:
+        """Return all help_event rows for one (learner, session) pair as dicts."""
+        rows = self._conn.execute(
+            """
+            SELECT * FROM help_event
+             WHERE learner_id = ? AND session_id = ?
+             ORDER BY id;
+            """,
+            (learner_id, session_id),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ── Probe events ─────────────────────────────────────────────────────────
+
+    def write_probe_event(
+        self,
+        learner_id: int,
+        session_id: str,
+        skill_id: str,
+        response_log_id: int,
+        retry_response_log_id: int | None,
+        class_: str,
+    ) -> int:
+        """Insert a probe_event row and return the new id."""
+        cur = self._conn.execute(
+            """
+            INSERT INTO probe_event
+                (learner_id, session_id, skill_id, response_log_id,
+                 retry_response_log_id, class)
+            VALUES (?, ?, ?, ?, ?, ?);
+            """,
+            (learner_id, session_id, skill_id, response_log_id,
+             retry_response_log_id, class_),
+        )
+        self._conn.commit()
+        return cur.lastrowid  # type: ignore[return-value]
+
+    def session_probe_events(self, learner_id: int, session_id: str) -> list[dict]:
+        """Return all probe_event rows for one (learner, session) pair as dicts."""
+        rows = self._conn.execute(
+            """
+            SELECT * FROM probe_event
+             WHERE learner_id = ? AND session_id = ?
+             ORDER BY id;
+            """,
+            (learner_id, session_id),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ── Escalation log ───────────────────────────────────────────────────────
+
+    def write_escalation(
+        self,
+        learner_id: int,
+        trigger_class: str,
+        trigger_text_verbatim: str,
+    ) -> int:
+        """Insert an escalation_log row and return the new id.
+
+        trigger_text_verbatim is stored exactly as received — never truncated
+        (SAFETY.md §3.3 Step 2: "never silently dropped").
+        """
+        cur = self._conn.execute(
+            """
+            INSERT INTO escalation_log
+                (learner_id, trigger_class, trigger_text_verbatim)
+            VALUES (?, ?, ?);
+            """,
+            (learner_id, trigger_class, trigger_text_verbatim),
+        )
+        self._conn.commit()
+        return cur.lastrowid  # type: ignore[return-value]
+
+    def parent_ack_escalation(self, esc_id: int) -> None:
+        """Record the parent's acknowledgment of an escalation event."""
+        self._conn.execute(
+            """
+            UPDATE escalation_log
+               SET parent_ack_at    = strftime('%Y-%m-%dT%H:%M:%SZ', 'now'),
+                   session_outcome  = 'acknowledged'
+             WHERE id = ?;
+            """,
+            (esc_id,),
+        )
+        self._conn.commit()
+
+    def get_escalation(self, learner_id: int, esc_id: int) -> sqlite3.Row | None:
+        """Return one escalation_log row, scoped to learner."""
+        return self._conn.execute(
+            "SELECT * FROM escalation_log WHERE id = ? AND learner_id = ?;",
+            (esc_id, learner_id),
+        ).fetchone()
+
+    def learner_escalations(self, learner_id: int) -> list[dict]:
+        """Return all escalation_log rows for a learner as dicts."""
+        rows = self._conn.execute(
+            "SELECT * FROM escalation_log WHERE learner_id = ? ORDER BY id;",
+            (learner_id,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ── Transcript ───────────────────────────────────────────────────────────
+
+    def write_transcript(
+        self,
+        learner_id: int,
+        session_id: str,
+        turn_index: int,
+        role: str,
+        text: str,
+    ) -> int:
+        """Append one turn to the immutable transcript and return the new id.
+
+        Immutability is enforced by DB triggers (trg_transcript_no_update and
+        trg_transcript_no_delete in schema.sql) — attempts to UPDATE or DELETE
+        a transcript row raise sqlite3.OperationalError.
+        """
+        cur = self._conn.execute(
+            """
+            INSERT INTO transcript
+                (learner_id, session_id, turn_index, role, text)
+            VALUES (?, ?, ?, ?, ?);
+            """,
+            (learner_id, session_id, turn_index, role, text),
+        )
+        self._conn.commit()
+        return cur.lastrowid  # type: ignore[return-value]
+
+    def transcript_for_session(
+        self, learner_id: int, session_id: str
+    ) -> list[dict]:
+        """Return all transcript rows for one (learner, session) pair as dicts.
+
+        Ordered by turn_index ascending — safe for deterministic replay.
+        """
+        rows = self._conn.execute(
+            """
+            SELECT * FROM transcript
+             WHERE learner_id = ? AND session_id = ?
+             ORDER BY turn_index ASC;
+            """,
+            (learner_id, session_id),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ── Connection lifecycle ─────────────────────────────────────────────────
+
+    def checkpoint(self) -> None:
+        """Checkpoint the WAL so an OS file-copy produces a consistent snapshot.
+
+        Call this before shutil.copy2() / any file-level export.
+        PRAGMA wal_checkpoint(TRUNCATE) flushes and truncates the WAL file.
+        """
+        self._conn.execute("PRAGMA wal_checkpoint(TRUNCATE);")
+
+    def close(self) -> None:
+        """Checkpoint and close the connection.
+
+        After close() the .db file is safe to copy (export = file copy per W3.6).
+        """
+        self.checkpoint()
+        self._conn.close()
+
+    # ── Context manager support ──────────────────────────────────────────────
+
+    def __enter__(self) -> "LearnerStore":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()

mentar/dialogue/__init__.py

@@ -0,0 +1,4 @@
+"""Session controller, FSM, Help loop, probe trigger, prompt assembly.
+
+Spec: docs/SPEC.md §12-14; FSM: docs/SESSION_FSM.md (W6.1); tests: T3.7, T4.x, T5.x.
+"""

mentar/engine/__init__.py

@@ -0,0 +1,4 @@
+"""KST concept graph, BKT mastery, fringe selection, deterministic verifiers.
+
+Spec: docs/SPEC.md §10-11; tests: T3.2 (fringe), T3.3 (BKT), T3.5 (verifier).
+"""

mentar/engine/bkt.py

@@ -0,0 +1,99 @@
+"""BKT per-turn mastery update — cold-start priors + hinted-win discount.
+
+Spec: docs/SPEC.md §11 (Mastery / BKT), §13.2 (hinted-win); docs/design/W3.3_bkt.md.
+Tests: docs/TESTS.md T3.3.
+
+This is Mentar's own deterministic BKT recurrence (Corbett & Anderson 1995),
+used for the per-turn update in the session FSM `bkt_update` state. pyBKT is NOT
+called here: it cannot fit parameters from one learner's cold-start (W3.3), so it
+is reserved for OFFLINE parameter fitting post-pilot (N >= 100 scored responses
+per skill, flipping skill_state.prior_mode -> 0). See design doc §1.
+
+stdlib-only, pure, side-effect-free: the caller persists the result via
+store.update_skill_state(). No DB, no I/O, no RNG.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Initial mastery prior for a freshly-fringed concept (design §2). NOT 0.0:
+# at exactly 0, no correct answer can ever move mastery (0*(1-slip)/... == 0).
+P_L0 = 0.10
+
+# How much a hinted-correct answer is discounted, as a fraction of the gap to a
+# pure guess. 0.5 => guess_hinted is a coin-flip's worth of evidence (design §3.1).
+# Deliberately strong: over-crediting a hinted win is the dangerous direction.
+HINT_DISCOUNT = 0.5
+
+# Node-class defaults keyed by verifier.answer_type (design §2). Template
+# `bkt_priors:` overrides these per node.
+_CLASS_DEFAULTS = {
+    "mc4":     {"guess": 0.20, "slip": 0.10, "learns": 0.20, "forgets": 0.0},
+    "numeric": {"guess": 0.05, "slip": 0.10, "learns": 0.20, "forgets": 0.0},
+}
+# answer_type -> node class
+_NUMERIC_TYPES = frozenset({"int", "decimal", "fraction"})
+
+
+@dataclass(frozen=True)
+class BktParams:
+    """Per-skill BKT parameters. forgets is stored for forward-compat; unused in v0."""
+
+    guess: float
+    slip: float
+    learns: float
+    forgets: float = 0.0
+
+
+def params_for(answer_type: str, overrides: dict | None = None) -> BktParams:
+    """Resolve params for a node: template `bkt_priors:` override wins, else the
+    class default by answer_type (design §2). `mc4` -> MC default; int/decimal/
+    fraction -> numeric default."""
+    node_class = "mc4" if answer_type == "mc4" else (
+        "numeric" if answer_type in _NUMERIC_TYPES else None
+    )
+    if node_class is None:
+        raise ValueError(f"no BKT prior class for answer_type {answer_type!r}")
+    base = dict(_CLASS_DEFAULTS[node_class])
+    if overrides:
+        base.update({k: v for k, v in overrides.items() if k in base})
+    return BktParams(**base)
+
+
+def _posterior_given_obs(p: float, correct: bool, guess: float, slip: float) -> float:
+    """Bayesian conditioning of mastery on one observation (design §3 step a)."""
+    if correct:
+        num = p * (1.0 - slip)
+        den = num + (1.0 - p) * guess
+    else:
+        num = p * slip
+        den = num + (1.0 - p) * (1.0 - guess)
+    return num / den if den > 0.0 else p
+
+
+def bkt_update(
+    p_prior: float | None,
+    correct: bool,
+    hinted: bool,
+    params: BktParams,
+) -> float:
+    """Return the updated p_mastery after one scored observation.
+
+    p_prior is the current skill_state.p_mastery; pass None (or 0.0) for an
+    uninitialised skill -> seeded to P_L0 (design §2; regression guard for the
+    degenerate-zero bug).
+
+    Hinted-win discount (design §3.1): a *correct* answer after Help uses an
+    elevated guess, so it raises mastery strictly less than a cold correct. A
+    hinted *incorrect* uses the normal guess (we do not soften a wrong answer).
+    """
+    p = P_L0 if (p_prior is None or p_prior <= 0.0) else p_prior
+
+    guess_eff = params.guess
+    if correct and hinted:
+        guess_eff = params.guess + (1.0 - params.guess) * HINT_DISCOUNT
+
+    p_cond = _posterior_given_obs(p, correct, guess_eff, params.slip)
+    # learning transition (within-session; forgets unused in v0)
+    return p_cond + (1.0 - p_cond) * params.learns