mentar 0.1.0.dev0__tar.gz

mentar-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: mentar
+Version: 0.1.0.dev0
+Summary: OSS-first, local-first AI tutor for children — supplements school, never replaces it.
+Author: Mentar maintainers
+License: TBD
+Keywords: tutor,education,kids,oss,local-llm,kst,bkt
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pyBKT>=1.4
+Requires-Dist: libzim>=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: hypothesis>=6.100; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Provides-Extra: inference-ollama
+Requires-Dist: ollama>=0.3; extra == "inference-ollama"
+Provides-Extra: nas
+Requires-Dist: smbprotocol>=1.12; extra == "nas"
+
+# Mentar
+
+**OSS-first AI tutor for children that supplements — never replaces — school education.**
+
+Local LLM hosting. Curriculum-templated by country and year level. Built-in kid safety from day one.
+
+---
+
+## What it is
+
+Mentar is an open-source tutoring framework that lets parents run an AI tutor on their own hardware, with no data leaving the device and no per-seat API fees. The core is three components:
+
+- **Template engine** — Markdown curriculum files per country + year/grade level, used as learning guidelines. Community-extensible.
+- **Dialogue framework** — Scaffolds tutoring conversations within the bounds of the active curriculum template.
+- **Safety layer** — Content guardrails and age-mode logic baked in, not bolted on. This is the non-negotiable bar the project must clear to justify existing.
+
+---
+
+## How this is built — an honesty note
+
+Mentar is, candidly, **AI-built software**. The great majority of the code, tests, and docs in this
+repo are written by AI agents working under a human maintainer's direction, decisions, and review —
+**not hand-written by a person**. In that sense it is close to "vibe coding," even though it follows
+deliberate engineering discipline: spec-first design, test-driven development (150+ tests gating
+changes), design docs before code, versioned prompts, and code review. Those principles raise the
+quality bar — but they don't change that underlying fact, and we'd rather be upfront about it.
+
+What this means for you:
+
+- **The human makes the decisions** (scope, safety thresholds, model choices, architecture); the AI
+  executes and advises. Changes are test-gated and reviewed — but the author is AI.
+- **It has not had a professional, independent audit.** In particular, the **child-safety** code and
+  spec are AI-authored and reviewed by AI plus the maintainer — *not* by a qualified safeguarding,
+  security, or child-development professional. The safety spec's own rollout guards
+  ([`docs/SAFETY.md`](docs/SAFETY.md)) require that review **before** any use beyond a single,
+  supervised pilot.
+- Treat the project accordingly: carefully built and openly documented, but **not yet independently
+  verified**. Read the code, run the tests, and do not put it in front of a real child outside a
+  supervised pilot until the open safety items are closed.
+
+---
+
+## Why local-first
+
+Two reasons:
+
+1. **Privacy** — children's data never leaves the device. No operator collects it. This is also a major compliance advantage (see `compliance/`).
+2. **Cost** — no per-seat API fees. A parent with a capable laptop or homelab machine pays nothing to run inference.
+
+A paid hosted-inference tier (for non-technical parents) is a planned future bridge, but it carries its own heavier compliance obligations. The OSS local edition stays deliberately data-light by design.
+
+---
+
+## Architecture
+
+The codebase uses a Python **src-layout** (`src/mentar/`); specs and the safety spec live
+under `docs/` (not in a top-level `safety/`). See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
+for the authoritative layout.
+
+```
+mentar/
+├── curriculum/              # Markdown curriculum templates (concept graphs)
+│   ├── _template.md         # Authoring format for new curricula
+│   └── templates/
+│       └── _pilot/          # Phase-0 fractions pilot graph (more to follow)
+├── prompts/                 # Versioned prompt templates + prompts/README.md registry (W6.2)
+├── src/mentar/              # Python package (src-layout)
+│   ├── engine/              # Concept graph (KST), BKT mastery, fringe, probe classifier
+│   ├── dialogue/            # Turn-loop controller (session state machine)
+│   ├── safety/              # Safety-layer implementation (escalation, filters)
+│   ├── inference/           # LLM abstraction layer (swappable backends)
+│   ├── eval/                # Deterministic verifiers + model-eval harness
+│   ├── db/                  # Local SQLite store (schema + access)
+│   ├── tools/               # Template validator, etc.
+│   └── cli/                 # Command-line entry points
+├── tests/                   # Mirrors the src/ layout
+├── docs/                    # SPEC, PHASE0(+_STATUS), SAFETY, SESSION_FSM, ARCHITECTURE,
+│                            #   TESTS, CONTENT_LICENSES, PILOT_CONSENT, design/, research/
+├── compliance/              # Compliance coverage-status map (points back to docs/)
+└── eval/                    # Eval datasets/outputs (data is gitignored)
+```
+
+---
+
+## Curriculum templates
+
+Templates are simple Markdown files that define what topics a child at a given country + year level should be learning. They are **guidelines**, not scripts — the dialogue framework uses them to keep sessions on-topic and age-appropriate.
+
+Anyone can add a new country or year-level template. See `curriculum/_template.md` for the format.
+
+---
+
+## Safety
+
+Kid-safe content blocks and age-appropriate responses are non-negotiable and built in from the start. See [`docs/SAFETY.md`](docs/SAFETY.md) for the full 6-layer spec (implementation lives in `src/mentar/safety/`).
+
+Key commitments:
+- No dark patterns, no compulsive gamification mechanics (legal line under EU AI Act Article 5)
+- No emotion recognition or mood inference
+- Under-13: parent-mediated mode (parent in the loop, child never alone with AI)
+- 13+: more independent with parental oversight available
+- Hard block: model must never produce sexual content involving minors
+
+---
+
+## Compliance
+
+The OSS local edition is data-light by design, which removes most direct developer exposure under COPPA, GDPR-K, and similar frameworks. However, obligations are real and documented.
+
+See `compliance/README.md` for coverage status — what's mapped, what's incomplete, and where contributors can help.
+
+---
+
+## LLMs
+
+Mentar is designed to work with smaller OSS models suited to educational dialogue. Low hallucination is critical for a children's tutor. The inference layer is abstracted so users can swap models.
+
+Current evaluation status: see `docs/llm-compatibility.md`.
+
+Hardware requirements: see `docs/hardware-requirements.md`.
+
+---
+
+## Documentation
+
+Full index: **[`docs/README.md`](docs/README.md)**. Highlights:
+
+- **[Spec](docs/SPEC.md)** · **[Live status](docs/PHASE0_STATUS.md)** · **[Architecture](docs/ARCHITECTURE.md)**
+- **[Safety spec](docs/SAFETY.md)** (6-layer, non-negotiable) · **[Pilot consent](docs/PILOT_CONSENT.md)**
+- **[Session state machine](docs/SESSION_FSM.md)** · **[Test plan](docs/TESTS.md)**
+- Model evaluation — **[results, plain-language](docs/EVAL_RESULTS.md)** · **[roster & plan](docs/MODEL.md)** · **[eval tooling](eval/README.md)**
+- **[Content licences](docs/CONTENT_LICENSES.md)** · **[Compliance status](compliance/README.md)** · **[Config & grounding sources](config/README.md)**
+
+---
+
+## Contributing
+
+- Add or improve a curriculum template under `curriculum/templates/` (see `curriculum/_template.md` for the format)
+- Improve the safety spec in `docs/SAFETY.md`
+- Fill compliance gaps flagged in `compliance/README.md`
+- Test and document model compatibility in `docs/llm-compatibility.md`
+
+---
+
+## Status
+
+Early-stage, in active **Phase 0** (a single-subject fractions pilot). The architecture,
+safety spec, session state machine, learner data model, and core engine pieces (concept
+graph, BKT mastery, verifiers, escalation, prompt registry) are in place; the end-to-end
+dialogue loop and the local model evaluation are the next milestones. Live status tracker:
+[`docs/PHASE0_STATUS.md`](docs/PHASE0_STATUS.md).

