skillplay 1.1.1__py3-none-any.whl

skillplay/__init__.py

@@ -0,0 +1,3 @@
+"""skillplay — learn-by-play TUI for dev skills."""
+
+__all__ = []

skillplay/__main__.py

@@ -0,0 +1,24 @@
+import sys
+
+from .core import cli
+
+
+def main() -> None:
+    # Bare `skillplay` (no args) launches the TUI; subcommands run the CLI.
+    if len(sys.argv) > 1:
+        # `skillplay exam --skill X` is a TUI subcommand — handled here so it can
+        # launch the app directly into a mastery exam.
+        if sys.argv[1] == "exam":
+            raise SystemExit(cli.run_exam(sys.argv[2:]))
+        raise SystemExit(cli.run(sys.argv[1:]))
+    from .tui.app import SkillPlayApp
+
+    app = SkillPlayApp()
+    try:
+        app.run()
+    except KeyboardInterrupt:
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

skillplay/core/__init__.py

@@ -0,0 +1,39 @@
+"""Core data layer: loader, validators, progress, streak, engine."""
+
+from . import (
+    achievements,
+    cli,
+    config,
+    engine,
+    goals,
+    i18n,
+    leaderboard_server,
+    loader,
+    progress,
+    registry,
+    schema,
+    share,
+    sound,
+    streak,
+    telemetry,
+    validators,
+)
+
+__all__ = [
+    "achievements",
+    "cli",
+    "config",
+    "engine",
+    "goals",
+    "i18n",
+    "leaderboard_server",
+    "loader",
+    "progress",
+    "registry",
+    "schema",
+    "share",
+    "sound",
+    "streak",
+    "telemetry",
+    "validators",
+]

skillplay/core/achievements.py

