Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

21.7 KB
Raw Blame
from __future__ import annotations

import math
import os
import time
from typing import Protocol

from deeptutor.learning.models import (
    KnowledgeType,
    LearningEvidence,
    LearningProgress,
    RepetitionState,
    ReviewTask,
)

INTERVAL_SEQUENCES: dict[KnowledgeType, list[int]] = {
    KnowledgeType.MEMORY: [0, 1, 3, 7, 14, 30, 60],
    KnowledgeType.CONCEPT: [3, 7, 14, 30],
    KnowledgeType.PROCEDURE: [3, 7, 14],
    KnowledgeType.DESIGN: [14, 28],
}

_TYPE_PRIORITY: dict[KnowledgeType, int] = {
    KnowledgeType.MEMORY: 2,
    KnowledgeType.CONCEPT: 3,
    KnowledgeType.PROCEDURE: 4,
    KnowledgeType.DESIGN: 5,
}

_TYPE_DIFFICULTY: dict[KnowledgeType, float] = {
    KnowledgeType.MEMORY: 0.3,
    KnowledgeType.CONCEPT: 0.4,
    KnowledgeType.PROCEDURE: 0.5,
    KnowledgeType.DESIGN: 0.6,
}

DEFAULT_DESIRED_RETENTION = 0.9
MIN_DESIRED_RETENTION = 0.7
MAX_DESIRED_RETENTION = 0.99
_MIN_STABILITY_DAYS = 0.5
_FAIL_QUALITY = 0.5
_EPS = 1e-6
# Short-interval practice is not another durable retrieval (#1541). The
# threshold uses a fixed baseline interval, not the learner's configurable
# recall target, so changing that target cannot alter replayed transitions.
_SAME_SESSION_DAYS = 0.25
_EVIDENCE_SOURCE_LABELS = {
    "deep_question": "Question Bank",
    "immersive_reading": "Reading",
    "book": "Book",
    "partner_chat": "Study Partner",
    "import": "Imported",
}


def validate_desired_retention(value: float) -> float:
    desired = float(value)
    if not math.isfinite(desired) or not MIN_DESIRED_RETENTION <= desired <= MAX_DESIRED_RETENTION:
        raise ValueError(
            f"desired_retention must be between {MIN_DESIRED_RETENTION} and {MAX_DESIRED_RETENTION}"
        )
    return desired


class RetentionScheduler(Protocol):
    """Pluggable retention model. The default baseline is exponential forgetting
    with type-specific cold-start priors — not a calibrated FSRS fit.
    """

    def get_initial_state(
        self,
        knowledge_type: KnowledgeType,
        *,
        now: float | None = None,
        desired_retention: float | None = None,
    ) -> RepetitionState: ...

    def schedule_review(
        self,
        state: RepetitionState,
        knowledge_type: KnowledgeType,
        evidence: LearningEvidence,
        *,
        now: float | None = None,
    ) -> RepetitionState: ...

    def retrievability(self, state: RepetitionState, *, now: float | None = None) -> float: ...

    def forgetting_risk(
        self,
        state: RepetitionState,
        progress: LearningProgress,
        kp_id: str,
        *,
        now: float | None = None,
    ) -> float: ...

    def build_review_queue(
        self, progress: LearningProgress, *, now: float | None = None
    ) -> list[ReviewTask]: ...

    def replay(
        self,
        knowledge_type: KnowledgeType,
        evidence: list[LearningEvidence],
        *,
        now: float | None = None,
        desired_retention: float | None = None,
        initial_state: RepetitionState | None = None,
    ) -> RepetitionState: ...


def _error_kp_ids(progress: LearningProgress) -> set[str]:
    return {
        rec.knowledge_point_id
        for rec in progress.error_records
        if rec.status in ("active", "retrying")
    }


def review_sort_key(task: ReviewTask, *, now: float) -> tuple[float, float, int]:
    """Higher forgetting risk, then more overdue, then lower type/error priority."""
    overdue = max(0.0, now - task.due_at)
    return (-task.forgetting_risk, -overdue, task.priority)


