DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(learning): make review timing and retention settings consistent (#1541)
Bingxi Zhao (Frank)8b08debd7cb8
diff --git a/deeptutor/api/routers/mastery_path.py b/deeptutor/api/routers/mastery_path.pyindex bca5270fc..07c80e3d3 100644--- a/deeptutor/api/routers/mastery_path.py+++ b/deeptutor/api/routers/mastery_path.py@@ -170,6 +170,12 @@ class RenamePathRequest(BaseModel):name: str = ""+class ReviewSettingsRequest(BaseModel):+ """A per-path recall target; higher values schedule shorter intervals."""++ desired_retention: float = Field(..., ge=0.7, le=0.99, allow_inf_nan=False)++class ChapterImport(BaseModel):title: strknowledge_points: list[str] = []@@ -256,6 +262,8 @@ def _review_queue(progress, *, now: float | None = None) -> list[dict]:"due": task.due_at <= moment,"forgetting_risk": round(task.forgetting_risk, 3),"reason": task.reason,+ "evidence_source": task.evidence_source,+ "evidence_id": task.evidence_id,"stability": round(task.state.stability, 3),"retrievability": round(scheduler.retrievability(task.state, now=moment), 3),"desired_retention": task.state.desired_retention,@@ -324,6 +332,10 @@ def _topic_payload_from_snapshot().to_dict(),"map": learning_policy.map_summary(projected, now=moment),"reviews": _review_queue(projected, now=moment),+ "review_settings": {+ "desired_retention": progress.desired_retention,+ "scope": "path",+ },# Who this goal is for. Null until intake has happened, which is also# what the dashboard renders as "not asked yet"."learner_profile": (@@ -491,6 +503,45 @@ async def get_topic(path_id: str):return await asyncio.to_thread(_topic_payload, LearningStore(), path_id)[email protected]("/topics/{path_id}/review-settings")+async def get_review_settings(path_id: str):+ _validate_book_id(path_id)+ progress = await asyncio.to_thread(LearningStore().load, path_id)+ if progress is None:+ raise HTTPException(status_code=404, detail="Mastery topic not found")+ return {"desired_retention": progress.desired_retention, "scope": "path"}++[email protected]("/topics/{path_id}/review-settings")+async def update_review_settings(path_id: str, body: ReviewSettingsRequest):+ _validate_book_id(path_id)+ if not await asyncio.to_thread(LearningStore().exists, path_id):+ raise HTTPException(status_code=404, detail="Mastery topic not found")+ async with _exclusive_path_mutation(path_id):+ store = LearningStore()++ def update(tx):+ from deeptutor.learning.scheduler import SpacedRepetitionScheduler++ if tx.progress.desired_retention == body.desired_retention and all(+ state.desired_retention == body.desired_retention+ for state in tx.progress.repetition_states.values()+ ):+ return+ SpacedRepetitionScheduler().set_desired_retention(tx.progress, body.desired_retention)+ tx.touch()+ tx.emit(+ "review.settings_changed",+ {"desired_retention": tx.progress.desired_retention},+ )++ try:+ await asyncio.to_thread(store.mutate, path_id, update)+ except KeyError as exc:+ raise HTTPException(status_code=404, detail="Mastery topic not found") from exc+ return await asyncio.to_thread(_topic_payload, LearningStore(), path_id)++@router.put("/topics/{path_id}/map")async def edit_topic_map(path_id: str, body: EditTopicMapRequest):_validate_book_id(path_id)diff --git a/deeptutor/learning/models.py b/deeptutor/learning/models.pyindex 34a37ea57..843e8b396 100644--- a/deeptutor/learning/models.py+++ b/deeptutor/learning/models.py@@ -155,8 +155,9 @@ class ErrorRecord(BaseModel):class LearningEvidence(BaseModel):"""One durable review/assessment event that can recompute retention state.- Mastery Path is the only writer in this phase. Quality is a normalized- 0..1 review strength inferred from the outcome (not a learner self-rating).+ Quality is a normalized 0..1 review strength inferred from the outcome+ (not a learner self-rating). Trusted linked assessments may originate in+ another learning surface."""model_config = ConfigDict(extra="ignore")@@ -207,6 +208,8 @@ class ReviewTask(BaseModel):state: RepetitionStateforgetting_risk: float = 0.0reason: str = ""+ evidence_source: str = ""+ evidence_id: str = ""class PendingOption(BaseModel):@@ -498,6 +501,9 @@ class LearningProgress(BaseModel):# Durable review history used to recompute retention. Distinct from# ``quiz_attempts`` (mastery evidence) so the two can evolve separately.learning_evidence: list[LearningEvidence] = Field(default_factory=list)+ # One target per learning path; older aggregates load at the baseline 0.9.+ # It is copied into each repetition state when that state is created.+ desired_retention: float = Field(default=0.9, ge=0.7, le=0.99, allow_inf_nan=False)repetition_states: dict[str, RepetitionState] = Field(default_factory=dict)review_queue: list[ReviewTask] = Field(default_factory=list)# A learner may explicitly claim prior mastery. Policy exposes this as adiff --git a/deeptutor/learning/scheduler.py b/deeptutor/learning/scheduler.pyindex d055bcef4..d461900b9 100644--- a/deeptutor/learning/scheduler.py+++ b/deeptutor/learning/scheduler.py@@ -35,9 +35,30 @@ _TYPE_DIFFICULTY: dict[KnowledgeType, float] = {}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+# Answers repeated before the next due time within one study session are+# practice, not evidence of another durable retrieval (#1541).+_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 desiredclass RetentionScheduler(Protocol):@@ -46,7 +67,11 @@ class RetentionScheduler(Protocol):"""def get_initial_state(- self, knowledge_type: KnowledgeType, *, now: float | None = None+ self,+ knowledge_type: KnowledgeType,+ *,+ now: float | None = None,+ desired_retention: float | None = None,) -> RepetitionState: ...def schedule_review(@@ -79,6 +104,8 @@ class RetentionScheduler(Protocol):evidence: list[LearningEvidence],*,now: float | None = None,+ desired_retention: float | None = None,+ initial_state: RepetitionState | None = None,) -> RepetitionState: ...@@ -97,9 +124,10 @@ def review_sort_key(task: ReviewTask, *, now: float) -> tuple[float, float, int]class SpacedRepetitionScheduler:- def __init__(self) -> None:+ 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@@ -139,12 +167,20 @@ class SpacedRepetitionScheduler:return statedef get_initial_state(- self, knowledge_type: KnowledgeType, *, now: float | None = None+ 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 = DEFAULT_DESIRED_RETENTION+ desired = (+ self.desired_retention+ if desired_retention is None+ else validate_desired_retention(desired_retention)+ )return RepetitionState(interval_index=0,consecutive_correct=0,@@ -179,7 +215,7 @@ class SpacedRepetitionScheduler:now: float | None = None,) -> RepetitionState:self.hydrate(state, knowledge_type)- moment = time.time() if now is None else now+ moment = evidence.timestamp if now is None else nowquality = _resolved_quality(evidence)intervals = INTERVAL_SEQUENCES[knowledge_type]max_index = len(intervals) - 1@@ -195,6 +231,19 @@ class SpacedRepetitionScheduler:if state.last_review_at is not Noneelse 0.0)+ if (+ quality >= _FAIL_QUALITY+ and state.last_review_at is not None+ and elapsed_days < _SAME_SESSION_DAYS+ and moment < state.next_review_at+ ):+ # 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 statespacing_ratio = min(elapsed_days / previous_stability, 4.0)# Difficulty is an item/learner estimate, not the knowledge-type@@ -281,6 +330,7 @@ class SpacedRepetitionScheduler:kp_id: str,*,now: float | None = None,+ latest_evidence: LearningEvidence | None = None,) -> str:moment = time.time() if now is None else nowunit = self._seconds_per_unit()@@ -303,6 +353,10 @@ class SpacedRepetitionScheduler: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]:@@ -316,12 +370,18 @@ class SpacedRepetitionScheduler:) -> list[ReviewTask]:moment = time.time() if now is None else nowerror_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] = eventtasks: 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}",@@ -331,22 +391,74 @@ class SpacedRepetitionScheduler:priority=priority,state=state,forgetting_risk=round(risk, 4),- reason=self.review_reason(state, progress, kp_id, now=moment),+ 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)+ ratio = -math.log(desired) / -math.log(old_desired)+ anchor = state.last_review_at+ if anchor is not None:+ state.next_review_at = anchor + (state.next_review_at - anchor) * ratio+ 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.next_review_at > moment:+ # Legacy snapshots may lack a review anchor; preserve their+ # overdue position and only scale remaining future time.+ 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)+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 stateif not evidence:- return self.get_initial_state(knowledge_type, now=now)- state = self.get_initial_state(knowledge_type, now=evidence[0].timestamp)+ 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 statediff --git a/deeptutor/learning/service.py b/deeptutor/learning/service.pyindex 2bc00704a..cfe3970ae 100644--- a/deeptutor/learning/service.py+++ b/deeptutor/learning/service.py@@ -513,7 +513,9 @@ class LearningService:if kp_type is not None and scheduler is not None:state = progress.repetition_states.get(knowledge_point_id- ) or scheduler.get_initial_state(kp_type)+ ) or scheduler.get_initial_state(+ kp_type, desired_retention=progress.desired_retention+ )progress.repetition_states[knowledge_point_id] = statescheduler.schedule_review(state, kp_type, evidence)progress.review_queue = scheduler.build_review_queue(progress)@@ -1283,7 +1285,9 @@ class LearningService:progress.repetition_states.pop(kp_id, None)elif events:progress.repetition_states[kp_id] = scheduler.replay(- kp_type, sorted(events, key=lambda item: item.timestamp)+ kp_type,+ sorted(events, key=lambda item: item.timestamp),+ desired_retention=progress.desired_retention,)else:synthesized = [@@ -1301,7 +1305,9 @@ class LearningService:start=1,)]- progress.repetition_states[kp_id] = scheduler.replay(kp_type, synthesized)+ progress.repetition_states[kp_id] = scheduler.replay(+ kp_type, synthesized, desired_retention=progress.desired_retention+ )progress.review_queue = scheduler.build_review_queue(progress)def repair_question(@@ -1688,7 +1694,9 @@ class LearningService:kp_type = progress.knowledge_types.get(kp_id)if kp_type is not None and scheduler is not None:state = progress.repetition_states.get(kp_id) or scheduler.get_initial_state(- kp_type, now=review_evidence.timestamp+ kp_type,+ now=review_evidence.timestamp,+ desired_retention=progress.desired_retention,)progress.repetition_states[kp_id] = statescheduler.schedule_review(diff --git a/deeptutor/learning/storage.py b/deeptutor/learning/storage.pyindex 3c6b2cde1..cfda8f042 100644--- a/deeptutor/learning/storage.py+++ b/deeptutor/learning/storage.py@@ -628,6 +628,8 @@ class LearningStore:conn: sqlite3.Connection,path_id: str,progress: LearningProgress,+ *,+ previous_evidence: list[dict[str, Any]] | None = None,) -> None:"""Mirror aggregate evidence into the query/index table.@@ -637,17 +639,28 @@ class LearningStore:inventing a second evidence identity. Ordinary appends update onlynew rows; shrinking or repairing history removes only the stale tail."""- existing = {- int(row["ordinal"]): str(row["evidence_json"])- for row in conn.execute(- "SELECT ordinal, evidence_json FROM mastery_learning_evidence WHERE path_id = ?",- (path_id,),- ).fetchall()- }+ # Ordinary writes already loaded the previous aggregate. Compare that+ # in-memory snapshot, not a second SELECT of every projection row on+ # every unrelated path edit. Migration/explicit repair passes None and+ # reconciles against the projection itself.+ existing = (+ {+ int(row["ordinal"]): str(row["evidence_json"])+ for row in conn.execute(+ "SELECT ordinal, evidence_json FROM mastery_learning_evidence WHERE path_id = ?",+ (path_id,),+ ).fetchall()+ }+ if previous_evidence is None+ else None+ )for ordinal, evidence in enumerate(progress.learning_evidence):payload = evidence.model_dump(mode="json")+ if previous_evidence is not None and ordinal < len(previous_evidence):+ if previous_evidence[ordinal] == payload:+ continueencoded = json.dumps(payload, ensure_ascii=False)- if existing.get(ordinal) == encoded:+ if existing is not None and existing.get(ordinal) == encoded:continueconn.execute("""@@ -681,12 +694,31 @@ class LearningStore:encoded,),)- if len(existing) > len(progress.learning_evidence):+ previous_length = len(previous_evidence) if previous_evidence is not None else len(existing)+ if previous_length > len(progress.learning_evidence):conn.execute("DELETE FROM mastery_learning_evidence WHERE path_id = ? AND ordinal >= ?",(path_id, len(progress.learning_evidence)),)+ def rebuild_learning_evidence_projection(self, book_id: str) -> None:+ """Explicitly reconcile a path's query index from its durable aggregate."""+ path_id = self._validate_id(book_id)+ self._import_legacy_if_needed(path_id)+ with self._connect() as conn:+ conn.execute("BEGIN IMMEDIATE")+ try:+ row = conn.execute(+ "SELECT state_json, revision FROM mastery_paths WHERE path_id = ?", (path_id,)+ ).fetchone()+ if row is None:+ raise KeyError(path_id)+ self._sync_evidence_projection(conn, path_id, self._progress_from_row(row))+ conn.commit()+ except Exception:+ conn.rollback()+ raise+def _archive_legacy(self, path: Path) -> None:if not path.exists():return@@ -923,7 +955,7 @@ class LearningStore:conn.execute("BEGIN IMMEDIATE")try:row = conn.execute(- "SELECT revision, created_at FROM mastery_paths WHERE path_id = ?",+ "SELECT revision, created_at, state_json FROM mastery_paths WHERE path_id = ?",(path_id,),).fetchone()if row is None:@@ -973,7 +1005,14 @@ class LearningStore:path_id, expected, int(current["revision"]) if current else 0)event_type = "path.saved"- self._sync_evidence_projection(conn, path_id, progress)+ previous_evidence = (+ json.loads(row["state_json"]).get("learning_evidence", [])+ if row is not None+ else []+ )+ self._sync_evidence_projection(+ conn, path_id, progress, previous_evidence=previous_evidence+ )conn.execute("""INSERT INTO mastery_events (@@ -1069,7 +1108,14 @@ class LearningStore:tx.base_revision,int(current["revision"]) if current else 0,)- self._sync_evidence_projection(conn, path_id, tx.progress)+ previous_evidence = (+ json.loads(row["state_json"]).get("learning_evidence", [])+ if row is not None+ else []+ )+ self._sync_evidence_projection(+ conn, path_id, tx.progress, previous_evidence=previous_evidence+ )for event_type, payload, session_id, turn_id in tx.events:conn.execute("""diff --git a/deeptutor/learning/tests/test_api_endpoints.py b/deeptutor/learning/tests/test_api_endpoints.pyindex d8f4bfeea..ef941a7a3 100644--- a/deeptutor/learning/tests/test_api_endpoints.py+++ b/deeptutor/learning/tests/test_api_endpoints.py@@ -1,6 +1,7 @@"""API endpoint tests for the mastery_path router."""import json+import timefrom unittest.mock import AsyncMock, patchfrom fastapi import FastAPI@@ -8,7 +9,13 @@ from fastapi.testclient import TestClientimport pytestfrom deeptutor.api.routers.mastery_path import router, ws_router-from deeptutor.learning.models import LearningProgress, PendingQuestion, QuizAttempt+from deeptutor.learning.models import (+ KnowledgeType,+ LearningProgress,+ PendingQuestion,+ QuizAttempt,+)+from deeptutor.learning.scheduler import SpacedRepetitionSchedulerfrom deeptutor.learning.service import LearningServicefrom deeptutor.learning.storage import LearningStore@@ -48,6 +55,58 @@ def _module_payload(module_id: str = "m1", kp_id: str = "kp1") -> dict:}+def test_path_retention_setting_persists_and_reschedules_review(client, tmp_path):+ store = LearningStore(root=tmp_path)+ progress = LearningProgress(book_id="srs-path", name="SRS path")+ progress.knowledge_types["kp1"] = KnowledgeType.CONCEPT+ scheduler = SpacedRepetitionScheduler()+ state = scheduler.get_initial_state(KnowledgeType.CONCEPT, now=time.time())+ state.last_review_at = time.time()+ state.next_review_at = state.last_review_at + 4 * 86400+ progress.repetition_states["kp1"] = state+ store.save(progress)+ old_due = state.next_review_at++ response = client.put(+ "/api/mastery-paths/topics/srs-path/review-settings",+ json={"desired_retention": 0.97},+ )+ assert response.status_code == 200+ assert response.json()["review_settings"] == {+ "desired_retention": 0.97,+ "scope": "path",+ }+ reloaded = LearningStore(root=tmp_path).load("srs-path")+ assert reloaded is not None+ assert reloaded.desired_retention == 0.97+ assert reloaded.repetition_states["kp1"].desired_retention == 0.97+ assert reloaded.repetition_states["kp1"].next_review_at < old_due+ assert client.get("/api/mastery-paths/topics/srs-path/review-settings").json() == {+ "desired_retention": 0.97,+ "scope": "path",+ }++[email protected]("invalid", [0.5, 1.0, "NaN"])+def test_path_retention_setting_rejects_invalid_values(client, tmp_path, invalid):+ store = LearningStore(root=tmp_path)+ store.save(LearningProgress(book_id="srs-path"))+ response = client.put(+ "/api/mastery-paths/topics/srs-path/review-settings",+ json={"desired_retention": invalid},+ )+ assert response.status_code == 422+ assert store.load("srs-path").desired_retention == 0.9+++def test_path_retention_setting_requires_existing_path(client):+ response = client.put(+ "/api/mastery-paths/topics/missing/review-settings",+ json={"desired_retention": 0.92},+ )+ assert response.status_code == 404++# -- GET /progress (list_all) --------------------------------------------diff --git a/deeptutor/learning/tests/test_guided_mastery_updates.py b/deeptutor/learning/tests/test_guided_mastery_updates.pyindex 145648be3..cdd3c1b3e 100644--- a/deeptutor/learning/tests/test_guided_mastery_updates.py+++ b/deeptutor/learning/tests/test_guided_mastery_updates.py@@ -337,7 +337,8 @@ def test_record_qualitative_updates_existing_review_state(tmp_path, monkeypatch)service.record_qualitative(progress, "kp1", passed=True, scheduler=scheduler)immediate = progress.repetition_states["kp1"]assert immediate.review_count == 2- assert immediate.stability > first_stability+ assert immediate.stability == first_stability+ assert immediate.next_review_at == first_dueimmediate_stability = immediate.stabilitynow[0] = immediate.next_review_atdiff --git a/deeptutor/learning/tests/test_scheduler.py b/deeptutor/learning/tests/test_scheduler.pyindex 64c695d4b..4739cf5fc 100644--- a/deeptutor/learning/tests/test_scheduler.py+++ b/deeptutor/learning/tests/test_scheduler.py@@ -70,17 +70,28 @@ class TestCorrectAdvances:assert state.next_review_at > beforeassert state.last_review_at is not None- def test_two_consecutive_strong_successes_lengthen_more(self, scheduler):+ def test_same_session_success_does_not_extend_due_time(self, scheduler):state = scheduler.get_initial_state(KnowledgeType.MEMORY)state = scheduler.schedule_next(state, KnowledgeType.MEMORY, True)after_one = state.stabilitydue_after_one = state.next_review_atstate = scheduler.schedule_next(state, KnowledgeType.MEMORY, True)- assert state.consecutive_correct == 0- assert state.stability > after_one- assert state.next_review_at > due_after_one+ assert state.consecutive_correct == 1+ assert state.stability == after_one+ assert state.next_review_at == due_after_one+ assert state.review_count == 2assert state.lapse_count == 0+ def test_success_at_due_time_extends_interval(self, scheduler):+ start = 1_700_000_000.0+ state = scheduler.get_initial_state(KnowledgeType.MEMORY, now=start)+ scheduler.schedule_review(state, KnowledgeType.MEMORY, _evidence(quality=1.0, ts=start))+ first_stability = state.stability+ due = state.next_review_at+ scheduler.schedule_review(state, KnowledgeType.MEMORY, _evidence(quality=1.0, ts=due))+ assert state.stability > first_stability+ assert state.next_review_at > due+# ── schedule_next: wrong retreats ────────────────────────────────────────@@ -302,6 +313,36 @@ class TestBuildReviewQueue:assert tasks[0].reasonassert 0.0 <= tasks[0].forgetting_risk <= 1.0+ def test_review_explains_latest_linked_assessment_source(self, scheduler):+ now = 1_700_000_000.0+ progress = LearningProgress(book_id="b1")+ progress.knowledge_types["kp1"] = KnowledgeType.CONCEPT+ progress.repetition_states["kp1"] = scheduler.get_initial_state(+ KnowledgeType.CONCEPT, now=now+ )+ progress.learning_evidence = [+ LearningEvidence(+ evidence_id="older-book-attempt",+ knowledge_point_id="kp1",+ timestamp=now - 86400,+ source="book",+ result="incorrect",+ ),+ LearningEvidence(+ evidence_id="reading-attempt-42",+ knowledge_point_id="kp1",+ timestamp=now,+ source="immersive_reading",+ result="correct",+ ),+ ]++ task = scheduler.build_review_queue(progress, now=now)[0]+ assert task.evidence_source == "immersive_reading"+ assert task.evidence_id == "reading-attempt-42"+ assert "latest Reading assessment: correct" in task.reason+ assert "reading-attempt-42" not in task.reason+# ── adaptive retention baseline ──────────────────────────────────────────@@ -356,6 +397,80 @@ class TestRetentionBaseline:assert delayed.stability > immediate.stabilityassert delayed.difficulty < immediate.difficulty+ def test_six_one_minute_reviews_do_not_turn_into_a_long_interval(self, scheduler):+ start = 1_700_000_000.0+ state = scheduler.get_initial_state(KnowledgeType.CONCEPT, now=start)+ scheduler.schedule_review(state, KnowledgeType.CONCEPT, _evidence(quality=1.0, ts=start))+ first_stability = state.stability+ first_due = state.next_review_at+ for index in range(1, 6):+ scheduler.schedule_review(+ state,+ KnowledgeType.CONCEPT,+ _evidence(quality=1.0, ts=start + index * 60),+ )+ assert state.stability == first_stability+ assert state.next_review_at == first_due+ assert state.review_count == 6++ def test_live_transition_equals_replay_with_path_retention_and_mixed_assessments(+ self, scheduler+ ):+ start = 1_700_000_000.0+ events = [+ LearningEvidence(+ knowledge_point_id="kp1",+ timestamp=start,+ assessment_type="qualitative",+ result="correct",+ quality=0.9,+ ),+ _evidence(quality=1.0, ts=start + 60), # not yet due+ _evidence(quality=0.0, result="incorrect", ts=start + 86400),+ _evidence(quality=1.0, ts=start + 86460),+ _evidence(quality=1.0, ts=start + 8 * 86400),+ ]+ live = scheduler.get_initial_state(KnowledgeType.CONCEPT, now=start, desired_retention=0.82)+ for event in events:+ scheduler.schedule_review(live, KnowledgeType.CONCEPT, event)+ replayed = scheduler.replay(KnowledgeType.CONCEPT, events, desired_retention=0.82)+ assert replayed.model_dump() == live.model_dump()++ def test_replay_from_legacy_starting_state_is_non_mutating(self, scheduler):+ baseline = RepetitionState(+ interval_index=2, next_review_at=1_700_000_000.0, desired_retention=0.85+ )+ event = _evidence(quality=1.0, ts=1_700_000_000.0 + 86400)+ live = baseline.model_copy(deep=True)+ scheduler.schedule_review(live, KnowledgeType.MEMORY, event)+ replayed = scheduler.replay(KnowledgeType.MEMORY, [event], initial_state=baseline)+ assert replayed.model_dump() == live.model_dump()+ assert baseline.stability == 0.0+ assert scheduler.replay(KnowledgeType.MEMORY, [], initial_state=baseline) == baseline++ def test_changing_retention_rescales_existing_due_without_new_review(self, scheduler):+ start = 1_700_000_000.0+ progress = LearningProgress(book_id="b1")+ progress.knowledge_types["kp1"] = KnowledgeType.CONCEPT+ state = scheduler.get_initial_state(KnowledgeType.CONCEPT, now=start)+ scheduler.schedule_review(state, KnowledgeType.CONCEPT, _evidence(quality=1.0, ts=start))+ progress.repetition_states["kp1"] = state+ old_due = state.next_review_at+ review_count = state.review_count+ scheduler.set_desired_retention(progress, 0.97, now=start)+ high_target_due = state.next_review_at+ assert high_target_due < old_due+ scheduler.set_desired_retention(progress, 0.7, now=start)+ assert state.next_review_at > old_due+ assert state.review_count == review_count+ assert progress.desired_retention == state.desired_retention == 0.7+ assert progress.review_queue[0].due_at == state.next_review_at++ @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):+ scheduler.get_initial_state(KnowledgeType.MEMORY, desired_retention=invalid)+def test_replay_matches_stepwise_updates(self, scheduler):now = 1_700_000_000.0events = [diff --git a/deeptutor/learning/tests/test_storage.py b/deeptutor/learning/tests/test_storage.pyindex c37534956..56726dfeb 100644--- a/deeptutor/learning/tests/test_storage.py+++ b/deeptutor/learning/tests/test_storage.py@@ -161,6 +161,67 @@ class TestSaveLoad:"incorrect",]+ def test_unrelated_path_save_does_not_write_historical_evidence(self, store):+ from deeptutor.learning.models import LearningEvidence++ progress = LearningProgress(book_id="unchanged-evidence")+ progress.learning_evidence = [+ LearningEvidence(knowledge_point_id="kp1", quality=0.5, timestamp=float(index))+ for index in range(100)+ ]+ store.save(progress)+ with sqlite3.connect(store.db_path) as conn:+ conn.execute(+ """+ CREATE TRIGGER reject_unchanged_evidence_write+ BEFORE INSERT ON mastery_learning_evidence+ WHEN NEW.path_id = 'unchanged-evidence'+ BEGIN SELECT RAISE(ABORT, 'unrelated write touched evidence'); END+ """+ )+ conn.execute(+ """+ CREATE TRIGGER reject_unchanged_evidence_update+ BEFORE UPDATE ON mastery_learning_evidence+ WHEN NEW.path_id = 'unchanged-evidence'+ BEGIN SELECT RAISE(ABORT, 'unrelated write touched evidence'); END+ """+ )+ conn.execute(+ """+ CREATE TRIGGER reject_unchanged_evidence_delete+ BEFORE DELETE ON mastery_learning_evidence+ WHEN OLD.path_id = 'unchanged-evidence'+ BEGIN SELECT RAISE(ABORT, 'unrelated write touched evidence'); END+ """+ )+ progress.name = "renamed"+ store.save(progress)+ assert store.load("unchanged-evidence").name == "renamed"+ assert store.count_learning_evidence("unchanged-evidence") == 100++ def test_explicit_evidence_projection_rebuild_repairs_missing_rows(self, store):+ from deeptutor.learning.models import LearningEvidence++ progress = LearningProgress(book_id="rebuild-evidence")+ progress.learning_evidence = [+ LearningEvidence(knowledge_point_id="kp1", timestamp=float(index)) for index in range(3)+ ]+ store.save(progress)+ with sqlite3.connect(store.db_path) as conn:+ conn.execute(+ "DELETE FROM mastery_learning_evidence WHERE path_id = ? AND ordinal = 1",+ ("rebuild-evidence",),+ )+ assert store.count_learning_evidence("rebuild-evidence") == 2+ store.rebuild_learning_evidence_projection("rebuild-evidence")+ assert store.count_learning_evidence("rebuild-evidence") == 3+ assert [event.timestamp for event in store.list_learning_evidence("rebuild-evidence")] == [+ 2.0,+ 1.0,+ 0.0,+ ]+def test_existing_paths_receive_evidence_projection_on_upgrade(self, store):from deeptutor.learning.models import LearningEvidence@@ -206,6 +267,49 @@ class TestSaveLoad:assert state.stability == 0.0assert loaded.learning_evidence == []+ def test_legacy_path_review_survives_restart_with_evidence_and_queue(self, store, tmp_path):+ from deeptutor.learning.models import LearningEvidence+ from deeptutor.learning.scheduler import SpacedRepetitionScheduler++ now = 1_700_000_000.0+ (tmp_path / "legacy-review.json").write_text(+ json.dumps(+ {+ "book_id": "legacy-review",+ "mastery_levels": {"kp1": 0.6, "kp2": 0.3},+ "knowledge_types": {"kp1": "memory", "kp2": "concept"},+ "repetition_states": {+ "kp1": {"interval_index": 2, "next_review_at": now},+ "kp2": {"interval_index": 1, "next_review_at": now - 86400},+ },+ }+ ),+ encoding="utf-8",+ )+ progress = store.load("legacy-review")+ assert progress is not None+ scheduler = SpacedRepetitionScheduler()+ event = LearningEvidence(+ knowledge_point_id="kp1",+ timestamp=now + 86400,+ result="correct",+ quality=0.9,+ )+ progress.learning_evidence.append(event)+ scheduler.schedule_review(progress.repetition_states["kp1"], KnowledgeType.MEMORY, event)+ progress.review_queue = scheduler.build_review_queue(progress, now=event.timestamp)+ expected_order = [task.knowledge_point_id for task in progress.review_queue]+ expected_state = progress.repetition_states["kp1"].model_dump()+ store.save(progress)++ restarted = LearningStore(root=tmp_path).load("legacy-review")+ assert restarted is not None+ assert restarted.mastery_levels == {"kp1": 0.6, "kp2": 0.3}+ assert restarted.repetition_states["kp1"].model_dump() == expected_state+ assert [task.knowledge_point_id for task in restarted.review_queue] == expected_order+ assert [item.model_dump() for item in restarted.learning_evidence] == [event.model_dump()]+ assert store.count_learning_evidence("legacy-review") == 1+def test_updated_at_auto_updates(self, store):lp = LearningProgress(book_id="book1")old_updated = lp.updated_atdiff --git a/web/app/(workspace)/learning/mastery/[pathId]/page.tsx b/web/app/(workspace)/learning/mastery/[pathId]/page.tsxindex 369074f58..f0c7303d8 100644--- a/web/app/(workspace)/learning/mastery/[pathId]/page.tsx+++ b/web/app/(workspace)/learning/mastery/[pathId]/page.tsx@@ -49,6 +49,7 @@ import {redoProgress,renameProgress,setMasteryObjectiveOverride,+ updateMasteryReviewSettings,type MasteryTopic,type BoardResult,type TopicSession,@@ -110,6 +111,8 @@ export default function MasteryTopicPage() {const [boardError, setBoardError] = useState(false);const [boardRequestNonce, setBoardRequestNonce] = useState(0);const [mutationBusy, setMutationBusy] = useState(false);+ const [retentionBusy, setRetentionBusy] = useState(false);+ const [retentionError, setRetentionError] = useState<string | null>(null);const editorTriggerRef = useRef<HTMLElement | null>(null);const confirmTriggerRef = useRef<HTMLElement | null>(null);const activity = useMasteryPathActivity(pathId || null);@@ -237,6 +240,20 @@ export default function MasteryTopicPage() {activity.refresh();};+ const handleRetentionChange = async (desiredRetention: number) => {+ setRetentionBusy(true);+ setRetentionError(null);+ try {+ const saved = await updateMasteryReviewSettings(pathId, desiredRetention);+ setTopic(saved);+ activity.refresh();+ } catch {+ setRetentionError(t("Could not save review target. Try again."));+ } finally {+ setRetentionBusy(false);+ }+ };+const handleReset = async () => {setMutationBusy(true);try {@@ -608,6 +625,14 @@ export default function MasteryTopicPage() {</div><ReviewTrailreviews={topic.reviews}+ desiredRetention={+ topic.review_settings?.desired_retention ??+ topic.reviews[0]?.desired_retention ??+ 0.9+ }+ retentionBusy={retentionBusy}+ retentionError={retentionError}+ onRetentionChange={(value) => void handleRetentionChange(value)}zh={zh}onSelect={(objectiveId) => {setSelectedId(objectiveId);diff --git a/web/components/space/learning/ReviewTrail.tsx b/web/components/space/learning/ReviewTrail.tsxindex 87748775b..8653636b3 100644--- a/web/components/space/learning/ReviewTrail.tsx+++ b/web/components/space/learning/ReviewTrail.tsx@@ -1,6 +1,6 @@"use client";-import { ArrowRight, CheckCircle2, Clock3, Play } from "lucide-react";+import { ArrowRight, CheckCircle2, Clock3, Loader2, Play } from "lucide-react";import { useTranslation } from "react-i18next";import { useState } from "react";@@ -8,13 +8,23 @@ import type { TopicReview } from "@/lib/learning-api";import { formatRelative } from "./format";+const RETENTION_TARGETS = [0.7, 0.8, 0.85, 0.9, 0.95, 0.97, 0.99];+export function ReviewTrail({reviews,+ desiredRetention,+ retentionBusy,+ retentionError,+ onRetentionChange,zh,onSelect,onStartReview,}: {reviews: TopicReview[];+ desiredRetention: number;+ retentionBusy: boolean;+ retentionError: string | null;+ onRetentionChange: (value: number) => void;zh: boolean;onSelect: (objectiveId: string) => void;onStartReview: (objectiveId: string, name: string) => void;@@ -30,19 +40,54 @@ export function ReviewTrail({: left.due_at - right.due_at),);const visible = expanded ? ordered : ordered.slice(0, 5);+ const retentionTargets = RETENTION_TARGETS.includes(desiredRetention)+ ? RETENTION_TARGETS+ : [...RETENTION_TARGETS, desiredRetention].sort((a, b) => a - b);return (<section className="overflow-hidden rounded-xl border border-[var(--border)] bg-[var(--card)]">- <div className="flex items-center justify-between gap-3 border-b border-[var(--border)] bg-[var(--secondary)] px-4 py-2.5">+ <div className="flex flex-wrap items-center justify-between gap-3 border-b border-[var(--border)] bg-[var(--secondary)] px-4 py-2.5"><h2className="text-[12px] font-semibold text-[var(--foreground)]"title={t("Scheduled by your forgetting curve")}>{t("Review plan")}</h2>- <span className="text-[11px] tabular-nums text-[var(--muted-foreground)]">- {due.length} {t("due")}- </span>+ <div className="flex items-center gap-3">+ <label className="flex items-center gap-1.5 text-[11px] text-[var(--muted-foreground)]">+ <span>{t("Recall target")}</span>+ <select+ value={desiredRetention}+ onChange={(event) => onRetentionChange(Number(event.target.value))}+ disabled={retentionBusy}+ aria-describedby="review-retention-hint"+ className="h-7 rounded-md border border-[var(--border)] bg-[var(--card)] px-1.5 text-[11px] font-medium tabular-nums text-[var(--foreground)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)]/40 disabled:opacity-60"+ >+ {retentionTargets.map((target) => (+ <option key={target} value={target}>+ {Math.round(target * 1000) / 10}%+ </option>+ ))}+ </select>+ </label>+ {retentionBusy && (+ <span className="inline-flex items-center gap-1 text-[11px] text-[var(--muted-foreground)]">+ <Loader2 className="h-3 w-3 animate-spin" aria-hidden="true" />+ <span className="sr-only">{t("Saving…")}</span>+ </span>+ )}+ <span className="text-[11px] tabular-nums text-[var(--muted-foreground)]">+ {due.length} {t("due")}+ </span>+ </div></div>+ <p id="review-retention-hint" className="px-4 pt-2 text-[10px] text-[var(--muted-foreground)]">+ {t("Higher targets schedule reviews sooner.")}+ </p>+ {retentionError && (+ <p role="alert" className="px-4 pt-1 text-[11px] text-red-600 dark:text-red-400">+ {retentionError}+ </p>+ )}{reviews.length === 0 ? (<div className="flex items-start gap-2 px-4 py-3.5 text-[12px] leading-5 text-[var(--muted-foreground)]"><CheckCircle2 className="mt-0.5 h-3.5 w-3.5 shrink-0 text-[var(--primary)]" />diff --git a/web/lib/learning-api.ts b/web/lib/learning-api.tsindex 910df1f7a..1dc6e3658 100644--- a/web/lib/learning-api.ts+++ b/web/lib/learning-api.ts@@ -463,6 +463,13 @@ export interface TopicReview {desired_retention: number;lapse_count: number;recent_failure: boolean;+ evidence_source?: string;+ evidence_id?: string;+}++export interface MasteryReviewSettings {+ desired_retention: number;+ scope: "path";}export interface MasteryTopic extends LearningOrigin {@@ -474,6 +481,7 @@ export interface MasteryTopic extends LearningOrigin {next: NextStep;map: MasteryMap;reviews: TopicReview[];+ review_settings?: MasteryReviewSettings;/** Null until the tutor has asked the learner about themselves. */learner_profile: LearnerProfile | null;session_count: number;@@ -641,6 +649,21 @@ export function fetchMasteryTopic();}+export function updateMasteryReviewSettings(+ pathId: string,+ desiredRetention: number,+): Promise<MasteryTopic> {+ return masteryJson(+ `/api/mastery-paths/topics/${encodeURIComponent(pathId)}/review-settings`,+ {+ method: "PUT",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify({ desired_retention: desiredRetention }),+ },+ "update review target",+ );+}+/** Change what a conversation is doing, from the learner's own mode buttons. */export async function setMasterySessionMode(pathId: string,diff --git a/web/locales/en/app.json b/web/locales/en/app.jsonindex 4c0a09fe9..644f6cf23 100644--- a/web/locales/en/app.json+++ b/web/locales/en/app.json@@ -2901,6 +2901,8 @@"Previous {{unit}}": "Previous {{unit}}","Next {{unit}}": "Next {{unit}}","Change reading theme": "Change reading theme",+ "Switch to two-page spread": "Switch to two-page spread",+ "Switch to single-page view": "Switch to single-page view","That annotation could not be saved.": "That annotation could not be saved.","That annotation could not be removed.": "That annotation could not be removed.","Bookmarks": "Bookmarks",@@ -3204,6 +3206,9 @@"Topic name": "Topic name","What is this path called?": "What is this path called?","Review plan": "Review plan",+ "Recall target": "Recall target",+ "Higher targets schedule reviews sooner.": "Higher targets schedule reviews sooner.",+ "Could not save review target. Try again.": "Could not save review target. Try again.","masteryMode.outline": "Outline","masteryMode.study": "Study","masteryMode.review": "Review",diff --git a/web/locales/fr/app.json b/web/locales/fr/app.jsonindex 9fb92a687..ae459a08b 100644--- a/web/locales/fr/app.json+++ b/web/locales/fr/app.json@@ -3429,6 +3429,8 @@"Use serif font": "Utiliser une police à empattement","Change line width": "Changer la largeur de ligne","Change reading theme": "Changer le thème de lecture",+ "Switch to two-page spread": "Passer à l'affichage sur deux pages",+ "Switch to single-page view": "Passer à l'affichage sur une page","That annotation could not be saved.": "Cette annotation n'a pas pu être enregistrée.","That annotation could not be removed.": "Cette annotation n'a pas pu être supprimée.","Explain this passage": "Expliquer ce passage",@@ -3810,6 +3812,9 @@"Topic name": "Nom du sujet","What is this path called?": "Comment s'appelle ce parcours ?","Review plan": "Plan de révision",+ "Recall target": "Objectif de rappel",+ "Higher targets schedule reviews sooner.": "Un objectif plus élevé avance les prochaines révisions.",+ "Could not save review target. Try again.": "Impossible d'enregistrer l'objectif de révision. Réessayez.","Scheduled by your forgetting curve": "Planifié selon votre courbe d'oubli","Nothing is due today. Keep going — reviews will resurface at the right time.": "Rien n'est dû aujourd'hui. Continuez — les révisions réapparaîtront au bon moment.","Ready now": "Prêt maintenant",diff --git a/web/locales/zh/app.json b/web/locales/zh/app.jsonindex aa54acc82..934623290 100644--- a/web/locales/zh/app.json+++ b/web/locales/zh/app.json@@ -2901,6 +2901,8 @@"Previous {{unit}}": "上一{{unit}}","Next {{unit}}": "下一{{unit}}","Change reading theme": "切换阅读主题",+ "Switch to two-page spread": "切换到双页排版",+ "Switch to single-page view": "切换到单页排版","That annotation could not be saved.": "这条标注保存失败。","That annotation could not be removed.": "这条标注删除失败。","Bookmarks": "书签",@@ -3204,6 +3206,9 @@"Topic name": "目标名称","What is this path called?": "这条路叫什么?","Review plan": "复习计划",+ "Recall target": "记忆保持目标",+ "Higher targets schedule reviews sooner.": "目标越高,复习间隔越短。",+ "Could not save review target. Try again.": "无法保存复习目标,请重试。","masteryMode.outline": "编辑大纲","masteryMode.study": "学习","masteryMode.review": "复习",