@@ -0,0 +1,73 @@
+"""Achievement/badge definitions and awarding (P8).
+
+Achievements are pure functions over the progress document. `award` is called
+from `engine.finalize` and appends any newly-earned ids to `progress["achievements"]`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+
+def _total_completed(progress: dict) -> int:
+    return sum(len(s.get("completed_ids", [])) for s in progress.get("skills", {}).values())
+
+
+def _checkers() -> list[tuple[str, str, str, Callable[[dict], bool]]]:
+    def first_blood(p: dict) -> bool:
+        return _total_completed(p) >= 1
+
+    def streak_7(p: dict) -> bool:
+        return p.get("streak", {}).get("longest", 0) >= 7
+
+    def century(p: dict) -> bool:
+        return p.get("total_xp", 0) >= 100
+
+    def pack_complete(p: dict) -> bool:
+        from . import loader
+
+        for pack in loader.load_all_packs():
+            ids = {c.id for c in pack.challenges}
+            done = set(p.get("skills", {}).get(pack.skill, {}).get("completed_ids", []))
+            if ids and ids <= done:
+                return True
+        return False
+
+    def daily_5(p: dict) -> bool:
+        return len(p.get("daily", {}).get("dates", [])) >= 5
+
+    def combo_master(p: dict) -> bool:
+        # Reached via any session; we approximate using daily/weekly accuracy.
+        return p.get("total_xp", 0) >= 500
+
+    return [
+        ("first_blood", "First Blood", "Complete your first challenge.", first_blood),
+        ("streak_7", "Week Strong", "Keep a 7-day streak alive.", streak_7),
+        ("century", "Century", "Earn 100 total XP.", century),
+        ("pack_complete", "Pack Rat", "Finish every challenge in a pack.", pack_complete),
+        ("daily_5", "Daily Devotion", "Complete 5 daily challenges.", daily_5),
+        ("combo_master", "Combo Master", "Reach 500 total XP.", combo_master),
+    ]
+
+
+ACHIEVEMENTS: list[dict] = [{"id": i, "name": n, "description": d} for (i, n, d, _) in _checkers()]
+
+
+def award(progress: dict) -> list[str]:
+    """Append any newly-earned achievement ids; return the newly awarded list."""
+    earned = set(progress.get("achievements", []))
+    newly: list[str] = []
+    for aid, _name, _desc, check in _checkers():
+        if aid not in earned and check(progress):
+            earned.add(aid)
+            newly.append(aid)
+    if newly:
+        progress["achievements"] = sorted(earned)
+    return newly
+
+
+def by_id(aid: str) -> dict | None:
+    for a in ACHIEVEMENTS:
+        if a["id"] == aid:
+            return a
+    return None

skillplay/core/adaptive.py

@@ -0,0 +1,291 @@
+"""Section E — Adaptive engine v2: a tiny, offline-first local model.
+
+Trained purely on the player's own per-attempt history (``progress["attempts"]``),
+it predicts the probability a challenge will be solved correctly, then selects the
+*next-best* challenge: one the player is likely to get wrong but where practice
+still pays off (high expected learning gain). No data ever leaves the machine —
+the fitted weights live in ``progress["model"]`` and training happens locally on
+``finalize``.
+
+The model is a small logistic regression fit with batch gradient descent in pure
+Python (no numpy dependency). It is intentionally simple and bounded so it runs
+instantly and stays explainable.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from typing import Any
+
+from . import engine, skillgraph
+from . import progress as progress_mod
+from .loader import Challenge, Pack
+
+# Fixed feature order — must stay in sync with ``engine._attempt_features`` keys.
+_FEATURE_KEYS = ("difficulty", "box", "mistakes", "weak_share", "rolling", "seen", "latency")
+
+MIN_TRAIN_ATTEMPTS = 20
+MAX_TRAIN_ATTEMPTS = 5000
+MODEL_VERSION = 1
+# Only retrain once at least this many *new* attempts have accumulated, so
+# ``finalize`` stays cheap (G5: avoid re-fitting on every session save).
+RETRAIN_MIN_NEW = 10
+# How strongly the heuristic "drill the weakest mistake type" nudge is folded
+# into the model's learning-gain score (G4: keep retention behavior when the
+# model is active instead of silently dropping it).
+RETENTION_BONUS_WEIGHT = 0.03
+
+
+def _sigmoid(z: float) -> float:
+    if z >= 0:
+        ez = math.exp(-z)
+        return 1.0 / (1.0 + ez)
+    ez = math.exp(z)
+    return ez / (1.0 + ez)
+
+
+def _eval_auc(attempts: list[dict[str, Any]], model: AdaptiveModel) -> float | None:
+    """Cheap offline effectiveness check: rank-based AUC of P(correct) vs the
+    actual outcome (Mann-Whitney U, O(n log n)). 0.5 = no signal, 1.0 = perfect.
+    Returns None when there's only one class present."""
+    scores = []
+    for a in attempts:
+        if not a.get("feats"):
+            continue
+        y = 1.0 if a.get("correct") else 0.0
+        scores.append((y, model.predict_correct(a["feats"])))
+    if len(scores) < 2:
+        return None
+    scores.sort(key=lambda x: x[1])
+    n_neg = concordant = n_pos = 0
+    for y, _p in scores:
+        if y == 0:
+            n_neg += 1
+        else:
+            concordant += n_neg
+            n_pos += 1
+    if n_pos == 0 or n_neg == 0:
+        return None
+    return concordant / (n_pos * n_neg)
+
+
+def _retention_bonus(progress: dict[str, Any], ch) -> float:
+    """The heuristic's "drill the weakest mistake type" term (mirrors
+    ``engine._challenge_weight``) so the model path keeps the proven retention
+    behavior (G4). Zero for unseen/clean challenges."""
+    bonus = 0.0
+    dom = engine._dominant_mistake_type(progress, ch.id)
+    if dom is not None:
+        mt = progress.get("mistakes", {}).get(ch.id, {})
+        bonus += mt.get(dom, 0) * 2
+        if dom == engine._weakest_mistake_type(progress):
+            bonus += 3
+    return bonus
+
+
+class AdaptiveModel:
+    """A fitted logistic regressor over challenge features -> P(correct)."""
+
+    def __init__(
+        self, weights: dict[str, float] | None = None, bias: float = 0.0, trained_on: int = 0
+    ):
+        self.weights = weights or {k: 0.0 for k in _FEATURE_KEYS}
+        self.bias = bias
+        self.trained_on = trained_on
+
+    def predict_correct(self, feats: dict[str, float]) -> float:
+        z = self.bias
+        for k in _FEATURE_KEYS:
+            z += self.weights.get(k, 0.0) * feats.get(k, 0.0)
+        return _sigmoid(z)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"weights": dict(self.weights), "bias": self.bias, "trained_on": self.trained_on}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> AdaptiveModel:
+        return cls(d.get("weights", {}), d.get("bias", 0.0), d.get("trained_on", 0))
+
+
+def train_model(
+    attempts: list[dict[str, Any]], iters: int = 60, lr: float = 0.3
+) -> AdaptiveModel | None:
+    """Fit the logistic model on recorded attempts. Returns None if there is
+    not enough data to learn anything meaningful yet."""
+    samples = [a for a in attempts if isinstance(a, dict) and a.get("feats")]
+    if len(samples) < MIN_TRAIN_ATTEMPTS:
+        return None
+
+    feats_list = [a["feats"] for a in samples]
+    ys = [1.0 if a.get("correct") else 0.0 for a in samples]
+    w = {k: 0.0 for k in _FEATURE_KEYS}
+    b = 0.0
+    n = len(feats_list)
+    for _ in range(iters):
+        gw = {k: 0.0 for k in _FEATURE_KEYS}
+        gb = 0.0
+        for x, y in zip(feats_list, ys):
+            p = _sigmoid(b + sum(w[k] * x.get(k, 0.0) for k in _FEATURE_KEYS))
+            err = p - y
+            for k in _FEATURE_KEYS:
+                gw[k] += err * x.get(k, 0.0)
+            gb += err
+        for k in _FEATURE_KEYS:
+            w[k] -= lr * gw[k] / n
+        b -= lr * gb / n
+    return AdaptiveModel(w, b, len(samples))
+
+
+def retrain_if_needed(progress: dict[str, Any]) -> None:
+    """Fit (or refresh) the model from recent attempts and store it locally.
+
+    G5 hardening: the stored model carries a ``version`` so a format change can't
+    silently break old saves (``load_model`` rejects mismatches), and retraining is
+    throttled to at least ``RETRAIN_MIN_NEW`` new attempts so ``finalize`` stays
+    cheap. A held-out AUC is stored for visibility into model effectiveness.
+    """
+    total = len(progress.get("attempts", []))
+    if total < MIN_TRAIN_ATTEMPTS:
+        return
+    prev = progress.get("model") or {}
+    if (
+        prev.get("version") == MODEL_VERSION
+        and (total - prev.get("trained_on_count", 0)) < RETRAIN_MIN_NEW
+    ):
+        return  # already trained on (almost) all current data
+    attempts = progress["attempts"][-MAX_TRAIN_ATTEMPTS:]
+    model = train_model(attempts)
+    if model is None:
+        return
+    d = model.to_dict()
+    d["version"] = MODEL_VERSION
+    d["trained_on_count"] = total
+    d["eval_auc"] = _eval_auc(attempts, model)
+    progress["model"] = d
+
+
+def load_model(progress: dict[str, Any]) -> AdaptiveModel | None:
+    d = progress.get("model")
+    if not d or d.get("version") != MODEL_VERSION:
+        return None
+    model = AdaptiveModel.from_dict(d)
+    if model.trained_on < MIN_TRAIN_ATTEMPTS:
+        return None
+    return model
+
+
+def challenge_failure_prob(model: AdaptiveModel, progress: dict[str, Any], ch: Challenge) -> float:
+    """P(the player gets this challenge wrong) under the current model."""
+    feats = engine._attempt_features(progress, ch)
+    return 1.0 - model.predict_correct(feats)
+
+
+def adaptive_reason(p_fail: float) -> str:
+    pct = int(p_fail * 100)
+    if pct >= 60:
+        return f"Model: likely to slip ({pct}%) — high-value practice"
+    if pct >= 35:
+        return f"Model: worth drilling ({pct}%)"
+    return f"Model: probably fine ({pct}%) — light review"
+
+
+def next_best_challenge(
+    progress: dict[str, Any], pack: Pack, skill: str | None = None
+) -> Challenge | None:
+    """The single best challenge to practice next for a skill (model-driven)."""
+    model = load_model(progress)
+    candidates = pack.challenges
+    if skill:
+        candidates = [c for c in candidates if c.skill == skill]
+    if not candidates:
+        return None
+    if model is None:
+        # Not enough data yet — fall back to the proven heuristic weighting.
+        return max(candidates, key=lambda c: engine._challenge_weight(progress, c))
+    # V4: never target a challenge whose prerequisites aren't satisfied yet —
+    # the model walks the next unlockable frontier, not the weakest locked card.
+    unlocked = [c for c in candidates if skillgraph.is_unlocked(progress, c)]
+    candidates = unlocked or candidates
+    # Higher failure probability = better practice target; the retention bonus
+    # preserves the heuristic's "drill the weakest mistake type" nudge (G4).
+    ranked = sorted(
+        candidates,
+        key=lambda c: (
+            challenge_failure_prob(model, progress, c)
+            + RETENTION_BONUS_WEIGHT * _retention_bonus(progress, c)
+        ),
+        reverse=True,
+    )
+    return ranked[0]
+
+
+def select_adaptive_v2(
+    pack: Pack, progress: dict[str, Any], session_size: int, model: AdaptiveModel | None = None
+) -> list:
+    """Pick a session of challenges using the trained model.
+
+    Falls back to the classic weighted sampler when the model isn't trained yet,
+    so early players get the same good experience as before.
+    """
+    model = model or load_model(progress)
+    if model is None:
+        return engine.select_challenges(pack, progress, session_size)
+
+    today = progress_mod.today_str()
+    due = []
+    for ch in pack.challenges:
+        rec = progress["challenges"].get(ch.id, {})
+        next_due = rec.get("next_due", "")
+        if next_due and next_due > today:
+            continue
+        due.append(ch)
+    if not due:
+        due = list(pack.challenges)
+
+    # V4: respect prerequisites — only model-rank the unlocked frontier so the
+    # adaptive session never schedules a card the player isn't ready for.
+    due = engine._gate_prerequisites(due, progress)
+
+    # Expected learning gain: likely-to-fail * difficulty value, plus the
+    # heuristic retention nudge so the model path keeps drilling the player's
+    # weakest mistake type instead of dropping it (G4).
+    scored = []
+    for ch in due:
+        p_fail = challenge_failure_prob(model, progress, ch)
+        gain = p_fail * (0.5 + getattr(ch, "difficulty", 1) / 10.0)
+        gain += RETENTION_BONUS_WEIGHT * _retention_bonus(progress, ch)
+        scored.append((gain, ch))
+    scored.sort(key=lambda t: t[0], reverse=True)
+
+    # Weighted sample without replacement among the strongest contenders, with
+    # a little exploration noise so sessions don't become perfectly repetitive.
+    top = scored[: max(session_size, min(len(scored), session_size * 3))]
+    pool = [c for _, c in top]
+    weights = [max(1, int(g * 100)) for g, _ in top]
+    chosen: list = []
+    pp, pw = list(pool), list(weights)
+    while pp and len(chosen) < session_size:
+        pick = random.choices(pp, weights=pw, k=1)[0]
+        idx = pp.index(pick)
+        chosen.append(pp.pop(idx))
+        pw.pop(idx)
+    for ch in chosen:
+        ch.srs_reason = adaptive_reason(challenge_failure_prob(model, progress, ch))
+    return chosen
+
+
+def select_adaptive_v2_pack(packs: list[Pack], progress: dict[str, Any], session_size: int) -> list:
+    """Like ``select_mixed`` but scored by the adaptive model across all packs."""
+    all_ch = [c for p in packs for c in p.challenges]
+    synth = Pack(
+        id="adaptive",
+        name="Adaptive",
+        version="0.0.0",
+        skill="mixed",
+        description="Model-selected challenges across all your skills.",
+        difficulty="mixed",
+        author="core",
+        challenges=all_ch,
+    )
+    return select_adaptive_v2(synth, progress, session_size)