class SpacedRepetitionScheduler:
    def __init__(self, *, desired_retention: float = DEFAULT_DESIRED_RETENTION) -> None:
        # When True, intervals are in seconds instead of days (for testing)
        self.DEBUG_MODE: bool = os.environ.get("LEARNING_DEBUG", "").lower() in ("1", "true", "yes")
        self.desired_retention = validate_desired_retention(desired_retention)

    def _seconds_per_unit(self) -> float:
        return 1.0 if self.DEBUG_MODE else 86400.0

    @staticmethod
    def _stability_from_interval(interval_days: float, desired_retention: float) -> float:
        retention = min(max(desired_retention, _EPS), 1.0 - _EPS)
        if interval_days <= 0:
            return _MIN_STABILITY_DAYS
        return max(_MIN_STABILITY_DAYS, interval_days / -math.log(retention))

    @staticmethod
    def _interval_from_stability(stability: float, desired_retention: float) -> float:
        retention = min(max(desired_retention, _EPS), 1.0 - _EPS)
        return max(_EPS, max(stability, _EPS) * -math.log(retention))

    def _scheduled_interval_days(
        self, state: RepetitionState, knowledge_type: KnowledgeType
    ) -> float:
        if state.review_count == 0 and INTERVAL_SEQUENCES[knowledge_type][0] == 0:
            return 0.0
        interval_days = self._interval_from_stability(state.stability, state.desired_retention)
        if state.scheduled_after_failure:
            interval_days = min(
                interval_days,
                max(interval_days * 0.5, _MIN_STABILITY_DAYS * 0.2),
            )
        return interval_days

    def hydrate(self, state: RepetitionState, knowledge_type: KnowledgeType) -> RepetitionState:
        """Fill retention fields from a legacy interval-index snapshot.

        Does not change ``next_review_at``: the stored due time remains the
        source of truth for already-scheduled items.
        """
        if state.stability > 0:
            if state.difficulty <= 0:
                state.difficulty = _TYPE_DIFFICULTY.get(knowledge_type, 0.3)
            return state
        intervals = INTERVAL_SEQUENCES[knowledge_type]
        max_index = len(intervals) - 1
        state.interval_index = max(0, min(state.interval_index, max_index))
        state.desired_retention = state.desired_retention or DEFAULT_DESIRED_RETENTION
        state.stability = self._stability_from_interval(
            float(intervals[state.interval_index]), state.desired_retention
        )
        state.difficulty = _TYPE_DIFFICULTY.get(knowledge_type, 0.3)
        if state.retrievability <= 0:
            state.retrievability = 1.0
        return state

    def get_initial_state(
        self,
        knowledge_type: KnowledgeType,
        *,
        now: float | None = None,
        desired_retention: float | None = None,
    ) -> RepetitionState:
        intervals = INTERVAL_SEQUENCES[knowledge_type]
        first_interval = float(intervals[0])
        moment = time.time() if now is None else now
        desired = (
            self.desired_retention
            if desired_retention is None
            else validate_desired_retention(desired_retention)
        )
        stability = self._stability_from_interval(first_interval, DEFAULT_DESIRED_RETENTION)
        initial_interval = (
            first_interval
            if first_interval == 0
            else self._interval_from_stability(stability, desired)
        )
        return RepetitionState(
            interval_index=0,
            consecutive_correct=0,
            consecutive_wrong=0,
            next_review_at=moment + initial_interval * self._seconds_per_unit(),
            difficulty=_TYPE_DIFFICULTY[knowledge_type],
            stability=stability,
            retrievability=1.0,
            desired_retention=desired,
            review_count=0,
            lapse_count=0,
            last_review_at=None,
            last_scheduled_at=moment,
            scheduled_after_failure=False,
        )

    def schedule_next(
        self, state: RepetitionState, knowledge_type: KnowledgeType, is_correct: bool
    ) -> RepetitionState:
        evidence = LearningEvidence(
            knowledge_point_id="",
            assessment_type="review",
            result="correct" if is_correct else "incorrect",
            quality=1.0 if is_correct else 0.0,
        )
        return self.schedule_review(state, knowledge_type, evidence)

    def schedule_review(
        self,
        state: RepetitionState,
        knowledge_type: KnowledgeType,
        evidence: LearningEvidence,
        *,
        now: float | None = None,
    ) -> RepetitionState:
        self.hydrate(state, knowledge_type)
        event_moment = evidence.timestamp if now is None else now
        # A delayed cross-surface write keeps its source timestamp for audit,
        # but cannot move the learner's last review backwards in time.
        moment = (
            max(event_moment, state.last_review_at)
            if state.last_review_at is not None
            else event_moment
        )
        quality = _resolved_quality(evidence)
        intervals = INTERVAL_SEQUENCES[knowledge_type]
        max_index = len(intervals) - 1

        # A successful delayed retrieval is stronger evidence than an
        # immediate repetition. Measure the state before applying the review;
        # replay uses the event timestamp and therefore follows this exact
        # transition deterministically.
        previous_stability = max(state.stability, _EPS)
        previous_retrievability = self.retrievability(state, now=moment)
        elapsed_days = (
            max(0.0, moment - state.last_review_at) / self._seconds_per_unit()
            if state.last_review_at is not None
            else 0.0
        )
        same_session_days = min(
            _SAME_SESSION_DAYS,
            self._interval_from_stability(previous_stability, DEFAULT_DESIRED_RETENTION) * 0.5,
        )
        if state.last_review_at is not None and elapsed_days < same_session_days:
            if quality >= _FAIL_QUALITY:
                # Repeated practice refreshes recall, but must not repeatedly
                # multiply stability or postpone the original review deadline.
                state.review_count += 1
                state.last_review_at = moment
                state.retrievability = 1.0
                state.consecutive_wrong = 0
                return state
            if state.scheduled_after_failure and (
                evidence.result == "partial" or evidence.assessment_type == "qualitative"
            ):
                # Formative follow-ups within an active repair episode do not count
                # as repeated independent lapses or compound stability loss (#1781).
                state.review_count += 1
                state.last_review_at = moment
                state.retrievability = max(quality, 0.2)
                return state
        spacing_ratio = min(elapsed_days / previous_stability, 4.0)

        # Difficulty is an item/learner estimate, not the knowledge-type
        # category. Surprising failures raise it; strong retrieval lowers it.
        outcome_error = (1.0 - quality) - state.difficulty
        surprise = previous_retrievability - quality
        state.difficulty = float(
            min(0.95, max(0.05, state.difficulty + 0.12 * outcome_error + 0.08 * surprise))
        )

        if quality < _FAIL_QUALITY:
            state.consecutive_wrong += 1
            state.consecutive_correct = 0
            state.lapse_count += 1
            # Forgetting something that was predicted to be retrievable is a
            # stronger negative update. A hard item also recovers less of its
            # prior stability after a lapse.
            retention_factor = 0.55 - 0.25 * previous_retrievability
            difficulty_factor = 1.0 - 0.25 * state.difficulty
            state.stability = max(
                _MIN_STABILITY_DAYS * 0.1,
                previous_stability * retention_factor * difficulty_factor,
            )
            state.retrievability = max(quality, 0.2)
            if state.consecutive_wrong >= 2:
                state.consecutive_wrong = 0
        else:
            state.consecutive_wrong = 0
            state.consecutive_correct += 1
            retrieval_effort = 1.0 + (1.0 - previous_retrievability) * 1.5
            spacing_bonus = 1.0 + spacing_ratio * 0.15
            learnability = 1.35 - 0.6 * state.difficulty
            quality_strength = max(0.0, (quality - _FAIL_QUALITY) / (1.0 - _FAIL_QUALITY))
            growth = 1.0 + quality_strength * learnability * retrieval_effort * spacing_bonus
            if quality >= 0.8 and state.consecutive_correct >= 2:
                growth *= 1.15
            state.stability = max(_MIN_STABILITY_DAYS, previous_stability * growth)
            state.retrievability = 1.0
            if state.consecutive_correct >= 2:
                state.consecutive_correct = 0

        state.review_count += 1
        state.last_review_at = moment
        state.last_scheduled_at = moment
        state.scheduled_after_failure = quality < _FAIL_QUALITY
        interval_days = self._scheduled_interval_days(state, knowledge_type)
        state.next_review_at = moment + interval_days * self._seconds_per_unit()
        state.interval_index = _snap_interval_index(intervals, interval_days, max_index)
        return state

    def retrievability(self, state: RepetitionState, *, now: float | None = None) -> float:
        moment = time.time() if now is None else now
        stability = max(state.stability, _EPS)
        anchor = state.last_review_at if state.last_review_at is not None else state.next_review_at
        elapsed_days = max(0.0, (moment - anchor) / self._seconds_per_unit())
        return float(min(1.0, max(0.0, math.exp(-elapsed_days / stability))))

    def forgetting_risk(
        self,
        state: RepetitionState,
        progress: LearningProgress,
        kp_id: str,
        *,
        now: float | None = None,
    ) -> float:
        moment = time.time() if now is None else now
        recall = self.retrievability(state, now=moment)
        risk = 1.0 - recall
        if moment > state.next_review_at:
            overdue_days = (moment - state.next_review_at) / self._seconds_per_unit()
            risk += min(overdue_days / 7.0, 0.25)
        if kp_id in _error_kp_ids(progress):
            risk += 0.2
        if state.lapse_count:
            risk += min(0.1 * state.lapse_count, 0.2)
        return float(min(1.0, max(0.0, risk)))

    def review_reason(
        self,
        state: RepetitionState,
        progress: LearningProgress,
        kp_id: str,
        *,
        now: float | None = None,
        latest_evidence: LearningEvidence | None = None,
    ) -> str:
        moment = time.time() if now is None else now
        unit = self._seconds_per_unit()
        recall = self.retrievability(state, now=moment)
        parts: list[str] = []
        delta = moment - state.next_review_at
        if delta >= unit:
            parts.append(f"due {_format_span(delta / unit)} ago")
        elif delta >= 0:
            parts.append("due now")
        else:
            parts.append(f"due in {_format_span(-delta / unit)}")
        desired = state.desired_retention or DEFAULT_DESIRED_RETENTION
        if recall + 1e-9 < desired:
            parts.append(f"retrievability {recall:.0%} below {desired:.0%} target")
        else:
            parts.append(f"retrievability {recall:.0%}")
        failures = state.consecutive_wrong + (1 if kp_id in _error_kp_ids(progress) else 0)
        if state.lapse_count:
            parts.append(f"{state.lapse_count} lapse{'s' if state.lapse_count != 1 else ''}")
        elif failures:
            parts.append("recent failure")
        if latest_evidence is not None:
            source = _EVIDENCE_SOURCE_LABELS.get(latest_evidence.source)
            if source is not None:
                parts.append(f"latest {source} assessment: {latest_evidence.result}")
        return "; ".join(parts) + "."

    def get_due_tasks(self, progress: LearningProgress, max_tasks: int = 5) -> list[ReviewTask]:
        now = time.time()
        due = [t for t in progress.review_queue if t.due_at <= now]
        due.sort(key=lambda t: review_sort_key(t, now=now))
        return due[:max_tasks]

    def build_review_queue(
        self, progress: LearningProgress, *, now: float | None = None
    ) -> list[ReviewTask]:
        moment = time.time() if now is None else now
        error_kps = _error_kp_ids(progress)
        latest_evidence: dict[str, LearningEvidence] = {}
        for event in progress.learning_evidence:
            # The newest applied event is the last durable append, even if a
            # cross-surface assessment carried an earlier source timestamp.
            latest_evidence[event.knowledge_point_id] = event
        tasks: list[ReviewTask] = []
        for kp_id, state in progress.repetition_states.items():
            kp_type = progress.knowledge_types.get(kp_id, KnowledgeType.MEMORY)
            self.hydrate(state, kp_type)
            priority = 1 if kp_id in error_kps else _TYPE_PRIORITY[kp_type]
            risk = self.forgetting_risk(state, progress, kp_id, now=moment)
            evidence = latest_evidence.get(kp_id)
            tasks.append(
                ReviewTask(
                    id=f"review_{kp_id}",
                    knowledge_point_id=kp_id,
                    knowledge_type=kp_type,
                    due_at=state.next_review_at,
                    priority=priority,
                    state=state,
                    forgetting_risk=round(risk, 4),
                    reason=self.review_reason(
                        state, progress, kp_id, now=moment, latest_evidence=evidence
                    ),
                    evidence_source=evidence.source if evidence is not None else "",
                    evidence_id=evidence.evidence_id if evidence is not None else "",
                )
            )
        tasks.sort(key=lambda t: review_sort_key(t, now=moment))
        return tasks

    def set_desired_retention(
        self,
        progress: LearningProgress,
        desired_retention: float,
        *,
        now: float | None = None,
    ) -> None:
        """Change one path's target without rewriting its evidence history.

        Rescale the already scheduled interval, including a shorter failure
        retry. Do not count a settings edit as an assessment (#1541).
        """
        desired = validate_desired_retention(desired_retention)
        moment = time.time() if now is None else now
        for kp_id, state in progress.repetition_states.items():
            kp_type = progress.knowledge_types.get(kp_id, KnowledgeType.MEMORY)
            self.hydrate(state, kp_type)
            old_desired = validate_desired_retention(state.desired_retention)
            anchor = state.last_scheduled_at
            state.desired_retention = desired
            if anchor is not None:
                interval = self._scheduled_interval_days(state, kp_type)
                state.next_review_at = anchor + interval * self._seconds_per_unit()
                interval = (state.next_review_at - anchor) / self._seconds_per_unit()
                intervals = INTERVAL_SEQUENCES[kp_type]
                state.interval_index = _snap_interval_index(intervals, interval, len(intervals) - 1)
            elif state.last_review_at is not None:
                # Pre-#1541 states have no schedule anchor. Preserve their
                # existing interval until the next actual review establishes it.
                ratio = -math.log(desired) / -math.log(old_desired)
                state.next_review_at = (
                    state.last_review_at + (state.next_review_at - state.last_review_at) * ratio
                )
            elif state.next_review_at > moment:
                # Legacy snapshots may lack a review anchor; preserve their
                # overdue position and only scale remaining future time.
                ratio = -math.log(desired) / -math.log(old_desired)
                state.next_review_at = moment + (state.next_review_at - moment) * ratio
        progress.desired_retention = desired
        progress.review_queue = self.build_review_queue(progress, now=moment)

    def replay(
        self,
        knowledge_type: KnowledgeType,
        evidence: list[LearningEvidence],
        *,
        now: float | None = None,
        desired_retention: float | None = None,
        initial_state: RepetitionState | None = None,
    ) -> RepetitionState:
        if initial_state is not None:
            if desired_retention is not None:
                raise ValueError("initial_state already contains desired_retention")
            state = initial_state.model_copy(deep=True)
            for event in evidence:
                self.schedule_review(state, knowledge_type, event, now=event.timestamp)
            return state
        if not evidence:
            return self.get_initial_state(
                knowledge_type, now=now, desired_retention=desired_retention
            )
        state = self.get_initial_state(
            knowledge_type,
            now=evidence[0].timestamp,
            desired_retention=desired_retention,
        )
        for event in evidence:
            self.schedule_review(state, knowledge_type, event, now=event.timestamp)
        return state