mentar-0.1.0.dev0/README.md

@@ -0,0 +1,151 @@
+# Mentar
+
+**OSS-first AI tutor for children that supplements — never replaces — school education.**
+
+Local LLM hosting. Curriculum-templated by country and year level. Built-in kid safety from day one.
+
+---
+
+## What it is
+
+Mentar is an open-source tutoring framework that lets parents run an AI tutor on their own hardware, with no data leaving the device and no per-seat API fees. The core is three components:
+
+- **Template engine** — Markdown curriculum files per country + year/grade level, used as learning guidelines. Community-extensible.
+- **Dialogue framework** — Scaffolds tutoring conversations within the bounds of the active curriculum template.
+- **Safety layer** — Content guardrails and age-mode logic baked in, not bolted on. This is the non-negotiable bar the project must clear to justify existing.
+
+---
+
+## How this is built — an honesty note
+
+Mentar is, candidly, **AI-built software**. The great majority of the code, tests, and docs in this
+repo are written by AI agents working under a human maintainer's direction, decisions, and review —
+**not hand-written by a person**. In that sense it is close to "vibe coding," even though it follows
+deliberate engineering discipline: spec-first design, test-driven development (150+ tests gating
+changes), design docs before code, versioned prompts, and code review. Those principles raise the
+quality bar — but they don't change that underlying fact, and we'd rather be upfront about it.
+
+What this means for you:
+
+- **The human makes the decisions** (scope, safety thresholds, model choices, architecture); the AI
+  executes and advises. Changes are test-gated and reviewed — but the author is AI.
+- **It has not had a professional, independent audit.** In particular, the **child-safety** code and
+  spec are AI-authored and reviewed by AI plus the maintainer — *not* by a qualified safeguarding,
+  security, or child-development professional. The safety spec's own rollout guards
+  ([`docs/SAFETY.md`](docs/SAFETY.md)) require that review **before** any use beyond a single,
+  supervised pilot.
+- Treat the project accordingly: carefully built and openly documented, but **not yet independently
+  verified**. Read the code, run the tests, and do not put it in front of a real child outside a
+  supervised pilot until the open safety items are closed.
+
+---
+
+## Why local-first
+
+Two reasons:
+
+1. **Privacy** — children's data never leaves the device. No operator collects it. This is also a major compliance advantage (see `compliance/`).
+2. **Cost** — no per-seat API fees. A parent with a capable laptop or homelab machine pays nothing to run inference.
+
+A paid hosted-inference tier (for non-technical parents) is a planned future bridge, but it carries its own heavier compliance obligations. The OSS local edition stays deliberately data-light by design.
+
+---
+
+## Architecture
+
+The codebase uses a Python **src-layout** (`src/mentar/`); specs and the safety spec live
+under `docs/` (not in a top-level `safety/`). See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
+for the authoritative layout.
+
+```
+mentar/
+├── curriculum/              # Markdown curriculum templates (concept graphs)
+│   ├── _template.md         # Authoring format for new curricula
+│   └── templates/
+│       └── _pilot/          # Phase-0 fractions pilot graph (more to follow)
+├── prompts/                 # Versioned prompt templates + prompts/README.md registry (W6.2)
+├── src/mentar/              # Python package (src-layout)
+│   ├── engine/              # Concept graph (KST), BKT mastery, fringe, probe classifier
+│   ├── dialogue/            # Turn-loop controller (session state machine)
+│   ├── safety/              # Safety-layer implementation (escalation, filters)
+│   ├── inference/           # LLM abstraction layer (swappable backends)
+│   ├── eval/                # Deterministic verifiers + model-eval harness
+│   ├── db/                  # Local SQLite store (schema + access)
+│   ├── tools/               # Template validator, etc.
+│   └── cli/                 # Command-line entry points
+├── tests/                   # Mirrors the src/ layout
+├── docs/                    # SPEC, PHASE0(+_STATUS), SAFETY, SESSION_FSM, ARCHITECTURE,
+│                            #   TESTS, CONTENT_LICENSES, PILOT_CONSENT, design/, research/
+├── compliance/              # Compliance coverage-status map (points back to docs/)
+└── eval/                    # Eval datasets/outputs (data is gitignored)
+```
+
+---
+
+## Curriculum templates
+
+Templates are simple Markdown files that define what topics a child at a given country + year level should be learning. They are **guidelines**, not scripts — the dialogue framework uses them to keep sessions on-topic and age-appropriate.
+
+Anyone can add a new country or year-level template. See `curriculum/_template.md` for the format.
+
+---
+
+## Safety
+
+Kid-safe content blocks and age-appropriate responses are non-negotiable and built in from the start. See [`docs/SAFETY.md`](docs/SAFETY.md) for the full 6-layer spec (implementation lives in `src/mentar/safety/`).
+
+Key commitments:
+- No dark patterns, no compulsive gamification mechanics (legal line under EU AI Act Article 5)
+- No emotion recognition or mood inference
+- Under-13: parent-mediated mode (parent in the loop, child never alone with AI)
+- 13+: more independent with parental oversight available
+- Hard block: model must never produce sexual content involving minors
+
+---
+
+## Compliance
+
+The OSS local edition is data-light by design, which removes most direct developer exposure under COPPA, GDPR-K, and similar frameworks. However, obligations are real and documented.
+
+See `compliance/README.md` for coverage status — what's mapped, what's incomplete, and where contributors can help.
+
+---
+
+## LLMs
+
+Mentar is designed to work with smaller OSS models suited to educational dialogue. Low hallucination is critical for a children's tutor. The inference layer is abstracted so users can swap models.
+
+Current evaluation status: see `docs/llm-compatibility.md`.
+
+Hardware requirements: see `docs/hardware-requirements.md`.
+
+---
+
+## Documentation
+
+Full index: **[`docs/README.md`](docs/README.md)**. Highlights:
+
+- **[Spec](docs/SPEC.md)** · **[Live status](docs/PHASE0_STATUS.md)** · **[Architecture](docs/ARCHITECTURE.md)**
+- **[Safety spec](docs/SAFETY.md)** (6-layer, non-negotiable) · **[Pilot consent](docs/PILOT_CONSENT.md)**
+- **[Session state machine](docs/SESSION_FSM.md)** · **[Test plan](docs/TESTS.md)**
+- Model evaluation — **[results, plain-language](docs/EVAL_RESULTS.md)** · **[roster & plan](docs/MODEL.md)** · **[eval tooling](eval/README.md)**
+- **[Content licences](docs/CONTENT_LICENSES.md)** · **[Compliance status](compliance/README.md)** · **[Config & grounding sources](config/README.md)**
+
+---
+
+## Contributing
+
+- Add or improve a curriculum template under `curriculum/templates/` (see `curriculum/_template.md` for the format)
+- Improve the safety spec in `docs/SAFETY.md`
+- Fill compliance gaps flagged in `compliance/README.md`
+- Test and document model compatibility in `docs/llm-compatibility.md`
+
+---
+
+## Status
+
+Early-stage, in active **Phase 0** (a single-subject fractions pilot). The architecture,
+safety spec, session state machine, learner data model, and core engine pieces (concept
+graph, BKT mastery, verifiers, escalation, prompt registry) are in place; the end-to-end
+dialogue loop and the local model evaluation are the next milestones. Live status tracker:
+[`docs/PHASE0_STATUS.md`](docs/PHASE0_STATUS.md).