skillplay/core/capstone.py

@@ -0,0 +1,140 @@
+"""V2 - Project / capstone mode (W1): session practice -> portfolio outcomes.
+
+A capstone pack is a chain of challenges (ordered by the V4 prerequisite DAG)
+that together build a single real artifact - a small CLI, a module, a tiny API.
+As the player solves the code-producing challenges, their own correct solutions
+are stitched together into a runnable file saved under the portfolio directory,
+so a learning session leaves behind something tangible.
+
+All functions here are pure except `build_artifact`, which writes the artifact
+file and updates `progress["portfolio"]` in memory (the caller persists, per the
+engine's save invariant).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from . import progress as progress_mod
+from .loader import Pack
+
+# Validation modes whose answer is code we can assemble into an artifact.
+_CODE_MODES = ("test_cases", "freeform")
+
+
+def is_capstone(pack: Pack) -> bool:
+    return bool(getattr(pack, "capstone", False))
+
+
+def capstone_packs(packs: list[Pack]) -> list[Pack]:
+    return [p for p in packs if is_capstone(p)]
+
+
+def _topo_order(pack: Pack) -> list:
+    """Order the pack's challenges so prerequisites come before dependents (Kahn).
+    Cross-pack prerequisites are ignored for ordering (placed at the end)."""
+    by_id = {c.id: c for c in pack.challenges}
+    indeg = {c.id: 0 for c in pack.challenges}
+    adj: dict[str, list[str]] = {c.id: [] for c in pack.challenges}
+    for c in pack.challenges:
+        for pid in getattr(c, "prerequisites", None) or []:
+            if pid in by_id:
+                adj[pid].append(c.id)
+                indeg[c.id] += 1
+    queue = [cid for cid, d in indeg.items() if d == 0]
+    order: list[str] = []
+    while queue:
+        n = queue.pop(0)
+        order.append(n)
+        for m in adj[n]:
+            indeg[m] -= 1
+            if indeg[m] == 0:
+                queue.append(m)
+    for cid in by_id:  # safety: append any leftovers (should be none - DAG-checked)
+        if cid not in order:
+            order.append(cid)
+    return [by_id[cid] for cid in order]
+
+
+def code_challenges(pack: Pack) -> list:
+    return [c for c in _topo_order(pack) if c.validation.get("mode") in _CODE_MODES]
+
+
+def _solution_for(progress: dict[str, Any], ch) -> str:
+    """The player's own correct code if recorded, else the reference solution."""
+    sol = progress.get("solutions", {}).get(ch.id)
+    if sol:
+        return sol
+    return (ch.answer.get("reference_code") or "").strip()
+
+
+def capstone_progress(progress: dict[str, Any], pack: Pack) -> dict[str, int]:
+    """Summary for the UI: how many code challenges solved and if built."""
+    code = code_challenges(pack)
+    solved = sum(1 for c in code if c.id in progress.get("solutions", {}))
+    built = 1 if progress.get("portfolio", {}).get(pack.id) else 0
+    return {"total": len(code), "solved": solved, "built": built}
+
+
+def _ensure_guard(code: str, lang: str) -> str:
+    """For python artifacts, ensure a defined `main` is actually invoked."""
+    if lang != "python":
+        return code
+    if "def main(" not in code:
+        return code
+    if 'if __name__ == "__main__"' in code or "if __name__ == '__main__'" in code:
+        return code
+    return code + '\n\nif __name__ == "__main__":\n    main()\n'
+
+
+def build_artifact(
+    progress: dict[str, Any], pack: Pack, data_dir: Path | None = None
+) -> dict[str, Any]:
+    """Assemble the capstone's code challenges (in prerequisite order) into one
+    artifact file under `<data_dir>/portfolio/<filename>`.
+
+    Uses the player's own correct solutions where available, falling back to each
+    challenge's reference code so the artifact is always buildable. Returns a
+    result dict; side effects are limited to writing the file and updating
+    `progress["portfolio"][pack.id]` in memory (caller persists).
+    """
+    data_dir = data_dir or progress_mod.DATA_DIR
+    artifact = getattr(pack, "artifact", {}) or {}
+    filename = artifact.get("filename") or f"{pack.id}.py"
+    lang = artifact.get("lang", "python")
+    code_chs = code_challenges(pack)
+
+    parts: list[str] = [f"# {pack.name} - assembled skillplay capstone artifact"]
+    solved = 0
+    for ch in code_chs:
+        sol = _solution_for(progress, ch)
+        if not sol:
+            continue
+        if ch.id in progress.get("solutions", {}):
+            solved += 1
+        parts.append(f"\n# --- {ch.id}: {ch.title} ---\n{sol}")
+    body = "\n".join(parts) + "\n"
+    body = _ensure_guard(body, lang)
+
+    out_dir = Path(data_dir) / "portfolio"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    path = out_dir / filename
+    path.write_text(body, encoding="utf-8")
+
+    progress.setdefault("portfolio", {})[pack.id] = {
+        "path": str(path),
+        "filename": filename,
+        "built": progress_mod.today_str(),
+        "solved": solved,
+        "total": len(code_chs),
+    }
+    return {
+        "ok": True,
+        "path": str(path),
+        "filename": filename,
+        "lang": lang,
+        "solved": solved,
+        "total": len(code_chs),
+        "code": body,
+    }