def _resolved_quality(evidence: LearningEvidence) -> float:
    if evidence.quality is not None:
        quality = float(evidence.quality)
    elif evidence.result == "correct":
        quality = 1.0
    elif evidence.result == "partial":
        quality = 0.4
    else:
        quality = 0.0
    if evidence.quality is None:
        quality -= min(0.25, evidence.hints_used * 0.08)
        quality -= min(0.2, max(0, evidence.attempt_count - 1) * 0.05)
    return max(0.0, min(1.0, quality))


def _snap_interval_index(intervals: list[int], interval_days: float, max_index: int) -> int:
    nearest = min(range(len(intervals)), key=lambda i: abs(float(intervals[i]) - interval_days))
    return max(0, min(nearest, max_index))


def _format_span(days: float) -> str:
    if days < 1.0 / 24.0:
        return "moments"
    if days < 1:
        hours = max(1, int(round(days * 24)))
        return f"{hours} hour{'s' if hours != 1 else ''}"
    if days < 1.5:
        return "1 day"
    return f"{int(round(days))} days"


BaselineRetentionScheduler = SpacedRepetitionScheduler

__all__ = [
    "BaselineRetentionScheduler",
    "INTERVAL_SEQUENCES",
    "RetentionScheduler",
    "SpacedRepetitionScheduler",
    "review_sort_key",
]