Upload 4 files

recommendation/features.py

@@ -0,0 +1,239 @@
+"""
+Shared feature engineering.
+
+CRITICAL: this module is imported by BOTH generate_data.py (to build training
+rows) and ml_policy.py (to build live scoring rows). Using the exact same
+functions in both places is what guarantees train/serve parity for
+`current_level_*`, rolling stats, the estimated-ability proxy, etc.
+
+No function here ever reads Child.ability, Child.learning_rate, or
+Child.fatigue_factor (the hidden simulator ground truth). Everything is
+derived from observable history only.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+import numpy as np
+import pandas as pd
+
+from recommendation.simulator import (
+    CATEGORIES,
+    CATEGORY_METRIC,
+    DIFFICULTY_B,
+    DISCRIMINATION_EASY,
+    GAME_BY_CATEGORY,
+    GAME_IDS,
+    GAMES,
+    ROLLING_WINDOWS,
+    Child,
+    logit,
+)
+
+# ---------------------------------------------------------------------------
+# Rolling / history helpers
+# ---------------------------------------------------------------------------
+
+
+def _metric_key(category: str) -> str:
+    return "accuracy_score" if CATEGORY_METRIC[category] == "accuracy" else "efficiency_score"
+
+
+def rolling_values(history, category, n):
+    key = _metric_key(category)
+    vals = [r[key] for r in history if r["game_category"] == category and pd.notna(r[key])]
+    return vals[-n:]
+
+
+def rolling_mean(history, category, n):
+    vals = rolling_values(history, category, n)
+    return float(np.mean(vals)) if vals else np.nan
+
+
+def rolling_std(history, category, n):
+    vals = rolling_values(history, category, n)
+    return float(np.std(vals)) if len(vals) >= 2 else np.nan
+
+
+def rolling_mean_by_game(history, game_id, n):
+    cfg = GAMES[game_id]
+    key = "accuracy_score" if cfg["metric"] == "accuracy" else "efficiency_score"
+    vals = [r[key] for r in history if r["game_id"] == game_id and pd.notna(r[key])]
+    vals = vals[-n:]
+    return float(np.mean(vals)) if vals else np.nan
+
+
+def weakest_category(history, excluded: set) -> str:
+    eligible = [c for c in CATEGORIES if c not in excluded] or list(CATEGORIES)
+    scores = {}
+    for c in eligible:
+        m = rolling_mean(history, c, 5)
+        scores[c] = m if not np.isnan(m) else -1.0
+    return min(scores, key=scores.get)
+
+
+def pick_game_in_category(history, category) -> str:
+    candidates = GAME_BY_CATEGORY[category]
+    if len(candidates) == 1:
+        return candidates[0]
+
+    def game_score(gid):
+        v = rolling_mean_by_game(history, gid, 5)
+        return v if not np.isnan(v) else -1.0
+
+    return min(candidates, key=game_score)
+
+
+# ---------------------------------------------------------------------------
+# Estimated ability (observable proxy for hidden theta — NOT ground truth)
+# ---------------------------------------------------------------------------
+
+
+def estimate_theta(history, category) -> float:
+    """
+    Statistical point estimate of the child's theta in `category`, derived
+    only from observed (difficulty, score) pairs in history. Uses a simple
+    inverse-IRT approximation (assumes the "easy" discrimination constant,
+    which is an approximation but a reasonable, stable proxy — this is a
+    feature, not a claim of ground truth).
+
+    Falls back to 0.0 (== ability 0.5) when there is no history yet.
+    """
+    metric = CATEGORY_METRIC[category]
+    key = "accuracy_score" if metric == "accuracy" else "efficiency_score"
+    obs = [
+        (r["difficulty"], r[key])
+        for r in history
+        if r["game_category"] == category and pd.notna(r[key])
+    ]
+    obs = obs[-10:]  # recency-weighted via truncation, simple and stable
+    if not obs:
+        return 0.0
+    thetas = []
+    for difficulty, score in obs:
+        b = DIFFICULTY_B[difficulty]
+        thetas.append(b + logit(score) / DISCRIMINATION_EASY)
+    return float(np.mean(thetas))
+
+
+# ---------------------------------------------------------------------------
+# Learner-state (context) features — identical across all candidates for a
+# given decision point.
+# ---------------------------------------------------------------------------
+
+
+def build_learner_context(child: Child, timestamp: datetime) -> dict:
+    feats = {
+        "age": child.age,
+        "plays_in_session": child.plays_in_session,
+        "is_onboarding": int(bool(child.onboarding_queue)),
+        "last_game_category": (child.history[-1]["game_category"] if child.history else "none"),
+    }
+
+    for gid in GAME_IDS:
+        idx = child.game_last_index.get(gid)
+        feats[f"games_since_played_{gid}"] = (
+            child.games_played_count - idx if idx is not None else np.nan
+        )
+
+    for cat in CATEGORIES:
+        idx = child.category_last_index.get(cat)
+        since_played = child.games_played_count - idx if idx is not None else np.nan
+        feats[f"category_since_played_{cat}"] = since_played
+        feats[f"is_first_play_{cat}"] = int(idx is None)
+
+        for n in ROLLING_WINDOWS:
+            feats[f"rolling_{cat}_last{n}"] = rolling_mean(child.history, cat, n)
+
+        feats[f"rolling_std_{cat}_last5"] = rolling_std(child.history, cat, 5)
+        last3 = feats[f"rolling_{cat}_last3"]
+        last10 = feats[f"rolling_{cat}_last10"]
+        feats[f"trend_{cat}"] = (
+            last3 - last10 if not (np.isnan(last3) or np.isnan(last10)) else 0.0
+        )
+
+        feats[f"sessions_played_{cat}"] = len(child.category_sessions_played[cat])
+
+        last_ts = child.category_last_ts.get(cat)
+        feats[f"days_since_last_played_{cat}"] = (
+            (timestamp - last_ts).total_seconds() / 86400.0 if last_ts is not None else np.nan
+        )
+
+        feats[f"current_level_{cat}"] = child.category_level[cat]
+        feats[f"estimated_theta_{cat}"] = estimate_theta(child.history, cat)
+
+    return feats
+
+
+# ---------------------------------------------------------------------------
+# Candidate-action + interaction features
+# ---------------------------------------------------------------------------
+
+
+def build_candidate_row(learner_ctx: dict, game_id: str, difficulty: int) -> dict:
+    cfg = GAMES[game_id]
+    category = cfg["category"]
+    b = DIFFICULTY_B[difficulty]
+    est_theta = learner_ctx[f"estimated_theta_{category}"]
+    current_level = learner_ctx[f"current_level_{category}"]
+
+    row = dict(learner_ctx)
+    row.update(
+        {
+            "game_id": game_id,
+            "game_category": category,
+            "difficulty": difficulty,
+            "difficulty_b": b,
+            "theta_minus_difficulty_b": est_theta - b,
+            "abs_theta_minus_difficulty_b": abs(est_theta - b),
+            "candidate_level_diff": difficulty - current_level,
+            "candidate_matches_current_level": int(difficulty == current_level),
+            "candidate_category_staleness": learner_ctx[f"category_since_played_{category}"],
+            "candidate_category_trend": learner_ctx[f"trend_{category}"],
+        }
+    )
+    return row
+
+
+ALL_CANDIDATES = [(gid, d) for gid in GAME_IDS for d in (1, 2, 3)]
+
+
+FEATURE_COLS = [
+    "game_id",
+    "game_category",
+    "difficulty",
+    "difficulty_b",
+    "theta_minus_difficulty_b",
+    "abs_theta_minus_difficulty_b",
+    "candidate_level_diff",
+    "candidate_matches_current_level",
+    "candidate_category_staleness",
+    "candidate_category_trend",
+    "age",
+    "is_onboarding",
+    "plays_in_session",
+    "last_game_category",
+] + [f"games_since_played_{g}" for g in GAME_IDS] + sum(
+    (
+        [
+            f"category_since_played_{c}",
+            f"is_first_play_{c}",
+            f"rolling_{c}_last3",
+            f"rolling_{c}_last5",
+            f"rolling_{c}_last10",
+            f"rolling_std_{c}_last5",
+            f"trend_{c}",
+            f"sessions_played_{c}",
+            f"days_since_last_played_{c}",
+            f"current_level_{c}",
+            f"estimated_theta_{c}",
+        ]
+        for c in CATEGORIES
+    ),
+    [],
+)
+
+CATEGORICAL_COLS = ["game_id", "game_category", "last_game_category"]
+TARGET_COL = "reward"
+GROUP_COL = "learner_id"

recommendation/recommendation_routes.py

@@ -0,0 +1,361 @@
+import logging
+from pathlib import Path
+from typing import Dict, Optional
+
+import joblib
+import numpy as np
+import pandas as pd
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field, validator
+
+from recommendation.simulator import (
+    GAMES,
+    CATEGORIES,
+    GAME_IDS,
+    DIFFICULTIES,
+)
+from recommendation.features import build_candidate_row
+
+logger = logging.getLogger("recommendation")
+
+router = APIRouter()
+
+ALL_CANDIDATES = [
+    (game_id, difficulty)
+    for game_id in GAME_IDS
+    for difficulty in DIFFICULTIES
+]
+
+VALID_LAST_GAME_CATEGORY = set(CATEGORIES) | {"none"}
+
+# ============================================================
+# Model
+# ============================================================
+
+# Quantile-75 is the deployed policy (chosen for category balance --
+# 14.4% memory coverage vs. 3.2% for the mean-regression baseline, at a
+# measured, accepted reward trade-off). Do NOT point this back at
+# reward_model.joblib (the mean baseline) without re-approving that
+# trade-off first.
+BASE_DIR = Path(__file__).resolve().parent.parent
+MODEL_PATH = BASE_DIR / "models" / "deployed_model.joblib"
+
+try:
+    bundle = joblib.load(MODEL_PATH)
+except Exception as e:
+    bundle = None
+    logger.error(f"Could not load model from {MODEL_PATH}: {e}")
+
+
+# ============================================================
+# Request schema
+# ============================================================
+
+class LearnerFeatures(BaseModel):
+    """
+    The 33 learner-state columns not already top-level on
+    RecommendationRequest (age, plays_in_session, last_game_category) and
+    not part of current_level. Field names match features.py:FEATURE_COLS
+    exactly. Nulls are accepted only where BACKEND_FEATURE_SPEC.md allows
+    them (first play in a category / game never played).
+    """
+
+    games_since_played_prob_maze: Optional[int] = None
+    games_since_played_att_odd_one_out: Optional[int] = None
+    games_since_played_mem_recognition: Optional[int] = None
+
+    category_since_played_attention: Optional[int] = None
+    category_since_played_memory: Optional[int] = None
+    category_since_played_problem_solving: Optional[int] = None
+
+    is_first_play_attention: int
+    is_first_play_memory: int
+    is_first_play_problem_solving: int
+
+    rolling_attention_last3: Optional[float] = None
+    rolling_memory_last3: Optional[float] = None
+    rolling_problem_solving_last3: Optional[float] = None
+
+    rolling_attention_last5: Optional[float] = None
+    rolling_memory_last5: Optional[float] = None
+    rolling_problem_solving_last5: Optional[float] = None
+
+    rolling_attention_last10: Optional[float] = None
+    rolling_memory_last10: Optional[float] = None
+    rolling_problem_solving_last10: Optional[float] = None
+
+    rolling_std_attention_last5: Optional[float] = None
+    rolling_std_memory_last5: Optional[float] = None
+    rolling_std_problem_solving_last5: Optional[float] = None
+
+    trend_attention: float = 0.0
+    trend_memory: float = 0.0
+    trend_problem_solving: float = 0.0
+
+    sessions_played_attention: int
+    sessions_played_memory: int
+    sessions_played_problem_solving: int
+
+    days_since_last_played_attention: Optional[float] = None
+    days_since_last_played_memory: Optional[float] = None
+    days_since_last_played_problem_solving: Optional[float] = None
+
+    estimated_theta_attention: float = 0.0
+    estimated_theta_memory: float = 0.0
+    estimated_theta_problem_solving: float = 0.0
+
+
+class RecommendationRequest(BaseModel):
+    learner_id: str
+    # Accepted for logging/audit only. days_since_last_played_* is computed
+    # by the backend and sent inside `features`, so timestamp does not feed
+    # into any feature computation here.
+    timestamp: str
+    age: int
+    plays_in_session: int = 0
+    last_game_category: str = "none"
+    features: LearnerFeatures
+    current_level: Dict[str, int]
+
+    @validator("last_game_category")
+    def _valid_last_game_category(cls, v):
+        if v not in VALID_LAST_GAME_CATEGORY:
+            raise ValueError(
+                f"last_game_category must be one of {sorted(VALID_LAST_GAME_CATEGORY)}, got {v!r}"
+            )
+        return v
+
+    @validator("current_level")
+    def _valid_current_level(cls, v):
+        missing = [c for c in CATEGORIES if c not in v]
+        if missing:
+            raise ValueError(f"current_level is missing required categories: {missing}")
+        bad = {c: lvl for c, lvl in v.items() if lvl not in (1, 2, 3)}
+        if bad:
+            raise ValueError(f"current_level values must be 1, 2 or 3, got: {bad}")
+        return v
+
+
+# ============================================================
+# Health check
+# ============================================================
+
+@router.get("/health")
+def health_check():
+    return {
+        "status": "ok",
+        "model_loaded": bundle is not None,
+        "model_path": str(MODEL_PATH),
+    }
+
+
+# ============================================================
+# Recommendation
+# ============================================================
+
+@router.post("/recommend")
+def recommend(request: RecommendationRequest):
+
+    if bundle is None:
+        raise HTTPException(
+            status_code=500,
+            detail="ML model is not loaded.",
+        )
+
+    # ----------------------------------------------------
+    # 1. Onboarding check -- bypass the model entirely.
+    #
+    # The model was trained on data where the first play of each of the
+    # 3 games was ALWAYS forced (never chosen by the reward model), so
+    # calling the model for a learner who hasn't played all 3 games yet
+    # would feed it a context distribution it never saw in training.
+    # "Never played" is read from games_since_played_<game> being null,
+    # rather than trusting a client-supplied is_onboarding flag.
+    # ----------------------------------------------------
+
+    games_since_played = {
+        "prob_maze": request.features.games_since_played_prob_maze,
+        "att_odd_one_out": request.features.games_since_played_att_odd_one_out,
+        "mem_recognition": request.features.games_since_played_mem_recognition,
+    }
+    unplayed_games = [g for g in GAME_IDS if games_since_played[g] is None]
+
+    if unplayed_games:
+        # Deterministic order (GAME_IDS order) rather than the random
+        # shuffle used in training data generation -- onboarding order
+        # doesn't affect the reward objective, only which game happens
+        # to go first, so determinism here is a reasonable simplification.
+        game_id = unplayed_games[0]
+        difficulty = 1
+        category = GAMES[game_id]["category"]
+
+        logger.info(f"learner {request.learner_id}: onboarding -> {game_id} d{difficulty}")
+
+        return {
+            "learner_id": request.learner_id,
+            "game_id": game_id,
+            "category": category,
+            "difficulty": difficulty,
+            "predicted_reward": None,
+            "is_onboarding": True,
+            "candidates": None,
+        }
+
+    try:
+        # ----------------------------------------------------
+        # 2. Build learner context
+        # ----------------------------------------------------
+
+        learner_ctx = {
+            "age": request.age,
+            "plays_in_session": request.plays_in_session,
+            "is_onboarding": 0,  # always 0 here -- onboarding returned above
+            "last_game_category": request.last_game_category,
+        }
+        learner_ctx.update(request.features.dict())
+
+        for category in CATEGORIES:
+            learner_ctx[f"current_level_{category}"] = request.current_level[category]
+
+        # ----------------------------------------------------
+        # 3. Generate candidate rows
+        # ----------------------------------------------------
+
+        rows = [
+            build_candidate_row(learner_ctx, game_id, difficulty)
+            for game_id, difficulty in ALL_CANDIDATES
+        ]
+
+        # ----------------------------------------------------
+        # 4. Build feature matrix, same column order as training
+        # ----------------------------------------------------
+
+        X = pd.DataFrame(rows)
+        X = X[bundle["feature_cols"]]
+
+        # ----------------------------------------------------
+        # 5. Handle categorical features
+        # ----------------------------------------------------
+
+        lib = bundle.get("lib")
+
+        for column in bundle.get("cat_cols", []):
+            if lib == "catboost":
+                X[column] = X[column].astype(str)
+            else:
+                X[column] = X[column].astype("category")
+
+        # ----------------------------------------------------
+        # 6. Generate predictions (quantile/mean/UCB bundle types supported;
+        #    Softmax changes selection policy, not reward prediction)
+        # ----------------------------------------------------
+
+        if bundle.get("type") == "ucb":
+            q10 = bundle["models"][0.1].predict(X)
+            q50 = bundle["models"][0.5].predict(X)
+            q90 = bundle["models"][0.9].predict(X)
+            predictions = q50 + bundle["k"] * (q90 - q10)
+        else:
+            predictions = bundle["model"].predict(X)
+
+        # ----------------------------------------------------
+        # 7. Apply category calibrators if this bundle uses them
+        # ----------------------------------------------------
+
+        calibrators = bundle.get("calibrators")
+
+        if calibrators:
+            categories = [row["game_category"] for row in rows]
+            predictions = np.array(
+                [
+                    calibrators[category].predict([prediction])[0]
+                    if category in calibrators
+                    else prediction
+                    for prediction, category in zip(predictions, categories)
+                ]
+            )
+
+        # ----------------------------------------------------
+        # 8. Select candidate
+        # ----------------------------------------------------
+        # Default policy: deterministic argmax.
+        # Softmax policy: sample from a probability distribution derived
+        # from the predicted rewards. The model still predicts a reward
+        # for every candidate; Softmax only changes how the final action
+        # is selected.
+        #
+        # Expected bundle format for Softmax:
+        # {
+        #     "type": "softmax",
+        #     "T": 0.05,
+        #     ...
+        # }
+        if bundle.get("type") == "softmax":
+            T = float(bundle["T"])
+            if T <= 0:
+                raise ValueError("Softmax temperature T must be > 0.")
+
+            # Subtract max for numerical stability.
+            z = (predictions - predictions.max()) / T
+            exp_z = np.exp(z)
+            probabilities = exp_z / exp_z.sum()
+
+            best_idx = int(
+                np.random.choice(
+                    len(ALL_CANDIDATES),
+                    p=probabilities,
+                )
+            )
+        else:
+            best_idx = int(np.argmax(predictions))
+
+        game_id, difficulty = ALL_CANDIDATES[best_idx]
+        category = GAMES[game_id]["category"]
+
+        candidates = [
+            {
+                "game_id": gid,
+                "difficulty": diff,
+                "predicted_reward": round(float(pred), 4),
+            }
+            for (gid, diff), pred in zip(ALL_CANDIDATES, predictions)
+        ]
+
+        logger.info(
+            f"learner {request.learner_id}: recommended {game_id} d{difficulty} "
+            f"(reward={predictions[best_idx]:.4f})"
+        )
+
+        # ----------------------------------------------------
+        # 9. Return recommendation
+        # ----------------------------------------------------
+
+        return {
+            "learner_id": request.learner_id,
+            "game_id": game_id,
+            "category": category,
+            "difficulty": difficulty,
+            "predicted_reward": round(float(predictions[best_idx]), 4),
+            "is_onboarding": False,
+            "candidates": candidates,
+        }
+
+    except KeyError as e:
+        # a required feature/category was missing after validation --
+        # should be rare given the schema above, but keep this specific
+        # so it's obviously a data problem, not a model problem
+        logger.exception(f"learner {request.learner_id}: missing field {e}")
+        raise HTTPException(
+            status_code=422,
+            detail=f"Request is missing a required field: {e}",
+        )
+
+    except Exception as e:
+        # log the real exception server-side for debugging, but don't
+        # leak internal details (stack traces, file paths, library
+        # internals) to the caller
+        logger.exception(f"learner {request.learner_id}: recommendation failed")
+        raise HTTPException(
+            status_code=500,
+            detail="Recommendation failed due to an internal error.",
+        )

recommendation/simulator.py

@@ -0,0 +1,234 @@
+"""
+Aiko environment / simulator core.
+
+This module preserves the original simulator's IRT-based game mechanics
+and behavior policy unchanged (per the review's instruction to keep
+proven simulator concepts intact). What changes lives in generate_data.py
+(counterfactual, all-9-candidate labeling) and features.py (feature
+engineering shared between training-time and inference-time).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+import numpy as np
+from scipy.stats import truncnorm
+
+DIFFICULTIES = (1, 2, 3)
+
+GAMES = {
+    "prob_maze": {
+        "category": "problem_solving",
+        "metric": "efficiency",
+        "comfort_target": 0.75,
+        "optimal_moves": {1: 5, 2: 9, 3: 14},
+        "seconds_per_move_mean": 3.0,
+        "difficulty_b": {1: -1.45, 2: -0.55, 3: 0.35},
+    },
+    "att_odd_one_out": {
+        "category": "attention",
+        "metric": "accuracy",
+        "comfort_target": 0.78,
+        "n_trials_range": (10, 16),
+        "difficulty_b": {1: -1.45, 2: -0.55, 3: 0.35},
+    },
+    "mem_recognition": {
+        "category": "memory",
+        "metric": "accuracy",
+        "comfort_target": 0.72,
+        "n_trials_range": (10, 18),
+        "difficulty_b": {1: -1.45, 2: -0.55, 3: 0.35},
+    },
+}
+
+DIFFICULTY_B = {1: -1.45, 2: -0.55, 3: 0.35}
+
+CATEGORIES = sorted({g["category"] for g in GAMES.values()})
+GAME_IDS = list(GAMES.keys())
+GAME_BY_CATEGORY = {c: [g for g, cfg in GAMES.items() if cfg["category"] == c] for c in CATEGORIES}
+CATEGORY_METRIC = {c: GAMES[GAME_BY_CATEGORY[c][0]]["metric"] for c in CATEGORIES}
+CATEGORY_OF_GAME = {g: cfg["category"] for g, cfg in GAMES.items()}
+
+EXPLORATION_RATE = 0.30
+PASS_THRESHOLD = 0.50
+HARD_FAIL_THRESHOLD = 0.20
+
+FLOW_WIDTH_LOW = 0.13
+FLOW_WIDTH_HIGH = 0.20
+REWARD_FLOOR = 0.2
+
+STALENESS_SATURATION_GAMES = 20.0
+STALENESS_REWARD_WEIGHT = 0.15  # kept only as a diagnostic/feature weight now, not the training target
+
+THETA_SCALE = 4.0
+DISCRIMINATION_HARD = 3.5
+DISCRIMINATION_EASY = 2.0
+
+ROLLING_WINDOWS = (3, 5, 10)
+
+
+def sigmoid(x):
+    return 1.0 / (1.0 + np.exp(-x))
+
+
+def logit(p):
+    p = np.clip(p, 1e-4, 1 - 1e-4)
+    return float(np.log(p / (1 - p)))
+
+
+def ability_to_theta(ability: float) -> float:
+    return (ability - 0.5) * THETA_SCALE
+
+
+def irt_probability(theta: float, b: float) -> float:
+    diff = theta - b
+    a = DISCRIMINATION_HARD if diff < 0 else DISCRIMINATION_EASY
+    return sigmoid(a * diff)
+
+
+for _cfg in GAMES.values():
+    _cfg["match_offset"] = logit(_cfg["comfort_target"]) / DISCRIMINATION_EASY
+
+
+def natural_level(theta: float, cfg: dict) -> int:
+    adjusted = theta - cfg["match_offset"]
+    return min(DIFFICULTIES, key=lambda lvl: abs(adjusted - cfg["difficulty_b"][lvl]))
+
+
+def flow_reward(score: float, target: float) -> float:
+    width = FLOW_WIDTH_LOW if score < target else FLOW_WIDTH_HIGH
+    gaussian = np.exp(-((score - target) ** 2) / (2 * width ** 2))
+    return REWARD_FLOOR + (1 - REWARD_FLOOR) * gaussian
+
+
+def shape_reward_with_staleness(flow: float, category_since_played) -> float:
+    """Diagnostic-only shaped reward (NOT the training target anymore)."""
+    if category_since_played is None or (
+        isinstance(category_since_played, float) and np.isnan(category_since_played)
+    ):
+        staleness = 1.0
+    else:
+        staleness = min(1.0, float(category_since_played) / STALENESS_SATURATION_GAMES)
+    base = (1.0 - STALENESS_REWARD_WEIGHT) + STALENESS_REWARD_WEIGHT * staleness
+    return float(np.clip(flow * base, REWARD_FLOOR, 1.0))
+
+
+def trunc_normal(mean, sd, low, high, size, rng):
+    a, b = (low - mean) / sd, (high - mean) / sd
+    return truncnorm.rvs(a, b, loc=mean, scale=sd, size=size, random_state=rng)
+
+
+@dataclass
+class Child:
+    learner_id: str
+    age: int
+    ability: dict  # hidden ground truth — simulator-only, never exposed to model
+    learning_rate: float  # hidden ground truth — simulator-only
+    fatigue_factor: float  # hidden ground truth — simulator-only
+
+    category_level: dict = field(default_factory=lambda: {c: 1 for c in CATEGORIES})
+    onboarding_queue: list = field(default_factory=list)
+
+    games_played_count: int = 0
+    game_last_index: dict = field(default_factory=dict)
+    category_last_index: dict = field(default_factory=dict)
+    category_last_ts: dict = field(default_factory=dict)
+    category_sessions_played: dict = field(default_factory=lambda: {c: set() for c in CATEGORIES})
+    history: list = field(default_factory=list)
+
+    session_id: int = -1
+    position_in_session: int = 0
+    plays_in_session: int = 0
+
+
+def sample_child(idx: int, rng: np.random.Generator) -> Child:
+    age = int(rng.integers(4, 10))
+    ability = {c: float(trunc_normal(0.5, 0.16, 0.05, 0.95, None, rng)) for c in CATEGORIES}
+    learning_rate = float(trunc_normal(0.02, 0.012, 0.0, 0.08, None, rng))
+    fatigue_factor = float(trunc_normal(0.03, 0.015, 0.0, 0.1, None, rng))
+
+    child = Child(
+        learner_id=f"child_{idx:04d}",
+        age=age,
+        ability=ability,
+        learning_rate=learning_rate,
+        fatigue_factor=fatigue_factor,
+    )
+    order = list(GAME_IDS)
+    rng.shuffle(order)
+    child.onboarding_queue = order
+    return child
+
+
+def simulate_accuracy_game(child: Child, game_id: str, level: int, fatigue: float, rng: np.random.Generator) -> dict:
+    cfg = GAMES[game_id]
+    ability = child.ability[cfg["category"]]
+    theta = ability_to_theta(ability) - fatigue * THETA_SCALE
+    b = cfg["difficulty_b"][level]
+    p_correct = float(np.clip(irt_probability(theta, b), 0.02, 0.98))
+    n_trials = int(rng.integers(*cfg["n_trials_range"]))
+    correct = int(rng.binomial(n_trials, p_correct))
+    accuracy_score = correct / n_trials
+    return {
+        "accuracy_score": accuracy_score,
+        "efficiency_score": np.nan,
+        "time_taken_seconds": np.nan,
+        "n_trials": n_trials,
+    }
+
+
+def simulate_efficiency_game(child: Child, game_id: str, level: int, fatigue: float, rng: np.random.Generator) -> dict:
+    cfg = GAMES[game_id]
+    ability = child.ability[cfg["category"]]
+    theta = ability_to_theta(ability) - fatigue * THETA_SCALE
+    b = cfg["difficulty_b"][level]
+    base_efficiency = irt_probability(theta, b)
+    noise = float(trunc_normal(0.0, 0.06, -0.2, 0.2, None, rng))
+    efficiency_score = float(np.clip(base_efficiency + noise, 0.03, 1.0))
+    effective_ability = float(np.clip(ability - fatigue, 0.05, 0.98))
+    optimal_moves = cfg["optimal_moves"][level]
+    moves_taken = max(optimal_moves, int(round(optimal_moves / efficiency_score)))
+    per_move_time = max(
+        0.5,
+        float(
+            trunc_normal(
+                cfg["seconds_per_move_mean"] * (1.15 - 0.3 * effective_ability), 0.6, 0.5, 8.0, None, rng
+            )
+        ),
+    )
+    time_taken_seconds = round(moves_taken * per_move_time, 1)
+    return {
+        "accuracy_score": np.nan,
+        "efficiency_score": efficiency_score,
+        "time_taken_seconds": time_taken_seconds,
+        "n_trials": np.nan,
+    }
+
+
+def simulate_game(child: Child, game_id: str, level: int, fatigue: float, rng: np.random.Generator) -> dict:
+    cfg = GAMES[game_id]
+    if cfg["metric"] == "accuracy":
+        return simulate_accuracy_game(child, game_id, level, fatigue, rng)
+    return simulate_efficiency_game(child, game_id, level, fatigue, rng)
+
+
+def score_and_reward(game_id: str, outcome: dict) -> tuple[float, float]:
+    """Return (raw_score, raw_flow_reward) for a simulated outcome."""
+    cfg = GAMES[game_id]
+    score = outcome["accuracy_score"] if cfg["metric"] == "accuracy" else outcome["efficiency_score"]
+    reward = flow_reward(score, cfg["comfort_target"])
+    return float(score), float(reward)
+
+
+def update_behavior_policy_state(child: Child, category: str, score: float) -> None:
+    if score >= PASS_THRESHOLD:
+        child.category_level[category] = min(3, child.category_level[category] + 1)
+    elif score < HARD_FAIL_THRESHOLD:
+        child.category_level[category] = max(1, child.category_level[category] - 1)
+
+
+def apply_learning(child: Child, categories_played) -> None:
+    for cat in categories_played:
+        child.ability[cat] = min(0.98, child.ability[cat] + child.learning_rate * (1 - child.ability[cat]))