DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(learning): replay retention changes and late evidence consistently (#1541)
Bingxi Zhao (Frank)a83683640e33
diff --git a/deeptutor/learning/models.py b/deeptutor/learning/models.pyindex 843e8b396..9e3e928e3 100644--- a/deeptutor/learning/models.py+++ b/deeptutor/learning/models.py@@ -195,6 +195,11 @@ class RepetitionState(BaseModel):review_count: int = 0lapse_count: int = 0last_review_at: float | None = None+ # The review (or initial schedule) that set ``next_review_at``. Practice+ # inside one session updates ``last_review_at`` but keeps this anchor, so+ # changing the target cannot silently postpone a previously due review.+ last_scheduled_at: float | None = None+ scheduled_after_failure: bool = Falseclass ReviewTask(BaseModel):diff --git a/deeptutor/learning/scheduler.py b/deeptutor/learning/scheduler.pyindex d461900b9..595b5e73f 100644--- a/deeptutor/learning/scheduler.py+++ b/deeptutor/learning/scheduler.py@@ -40,8 +40,9 @@ MAX_DESIRED_RETENTION = 0.99_MIN_STABILITY_DAYS = 0.5_FAIL_QUALITY = 0.5_EPS = 1e-6-# Answers repeated before the next due time within one study session are-# practice, not evidence of another durable retrieval (#1541).+# 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",@@ -144,6 +145,19 @@ class SpacedRepetitionScheduler: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.@@ -181,18 +195,26 @@ class SpacedRepetitionScheduler:if desired_retention is Noneelse 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 + first_interval * self._seconds_per_unit(),+ next_review_at=moment + initial_interval * self._seconds_per_unit(),difficulty=_TYPE_DIFFICULTY[knowledge_type],- stability=self._stability_from_interval(first_interval, desired),+ 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(@@ -215,7 +237,14 @@ class SpacedRepetitionScheduler:now: float | None = None,) -> RepetitionState:self.hydrate(state, knowledge_type)- moment = evidence.timestamp if now is None else now+ 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@@ -231,11 +260,14 @@ class SpacedRepetitionScheduler:if state.last_review_at is not Noneelse 0.0)+ same_session_days = min(+ _SAME_SESSION_DAYS,+ self._interval_from_stability(previous_stability, DEFAULT_DESIRED_RETENTION) * 0.5,+ )if (quality >= _FAIL_QUALITYand state.last_review_at is not None- and elapsed_days < _SAME_SESSION_DAYS- and moment < state.next_review_at+ and elapsed_days < same_session_days):# Repeated practice refreshes recall, but must not repeatedly# multiply stability or postpone the original review deadline.@@ -287,11 +319,9 @@ class SpacedRepetitionScheduler:state.review_count += 1state.last_review_at = moment- interval_days = self._interval_from_stability(state.stability, state.desired_retention)- if quality < _FAIL_QUALITY:- # Failures must come back sooner than the success formula alone- # would schedule after a halved stability.- interval_days = min(interval_days, max(interval_days * 0.5, _MIN_STABILITY_DAYS * 0.2))+ 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@@ -372,9 +402,9 @@ class SpacedRepetitionScheduler:error_kps = _error_kp_ids(progress)latest_evidence: dict[str, LearningEvidence] = {}for event in progress.learning_evidence:- prior = latest_evidence.get(event.knowledge_point_id)- if prior is None or event.timestamp >= prior.timestamp:- latest_evidence[event.knowledge_point_id] = event+ # 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] = eventtasks: list[ReviewTask] = []for kp_id, state in progress.repetition_states.items():kp_type = progress.knowledge_types.get(kp_id, KnowledgeType.MEMORY)@@ -419,18 +449,26 @@ class SpacedRepetitionScheduler:kp_type = progress.knowledge_types.get(kp_id, KnowledgeType.MEMORY)self.hydrate(state, kp_type)old_desired = validate_desired_retention(state.desired_retention)- ratio = -math.log(desired) / -math.log(old_desired)- anchor = state.last_review_at+ anchor = state.last_scheduled_at+ state.desired_retention = desiredif anchor is not None:- state.next_review_at = anchor + (state.next_review_at - anchor) * ratio+ 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- state.desired_retention = desiredprogress.desired_retention = desiredprogress.review_queue = self.build_review_queue(progress, now=moment)diff --git a/deeptutor/learning/service.py b/deeptutor/learning/service.pyindex cfe3970ae..f8ff4074f 100644--- a/deeptutor/learning/service.py+++ b/deeptutor/learning/service.py@@ -1286,7 +1286,10 @@ class LearningService:elif events:progress.repetition_states[kp_id] = scheduler.replay(kp_type,- sorted(events, key=lambda item: item.timestamp),+ # Live transitions follow durable append order. A linked+ # assessment can arrive after a newer one with an older source+ # timestamp; sorting it here would make repair diverge (#1541).+ events,desired_retention=progress.desired_retention,)else:diff --git a/deeptutor/learning/tests/test_scheduler.py b/deeptutor/learning/tests/test_scheduler.pyindex 4739cf5fc..93b8edf80 100644--- a/deeptutor/learning/tests/test_scheduler.py+++ b/deeptutor/learning/tests/test_scheduler.py@@ -331,7 +331,7 @@ class TestBuildReviewQueue:LearningEvidence(evidence_id="reading-attempt-42",knowledge_point_id="kp1",- timestamp=now,+ timestamp=now - 2 * 86400,source="immersive_reading",result="correct",),@@ -466,6 +466,49 @@ class TestRetentionBaseline:assert progress.desired_retention == state.desired_retention == 0.7assert progress.review_queue[0].due_at == state.next_review_at+ def test_replay_matches_live_after_retention_change(self, scheduler):+ start = 1_700_000_000.0+ events = [+ _evidence(quality=1.0, ts=start),+ _evidence(quality=1.0, ts=start + 7 * 86400),+ ]+ progress = LearningProgress(book_id="changed-target")+ progress.knowledge_types["kp1"] = KnowledgeType.CONCEPT+ live = scheduler.get_initial_state(KnowledgeType.CONCEPT, now=start)+ for event in events:+ scheduler.schedule_review(live, KnowledgeType.CONCEPT, event)+ progress.repetition_states["kp1"] = live+ stability_before = live.stability++ scheduler.set_desired_retention(progress, 0.97, now=events[-1].timestamp)+ replayed = scheduler.replay(KnowledgeType.CONCEPT, events, desired_retention=0.97)++ assert live.stability == stability_before+ assert replayed.model_dump() == live.model_dump()++ def test_late_evidence_after_target_change_replays_in_append_order(self, scheduler):+ start = 1_700_000_000.0+ events = [+ _evidence(quality=1.0, ts=start),+ _evidence(quality=0.0, result="incorrect", ts=start + 7 * 86400),+ ]+ progress = LearningProgress(book_id="late-evidence")+ progress.knowledge_types["kp1"] = KnowledgeType.CONCEPT+ live = scheduler.get_initial_state(KnowledgeType.CONCEPT, now=start)+ for event in events:+ scheduler.schedule_review(live, KnowledgeType.CONCEPT, event)+ progress.repetition_states["kp1"] = live+ scheduler.set_desired_retention(progress, 0.97, now=events[-1].timestamp)+ due_after_failure = live.next_review_at++ late = _evidence(quality=1.0, ts=start + 86400)+ events.append(late)+ scheduler.schedule_review(live, KnowledgeType.CONCEPT, late)+ assert live.last_review_at == start + 7 * 86400+ assert live.next_review_at == due_after_failure+ replayed = scheduler.replay(KnowledgeType.CONCEPT, events, desired_retention=0.97)+ assert replayed.model_dump() == live.model_dump()+@pytest.mark.parametrize("invalid", [0.5, 1.0, float("nan"), float("inf")])def test_invalid_retention_is_rejected(self, scheduler, invalid):with pytest.raises(ValueError):diff --git a/deeptutor/learning/tests/test_storage.py b/deeptutor/learning/tests/test_storage.pyindex 56726dfeb..1d59e77af 100644--- a/deeptutor/learning/tests/test_storage.py+++ b/deeptutor/learning/tests/test_storage.py@@ -310,6 +310,70 @@ class TestSaveLoad:assert [item.model_dump() for item in restarted.learning_evidence] == [event.model_dump()]assert store.count_learning_evidence("legacy-review") == 1+ def test_changed_retention_and_late_evidence_replay_after_restart(self, store, tmp_path):+ from deeptutor.learning.models import LearningEvidence+ from deeptutor.learning.scheduler import SpacedRepetitionScheduler++ start = 1_700_000_000.0+ scheduler = SpacedRepetitionScheduler()+ progress = LearningProgress(book_id="late-srs")+ progress.knowledge_types["kp1"] = KnowledgeType.CONCEPT+ state = scheduler.get_initial_state(KnowledgeType.CONCEPT, now=start)+ first = LearningEvidence(+ evidence_id="guided-first",+ knowledge_point_id="kp1",+ timestamp=start,+ result="correct",+ quality=1.0,+ )+ second = LearningEvidence(+ evidence_id="guided-second",+ knowledge_point_id="kp1",+ timestamp=start + 7 * 86400,+ result="incorrect",+ quality=0.0,+ )+ for event in (first, second):+ progress.learning_evidence.append(event)+ scheduler.schedule_review(state, KnowledgeType.CONCEPT, event)+ progress.repetition_states["kp1"] = state+ store.save(progress)++ changed = LearningStore(root=tmp_path).load("late-srs")+ assert changed is not None+ scheduler.set_desired_retention(changed, 0.97, now=second.timestamp)+ store.save(changed)++ reopened = LearningStore(root=tmp_path).load("late-srs")+ assert reopened is not None+ late = LearningEvidence(+ evidence_id="late-book-attempt",+ knowledge_point_id="kp1",+ timestamp=start + 86400,+ source="book",+ result="correct",+ quality=1.0,+ )+ reopened.learning_evidence.append(late)+ scheduler.schedule_review(reopened.repetition_states["kp1"], KnowledgeType.CONCEPT, late)+ reopened.review_queue = scheduler.build_review_queue(reopened, now=second.timestamp)+ store.save(reopened)++ restarted = LearningStore(root=tmp_path).load("late-srs")+ assert restarted is not None+ replayed = scheduler.replay(+ KnowledgeType.CONCEPT,+ restarted.learning_evidence,+ desired_retention=restarted.desired_retention,+ )+ assert restarted.repetition_states["kp1"].model_dump() == replayed.model_dump()+ assert [item.evidence_id for item in restarted.learning_evidence] == [+ "guided-first",+ "guided-second",+ "late-book-attempt",+ ]+ assert restarted.review_queue[0].evidence_id == "late-book-attempt"+def test_updated_at_auto_updates(self, store):lp = LearningProgress(book_id="book1")old_updated = lp.updated_at