Skip to content

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

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.py
index 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: str
knowledge_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.py
index 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: RepetitionState
forgetting_risk: float = 0.0
reason: 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 a
diff --git a/deeptutor/learning/scheduler.py b/deeptutor/learning/scheduler.py
index 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 desired
class 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 state
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:
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 now
quality = _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 None
else 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 state
spacing_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 now
unit = 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 now
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
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}",
@@ -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 state
if 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 state
diff --git a/deeptutor/learning/service.py b/deeptutor/learning/service.py
index 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] = state
scheduler.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] = state
scheduler.schedule_review(
diff --git a/deeptutor/learning/storage.py b/deeptutor/learning/storage.py
index 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 only
new 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:
+ continue
encoded = json.dumps(payload, ensure_ascii=False)
- if existing.get(ordinal) == encoded:
+ if existing is not None and existing.get(ordinal) == encoded:
continue
conn.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.py
index 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 time
from unittest.mock import AsyncMock, patch
from fastapi import FastAPI
@@ -8,7 +9,13 @@ from fastapi.testclient import TestClient
import pytest
from 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 SpacedRepetitionScheduler
from deeptutor.learning.service import LearningService
from 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.py
index 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_due
immediate_stability = immediate.stability
now[0] = immediate.next_review_at
diff --git a/deeptutor/learning/tests/test_scheduler.py b/deeptutor/learning/tests/test_scheduler.py
index 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 > before
assert 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.stability
due_after_one = state.next_review_at
state = 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 == 2
assert 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].reason
assert 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.stability
assert 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.0
events = [
diff --git a/deeptutor/learning/tests/test_storage.py b/deeptutor/learning/tests/test_storage.py
index 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.0
assert 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_at
diff --git a/web/app/(workspace)/learning/mastery/[pathId]/page.tsx b/web/app/(workspace)/learning/mastery/[pathId]/page.tsx
index 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>
<ReviewTrail
reviews={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.tsx
index 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">
<h2
className="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.ts
index 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.json
index 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.json
index 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.json
index 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": "复习",