Skip to content

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

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.py
index 843e8b396..9e3e928e3 100644
--- a/deeptutor/learning/models.py
+++ b/deeptutor/learning/models.py
@@ -195,6 +195,11 @@ class RepetitionState(BaseModel):
review_count: int = 0
lapse_count: int = 0
last_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 = False
class ReviewTask(BaseModel):
diff --git a/deeptutor/learning/scheduler.py b/deeptutor/learning/scheduler.py
index 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 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 + 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 None
else 0.0
)
+ same_session_days = min(
+ _SAME_SESSION_DAYS,
+ self._interval_from_stability(previous_stability, DEFAULT_DESIRED_RETENTION) * 0.5,
+ )
if (
quality >= _FAIL_QUALITY
and 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 += 1
state.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] = event
tasks: 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 = desired
if 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 = desired
progress.desired_retention = desired
progress.review_queue = self.build_review_queue(progress, now=moment)
diff --git a/deeptutor/learning/service.py b/deeptutor/learning/service.py
index 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.py
index 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.7
assert 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.py
index 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