mentar-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mentar"
+version = "0.1.0.dev0"
+description = "OSS-first, local-first AI tutor for children — supplements school, never replaces it."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "TBD" }
+authors = [{ name = "Mentar maintainers" }]
+keywords = ["tutor", "education", "kids", "oss", "local-llm", "kst", "bkt"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Education",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Education",
+]
+
+dependencies = [
+  "pyyaml>=6.0",
+  "pyBKT>=1.4",
+  "libzim>=3.10",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=4.1",
+  "hypothesis>=6.100",
+  "ruff>=0.5",
+]
+inference-ollama = [
+  "ollama>=0.3",
+]
+nas = [
+  # SMB/Samba client for reading/downloading ZIMs from a NAS via smb:// URLs.
+  # Not needed when the share is mounted in the OS (libzim reads the mount directly).
+  "smbprotocol>=1.12",
+]
+
+[project.scripts]
+mentar = "mentar.cli.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mentar*"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = [
+  "-ra",
+  "--strict-markers",
+  "--strict-config",
+]
+markers = [
+  "llm: tests that require a live LLM backend (skipped on the build host; run on eval host)",
+  "slow: tests that take >5s",
+  "human_gated: tests that require a human action (consent, review, child session)",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = ["E501"]

mentar-0.1.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mentar-0.1.0.dev0/src/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-0.1.0.dev0/src/mentar/cli/__init__.py

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

mentar-0.1.0.dev0/src/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-0.1.0.dev0/src/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.
+"""