DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""Mastery Path policy — pure decisions over a :class:`LearningProgress`.
No LLM calls, no I/O. This is the engine the chat-loop tutor consults each
turn. It answers three questions:
* **is this objective mastered?** (:func:`is_mastered` — a HARD, per-type gate)
* **what should the learner work on next?** (:func:`next_objective`)
* **what does the whole map look like?** (:func:`map_summary`)
The gate is the heart of mastery-based learning. An objective only counts as
mastered when the evidence clears its threshold, and :func:`next_objective`
keeps returning the same objective until it does — advancement is *computed
from what is mastered*, never tracked by a stage counter. Objective ordering
follows module order then knowledge-point order; an objective the learner has
already proven is skipped (the "test out" / compression path) because the gate
reads proven mastery, not a fixed sequence of stages.
"""
from __future__ import annotations
from dataclasses import dataclass
import time
from deeptutor.learning.models import (
KnowledgePoint,
KnowledgeType,
LearningProgress,
RepetitionState,
ReviewTask,
)
from deeptutor.learning.pending import PublicPendingQuestion, public_pending_question
# Quantitative gate for objective knowledge types: the learner must reach this
# mastery (recency-weighted accuracy; see ``mastery.compute_mastery``) before
# the objective unlocks. ~0.9 mirrors Alpha School's "90% before you advance".
QUANTITATIVE_GATE: dict[KnowledgeType, float] = {
KnowledgeType.MEMORY: 0.9,
KnowledgeType.PROCEDURE: 0.9,
}
# CONCEPT / DESIGN are gated qualitatively — a Feynman-style explanation judged
# by the tutor via ``mastery_assess`` — rather than by string-graded accuracy,
# because there is rarely a single canonical right answer to match against.
QUALITATIVE_TYPES: frozenset[KnowledgeType] = frozenset(
{KnowledgeType.CONCEPT, KnowledgeType.DESIGN}
)
# Display mastery a qualitative pass maps to, so the map's colours agree with
# the gate even though qualitative mastery is a boolean, not a score. (The
# fail-side display is handled in ``LearningService.record_qualitative``.)
_QUALITATIVE_PASS_DISPLAY = 1.0
def path_display_name(progress: LearningProgress) -> str:
"""What to call this path, everywhere it is named.
A path's own :attr:`~deeptutor.learning.models.LearningProgress.name` wins.
Without one the first module's name stands in, and failing that the storage
id — the behaviour every surface implemented separately before this
function existed, which is why rebuilding a map used to rename the path
(``mastery_build`` replaces module one) and why three surfaces could
disagree about the same path.
Derivation is the fallback, never the record: a named path keeps its name
across every rebuild.
"""
named = str(progress.name or "").strip()
if named:
return named
first_module = progress.modules[0].name.strip() if progress.modules else ""
return first_module or progress.book_id
def gate_threshold(kp_type: KnowledgeType) -> float:
"""The quantitative mastery bar for *kp_type* (qualitative types report
their pass-display value so callers have a single number to show)."""
if kp_type in QUALITATIVE_TYPES:
return _QUALITATIVE_PASS_DISPLAY
return QUANTITATIVE_GATE.get(kp_type, 0.9)
def is_assessed_mastered(progress: LearningProgress, kp: KnowledgePoint) -> bool:
"""Whether ``kp`` clears its mastery gate.
* MEMORY / PROCEDURE: recency-weighted accuracy ≥ the type's threshold.
* CONCEPT / DESIGN: a recorded qualitative pass (``mastery_assess``).
"""
if not set(kp.required_visual_tasks).issubset(visual_achievements(progress, kp.id)):
return False
if kp.type in QUALITATIVE_TYPES:
return bool(progress.qualitative_mastery.get(kp.id, False))
return progress.mastery_levels.get(kp.id, 0.0) >= gate_threshold(kp.type)
def visual_achievements(progress: LearningProgress, kp_id: str) -> list[str]:
"""Independent source-verified visual tasks, separate from generic text scores."""
return sorted(
{
event.visual_context["task"]
for event in progress.learning_evidence
if event.knowledge_point_id == kp_id
and event.result == "correct"
and event.visual_context.get("task")
and event.visual_context.get("key_status") == "verified"
and not event.hints_used
}
)
def learning_stage(progress: LearningProgress, kp_id: str) -> str:
attempts = [
item
for item in progress.quiz_attempts
if item.knowledge_point_id == kp_id and not item.voided
]
evidence = [item for item in progress.learning_evidence if item.knowledge_point_id == kp_id]
if any(item.independent and item.is_correct for item in attempts) or any(
item.assessment_type == "qualitative" and item.result == "correct" and not item.hints_used
for item in evidence
):
return "independently_demonstrated"
if any(not item.independent for item in attempts) or any(item.hints_used for item in evidence):
return "practiced_with_help"
if attempts or evidence:
return "practiced_not_demonstrated"
explained = progress.explained_objectives.get(kp_id)
if not explained:
return "not_yet_covered"
if (
explained.get("coverage") == "partial"
and explained.get("explanation_quote")
and explained.get("delivery", {}).get("turn_id")
):
return "partially_explained"
# Keep historical notes, but do not invent proof of published teaching or
# imply that a summary covered every part of a composite objective.
return "teaching_record_unverified"
def mastery_source(progress: LearningProgress, kp: KnowledgePoint) -> str:
"""Return ``system`` or ``learner`` provenance for a cleared waypoint."""
if is_assessed_mastered(progress, kp):
return "system"
if kp.id in progress.learner_mastery_overrides:
return "learner"
return ""
def is_mastered(progress: LearningProgress, kp: KnowledgePoint) -> bool:
"""Whether the route may advance past ``kp``.
The deterministic assessed gate remains available through
:func:`is_assessed_mastered`. An explicit learner claim may advance the
route, but every public report exposes that different provenance.
"""
return bool(mastery_source(progress, kp))
def display_mastery(progress: LearningProgress, kp: KnowledgePoint) -> float:
"""A 0..1 number for the map UI. Qualitatively-mastered points show full;
otherwise the recency-weighted accuracy stands in."""
if kp.type in QUALITATIVE_TYPES and progress.qualitative_mastery.get(kp.id):
return _QUALITATIVE_PASS_DISPLAY
return float(progress.mastery_levels.get(kp.id, 0.0))
def objective_status(progress: LearningProgress, kp: KnowledgePoint) -> str:
"""``"mastered"`` | ``"learning"`` | ``"new"`` for one knowledge point."""
if is_mastered(progress, kp):
return "mastered"
seen = any(a.knowledge_point_id == kp.id for a in progress.quiz_attempts) or (
kp.id in progress.qualitative_mastery
)
return "learning" if seen else "new"
def reviewable_tasks(progress: LearningProgress) -> list[ReviewTask]:
"""Scheduled items for objectives that have cleared the mastery gate.
Failed attempts can also carry retry schedules, but review mode is limited
to work the learner has already mastered.
"""
mastered_ids = {
kp.id
for module in progress.modules
for kp in module.knowledge_points
if is_mastered(progress, kp)
}
return [task for task in progress.review_queue if task.knowledge_point_id in mastered_ids]
def due_reviews(progress: LearningProgress, *, now: float | None = None) -> list[ReviewTask]:
"""Mastered spaced-repetition tasks whose ``due_at`` has passed, highest forgetting
risk first. Pure read over ``progress.review_queue`` (built by the scheduler)."""
from deeptutor.learning.scheduler import review_sort_key
moment = time.time() if now is None else now
due = [task for task in reviewable_tasks(progress) if task.due_at <= moment]
due.sort(key=lambda task: review_sort_key(task, now=moment))
return due
@dataclass(frozen=True)
class NextStep:
"""What the tutor should do next, decided by the gate — not a stage cursor.
``action`` is advisory for the model's pedagogy; the binding fact is the
objective and whether it is mastered. Values:
* ``answer_pending`` — a posed question awaits the learner's answer.
* ``review`` — a spaced-repetition item is due.
* ``probe`` — an untouched objective; test out before teaching.
* ``teach`` — teach an untouched objective before assessing it, by request.
* ``practice`` — a quantitative objective below its gate.
* ``assess`` — a qualitative objective awaiting a Feynman-style check.
* ``complete`` — every objective mastered, nothing due.
"""
action: str
module_id: str = ""
module_name: str = ""
knowledge_point_id: str = ""
knowledge_point_name: str = ""
knowledge_point_type: str = ""
status: str = ""
gate: str = ""
mastery: float = 0.0
threshold: float = 0.0
reason: str = ""
forgetting_risk: float = 0.0
pending_prompt: str = ""
pending_question: PublicPendingQuestion | None = None
session_id: str = ""
def to_dict(self) -> dict:
return {
"action": self.action,
"module_id": self.module_id,
"module_name": self.module_name,
"knowledge_point_id": self.knowledge_point_id,
"knowledge_point_name": self.knowledge_point_name,
"knowledge_point_type": self.knowledge_point_type,
"status": self.status,
"gate": self.gate,
"mastery": round(self.mastery, 3),
"threshold": round(self.threshold, 3),
"reason": self.reason,
"forgetting_risk": round(self.forgetting_risk, 3),
"pending_prompt": self.pending_prompt,
"pending_question": (
self.pending_question.to_dict() if self.pending_question is not None else None
),
"session_id": self.session_id,
}
def find_knowledge_point(
progress: LearningProgress, kp_id: str
) -> tuple[KnowledgePoint | None, str, str]:
"""Return ``(kp, module_id, module_name)`` for *kp_id*, or ``(None, "", "")``."""
for module in progress.modules:
for kp in module.knowledge_points:
if kp.id == kp_id:
return kp, module.id, module.name
return None, "", ""
def gate_kind(kp: KnowledgePoint) -> str:
"""Which gate ``kp`` has to clear — ``qualitative`` or ``quantitative``.
Public because the tutor's tools report it too: a quiz attempt on a
qualitative objective moves ``mastery_levels`` without moving the gate,
so every surface that shows a mastery number has to be able to say which
kind of gate that number is being read against.
"""
return "qualitative" if kp.type in QUALITATIVE_TYPES else "quantitative"
def next_objective(
progress: LearningProgress,
*,
now: float | None = None,
pending_session_id: str = "",
) -> NextStep:
"""Decide the next thing to work on. Order of precedence:
1. an outstanding posed question (grade it before moving on);
2. a due spaced-repetition review (don't let mastered ground decay);
3. the first not-yet-mastered objective in module/KP order (the gate IS
the cursor — mastered objectives are skipped);
4. otherwise the path is complete.
"""
pending = progress.pending_question
if pending is not None:
kp, module_id, module_name = find_knowledge_point(progress, pending.knowledge_point_id)
return NextStep(
action="answer_pending",
module_id=module_id or pending.module_id,
module_name=module_name,
knowledge_point_id=pending.knowledge_point_id,
knowledge_point_name=kp.name if kp else "",
knowledge_point_type=kp.type.value if kp else "",
status=objective_status(progress, kp) if kp else "learning",
gate=gate_kind(kp) if kp else "",
mastery=display_mastery(progress, kp) if kp else 0.0,
threshold=gate_threshold(kp.type) if kp else 0.0,
reason="A posed question is awaiting the learner's answer; grade it with mastery_grade.",
pending_prompt=pending.prompt,
pending_question=public_pending_question(pending),
session_id=str(pending_session_id or ""),
)
deferred_ids = set(progress.deferred_objectives)
due = [
task
for task in due_reviews(progress, now=now)
if task.knowledge_point_id not in deferred_ids
]
if due:
kp, module_id, module_name = find_knowledge_point(progress, due[0].knowledge_point_id)
if kp is not None:
task = due[0]
return NextStep(
action="review",
module_id=module_id,
module_name=module_name,
knowledge_point_id=kp.id,
knowledge_point_name=kp.name,
knowledge_point_type=kp.type.value,
status=objective_status(progress, kp),
gate=gate_kind(kp),
mastery=display_mastery(progress, kp),
threshold=gate_threshold(kp.type),
reason=(task.reason or "This objective is due for spaced-repetition review."),
forgetting_risk=task.forgetting_risk,
)
deferred_fallback: NextStep | None = None
for module in sorted(progress.modules, key=lambda m: m.order):
for kp in module.knowledge_points:
if is_mastered(progress, kp):
continue
status = objective_status(progress, kp)
gate = gate_kind(kp)
if status == "new":
action = (
"teach"
if progress.learner_profile is not None
and progress.learner_profile.teaching_strategy == "teach_first"
else "probe"
)
elif gate == "qualitative":
action = "assess"
else:
action = "practice"
step = NextStep(
action=action,
module_id=module.id,
module_name=module.name,
knowledge_point_id=kp.id,
knowledge_point_name=kp.name,
knowledge_point_type=kp.type.value,
status=status,
gate=gate,
mastery=display_mastery(progress, kp),
threshold=gate_threshold(kp.type),
reason=(
(
"Untouched objective — teach before assessing, as the learner requested."
if action == "teach"
else "Untouched objective — probe first to let the learner test out."
)
if status == "new"
else "Objective is below its mastery gate; keep working it until it clears."
),
)
if kp.id in deferred_ids:
if deferred_fallback is None:
deferred_fallback = step
continue
return step
if deferred_fallback is not None:
return deferred_fallback
return NextStep(action="complete", reason="All objectives are mastered and no reviews are due.")
def map_summary(progress: LearningProgress, *, now: float | None = None) -> dict:
"""A compact, render-ready snapshot of the whole path for the tutor's
``mastery_status`` tool and the dashboard."""
counts = {"mastered": 0, "learning": 0, "new": 0, "total": 0}
modules_out: list[dict] = []
for module in sorted(progress.modules, key=lambda m: m.order):
kps_out: list[dict] = []
mastered = 0
for kp in module.knowledge_points:
status = objective_status(progress, kp)
counts[status] += 1
counts["total"] += 1
if status == "mastered":
mastered += 1
kps_out.append(
{
"id": kp.id,
"name": kp.name,
"type": kp.type.value,
"prerequisite_ids": list(kp.prerequisite_ids),
"topic_source_ids": list(kp.topic_source_ids),
"status": status,
"mastery": round(display_mastery(progress, kp), 3),
"mastery_source": mastery_source(progress, kp),
"override_note": (
progress.learner_mastery_overrides[kp.id].note
if kp.id in progress.learner_mastery_overrides
else ""
),
"deferred": kp.id in progress.deferred_objectives,
}
)
modules_out.append(
{
"id": module.id,
"name": module.name,
# What the module is for. Empty on outlines built before the
# field existed; every reader falls back to the name.
"objective": module.objective,
"order": module.order,
"mastered": mastered,
"total": len(module.knowledge_points),
"knowledge_points": kps_out,
}
)
return {
"name": path_display_name(progress),
"counts": counts,
"due_reviews": len(due_reviews(progress, now=now)),
"complete": counts["total"] > 0 and counts["mastered"] == counts["total"],
"modules": modules_out,
}
def _review_report(
progress: LearningProgress,
kp_id: str,
state: RepetitionState | None,
due_at: float | None,
*,
now: float,
) -> dict | None:
if state is None:
return None
task = next((item for item in progress.review_queue if item.knowledge_point_id == kp_id), None)
from deeptutor.learning.scheduler import SpacedRepetitionScheduler
scheduler = SpacedRepetitionScheduler()
recall = scheduler.retrievability(state, now=now)
risk = (
task.forgetting_risk
if task is not None
else scheduler.forgetting_risk(state, progress, kp_id, now=now)
)
reason = (
task.reason
if task is not None
else scheduler.review_reason(state, progress, kp_id, now=now)
)
return {
"due_at": due_at,
"interval_index": state.interval_index,
"consecutive_correct": state.consecutive_correct,
"consecutive_wrong": state.consecutive_wrong,
"stability": round(state.stability, 3),
"retrievability": round(recall, 3),
"desired_retention": state.desired_retention,
"lapse_count": state.lapse_count,
"forgetting_risk": round(risk, 3),
"reason": reason,
"recent_failure": bool(
state.consecutive_wrong
or any(
record.knowledge_point_id == kp_id and record.status in ("active", "retrying")
for record in progress.error_records
)
),
}
def objective_report(
progress: LearningProgress, kp_id: str, *, now: float | None = None
) -> dict | None:
"""Everything the engine knows about one objective, for review.
``map_summary`` stays deliberately thin because the tutor reads it on every
turn; this is the opposite trade — the whole evidence trail behind a single
objective, read only when someone opens it. ``None`` when *kp_id* is not on
the path.
"""
kp, module_id, module_name = find_knowledge_point(progress, kp_id)
if kp is None:
return None
attempts = [
{
"question_id": attempt.question_id,
"is_correct": attempt.is_correct,
"independent": attempt.independent,
"answer": str(attempt.user_answer or ""),
"error_type": attempt.error_type.value if attempt.error_type else "",
"at": attempt.timestamp,
}
for attempt in progress.quiz_attempts
if attempt.knowledge_point_id == kp_id
]
state = progress.repetition_states.get(kp_id)
due_at = next(
(task.due_at for task in progress.review_queue if task.knowledge_point_id == kp_id),
None,
)
moment = time.time() if now is None else now
return {
"id": kp.id,
"name": kp.name,
"type": kp.type.value,
"module_id": module_id,
"module_name": module_name,
"status": objective_status(progress, kp),
"gate": gate_kind(kp),
"mastered": is_mastered(progress, kp),
"assessed_mastered": is_assessed_mastered(progress, kp),
"mastery_source": mastery_source(progress, kp),
"override_note": (
progress.learner_mastery_overrides[kp_id].note
if kp_id in progress.learner_mastery_overrides
else ""
),
"mastery": round(display_mastery(progress, kp), 3),
"threshold": round(gate_threshold(kp.type), 3),
"attempts": attempts,
"correct_count": sum(1 for attempt in attempts if attempt["is_correct"]),
# The learner's own words, kept as the evidence behind a qualitative pass.
"explanation": progress.feynman_explanations.get(kp_id, ""),
"explained": progress.explained_objectives.get(kp_id),
"required_visual_tasks": kp.required_visual_tasks,
"demonstrated_visual_tasks": visual_achievements(progress, kp_id),
"review": _review_report(progress, kp_id, state, due_at, now=moment),
"errors": [
{
"id": record.id,
"error_type": record.error_type.value,
"status": record.status,
"self_attribution": record.self_attribution,
"retries": len(record.retry_history),
"created_at": record.created_at,
}
for record in progress.error_records
if record.knowledge_point_id == kp_id
],
}
__all__ = [
"QUANTITATIVE_GATE",
"QUALITATIVE_TYPES",
"NextStep",
"gate_kind",
"gate_threshold",
"is_assessed_mastered",
"is_mastered",
"mastery_source",
"display_mastery",
"objective_status",
"objective_report",
"due_reviews",
"find_knowledge_point",
"next_objective",
"map_summary",
"path_display_name",
]