Skip to content

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

fix(learning): persist cross-surface assessment evidence safely (#1542)

Bingxi Zhao (Frank)02cef7596a72
diff --git a/deeptutor/api/main.py b/deeptutor/api/main.py
index c19b3518c..2faba24fa 100644
--- a/deeptutor/api/main.py
+++ b/deeptutor/api/main.py
@@ -152,6 +152,15 @@ async def lifespan(app: FastAPI):
len(migration_reports["workspace_preferences"]),
)
+ try:
+ from deeptutor.learning.assessment import reconcile_linked_assessments
+
+ recovered, failed = await reconcile_linked_assessments()
+ if recovered or failed:
+ logger.info("Linked assessment recovery: recovered=%s failed=%s", recovered, failed)
+ except Exception:
+ logger.exception("Failed to reconcile linked assessments at startup")
+
# Initialize LLM client early so OPENAI_* env vars are available before
# any downstream provider integrations start.
try:
diff --git a/deeptutor/api/routers/book.py b/deeptutor/api/routers/book.py
index de5d18535..0deca5eb4 100644
--- a/deeptutor/api/routers/book.py
+++ b/deeptutor/api/routers/book.py
@@ -162,6 +162,7 @@ class QuizAttemptRequest(BaseModel):
# ``None`` = revealed but not graded (a written answer the reader skipped
# self-assessing). Distinct from ``False``, which means they got it wrong.
is_correct: bool | None = None
+ submission_id: str = Field(default="", max_length=200)
def _focus_check_question(
@@ -181,6 +182,21 @@ def _focus_check_question(
return None
+def _verified_choice_grade(question: dict[str, Any], user_answer: str) -> bool | None:
+ """A linked Book answer is trusted only when the stored key can grade it."""
+ if str(question.get("question_type") or "").strip().lower() != "choice":
+ return None
+ options = question.get("options")
+ if not isinstance(options, dict):
+ return None
+ answer = user_answer.strip().upper()
+ correct = str(question.get("correct_answer") or "").strip().upper()
+ keys = {str(key).strip().upper() for key in options}
+ if answer not in keys or correct not in keys:
+ return None
+ return answer == correct
+
+
class UpdateBlockRequest(BaseModel):
book_id: str
page_id: str
@@ -1088,22 +1104,31 @@ async def quiz_attempt(req: QuizAttemptRequest) -> dict[str, Any]:
else []
)
resolved_question = _focus_check_question(questions, req.question_id, req.block_id)
- progress = progress_ops.record_attempt(
- resolved.load_progress(req.book_id),
- page_id=req.page_id,
- block_id=req.block_id,
- question_id=req.question_id,
- user_answer=req.user_answer,
- is_correct=req.is_correct,
- page_to_chapter={
- page.id: page.chapter_id
- for page in resolved.engine.list_pages(req.book_id)
- if page.chapter_id
- },
- )
- resolved.learning.save_progress(progress)
+ current_progress = resolved.load_progress(req.book_id)
+ previous_attempts = len(current_progress.quiz_attempts)
+ try:
+ progress = progress_ops.record_attempt(
+ current_progress,
+ page_id=req.page_id,
+ block_id=req.block_id,
+ question_id=req.question_id,
+ user_answer=req.user_answer,
+ is_correct=req.is_correct,
+ page_to_chapter={
+ page.id: page.chapter_id
+ for page in resolved.engine.list_pages(req.book_id)
+ if page.chapter_id
+ },
+ submission_id=req.submission_id.strip(),
+ )
+ except ValueError as exc:
+ raise HTTPException(status_code=409, detail=str(exc)) from exc
+ if len(progress.quiz_attempts) != previous_attempts:
+ resolved.learning.save_progress(progress)
if req.is_correct is not None and resolved_question is not None and book is not None:
question_id, question = resolved_question
+ verified_grade = _verified_choice_grade(question, req.user_answer)
+ trusted_linkage = verified_grade is not None and verified_grade == req.is_correct
try:
from deeptutor.services.session import get_sqlite_session_store
@@ -1122,12 +1147,20 @@ async def quiz_attempt(req: QuizAttemptRequest) -> dict[str, Any]:
record_assessment,
)
- latest_attempt = progress.quiz_attempts[-1]
- attempt_count = sum(
- 1
+ matching_attempts = [
+ attempt
for attempt in progress.quiz_attempts
if attempt.block_id == req.block_id and attempt.question_id == req.question_id
+ ]
+ latest_attempt = next(
+ (
+ attempt
+ for attempt in matching_attempts
+ if req.submission_id and attempt.submission_id == req.submission_id
+ ),
+ matching_attempts[-1],
)
+ attempt_count = matching_attempts.index(latest_attempt) + 1
await record_assessment(
AssessmentRecord(
session_id=session_id if has_session else "",
@@ -1150,22 +1183,29 @@ async def quiz_attempt(req: QuizAttemptRequest) -> dict[str, Any]:
material_title=book.title,
section_id=req.page_id,
section_title=page.title if page is not None else "",
- mastery_path_id=str(question.get("mastery_path_id") or ""),
- knowledge_point_id=str(question.get("knowledge_point_id") or ""),
- attempt_count=max(1, attempt_count),
+ mastery_path_id=(
+ str(question.get("mastery_path_id") or "") if trusted_linkage else ""
+ ),
+ knowledge_point_id=(
+ str(question.get("knowledge_point_id") or "") if trusted_linkage else ""
+ ),
+ attempt_count=attempt_count,
attempt_id=(
f"book:{req.book_id}:{req.block_id}:{question_id}:"
- f"{latest_attempt.timestamp:.9f}"
+ f"{latest_attempt.submission_id or f'{latest_attempt.timestamp:.9f}'}"
),
)
)
- except Exception:
+ except Exception as exc:
logger.warning(
"Failed to sync Focus-Check %s to question bank for book %s",
req.question_id,
req.book_id,
exc_info=True,
)
+ raise HTTPException(
+ status_code=500, detail="Failed to save Focus-Check evidence"
+ ) from exc
return {"progress": progress.model_dump(mode="json")}
diff --git a/deeptutor/api/routers/reading_extensions.py b/deeptutor/api/routers/reading_extensions.py
index 86899562a..c178ae3da 100644
--- a/deeptutor/api/routers/reading_extensions.py
+++ b/deeptutor/api/routers/reading_extensions.py
@@ -69,6 +69,7 @@ class QuizAnswersPayload(BaseModel):
section_title: str = Field(default="", max_length=500)
session_id: str = ""
turn_id: str = ""
+ submission_id: str = Field(default="", max_length=200)
answers: list[QuizAnswerItem] = Field(min_length=1)
@@ -315,6 +316,12 @@ async def submit_quiz_answers(material_id: str, payload: QuizAnswersPayload) ->
str(choices[item.selected_index]) if 0 <= item.selected_index < len(choices) else ""
)
correct_text = str(choices[correct_index]) if 0 <= correct_index < len(choices) else ""
+ submission_id = payload.submission_id.strip()
+ attempt_id = (
+ f"reading:{material_id}:{payload.locator}:{item.question_id.strip()}:{submission_id}"
+ if submission_id
+ else ""
+ )
try:
await record_assessment(
AssessmentRecord(
@@ -338,6 +345,7 @@ async def submit_quiz_answers(material_id: str, payload: QuizAnswersPayload) ->
section_title=section_title,
mastery_path_id=str(question.get("mastery_path_id") or ""),
knowledge_point_id=str(question.get("knowledge_point_id") or ""),
+ attempt_id=attempt_id,
)
)
except RecordAssessmentError as exc:
diff --git a/deeptutor/book/models.py b/deeptutor/book/models.py
index bb38b5152..a58d37447 100644
--- a/deeptutor/book/models.py
+++ b/deeptutor/book/models.py
@@ -490,6 +490,7 @@ class QuizAttempt(BaseModel):
# the reader, and folding "not graded" into "wrong" would both understate
# their score and mark the chapter weak on nothing but a reveal.
is_correct: bool | None = None
+ submission_id: str = ""
timestamp: float = Field(default_factory=_now)
diff --git a/deeptutor/book/progress.py b/deeptutor/book/progress.py
index a91e55c35..8d2c8e7af 100644
--- a/deeptutor/book/progress.py
+++ b/deeptutor/book/progress.py
@@ -76,8 +76,22 @@ def record_attempt(
user_answer: str,
is_correct: bool | None,
page_to_chapter: dict[str, str],
+ submission_id: str = "",
) -> Progress:
"""Append an attempt and refresh everything derived from the set."""
+ if submission_id:
+ for existing in progress.quiz_attempts:
+ if existing.submission_id != submission_id:
+ continue
+ if (
+ existing.page_id != page_id
+ or existing.block_id != block_id
+ or existing.question_id != question_id
+ or existing.user_answer != user_answer
+ or existing.is_correct != is_correct
+ ):
+ raise ValueError("Submission id was reused for a different quiz answer")
+ return progress
progress.quiz_attempts.append(
QuizAttempt(
block_id=block_id,
@@ -85,6 +99,7 @@ def record_attempt(
question_id=question_id,
user_answer=user_answer,
is_correct=is_correct,
+ submission_id=submission_id,
)
)
progress.score = recompute_score(progress)
diff --git a/deeptutor/learning/assessment.py b/deeptutor/learning/assessment.py
index 63cca3573..ad11210e1 100644
--- a/deeptutor/learning/assessment.py
+++ b/deeptutor/learning/assessment.py
@@ -277,6 +277,20 @@ def _apply_linkage(record: AssessmentRecord, diagnostics: list[str]) -> tuple[st
return "", ""
+def _is_trusted_linkage(path_id: str, knowledge_point_id: str) -> bool:
+ """Only a saved path's exact objective can consume cross-surface evidence."""
+ from deeptutor.learning.policy import find_knowledge_point
+
+ try:
+ progress = _get_learning_store().load(path_id)
+ except (OSError, ValueError):
+ return False
+ if progress is None or progress.book_id != path_id:
+ return False
+ kp, _, _ = find_knowledge_point(progress, knowledge_point_id)
+ return kp is not None
+
+
def _get_learning_store():
from deeptutor.learning.storage import LearningStore
@@ -292,7 +306,7 @@ def _apply_linked_retention(
"""Apply explicitly linked non-Mastery evidence to its objective once."""
if (
record.source == "mastery_path"
- or result == "ungraded"
+ or result in {"ungraded", "voided"}
or not record.mastery_path_id
or not record.knowledge_point_id
):
@@ -331,12 +345,29 @@ def _apply_linked_retention(
f"Unknown linked objective {record.knowledge_point_id!r} "
f"on path {record.mastery_path_id!r}"
)
+ prior_evidence = [
+ item for item in progress.learning_evidence if item.knowledge_point_id == kp.id
+ ]
progress.learning_evidence.append(evidence)
- state = progress.repetition_states.get(kp.id) or scheduler.get_initial_state(
- kp.type, now=evidence.timestamp
- )
- progress.repetition_states[kp.id] = state
- scheduler.schedule_review(state, kp.type, evidence, now=evidence.timestamp)
+ if any(item.timestamp > evidence.timestamp for item in prior_evidence):
+ # A saved event may be retried after a newer assessment. Rebuild
+ # this objective in evidence order instead of scheduling the old
+ # event as if it had just happened.
+ ordered = sorted(
+ [*prior_evidence, evidence],
+ key=lambda item: (item.timestamp, item.evidence_id),
+ )
+ progress.repetition_states[kp.id] = scheduler.replay(
+ kp.type, ordered, desired_retention=progress.desired_retention
+ )
+ else:
+ state = progress.repetition_states.get(kp.id) or scheduler.get_initial_state(
+ kp.type,
+ now=evidence.timestamp,
+ desired_retention=progress.desired_retention,
+ )
+ progress.repetition_states[kp.id] = state
+ scheduler.schedule_review(state, kp.type, evidence, now=evidence.timestamp)
progress.review_queue = scheduler.build_review_queue(progress)
tx.emit(
"evidence.recorded",
@@ -400,19 +431,22 @@ async def record_assessment(record: AssessmentRecord) -> AssessmentOutcome:
from deeptutor.services.session import get_sqlite_session_store
store = get_sqlite_session_store()
- upserted = await store.upsert_notebook_entries(record.session_id or None, [item])
- entry = await store.find_notebook_entry_by_origin(
- record.origin_type,
- record.origin_ref,
- record.question_id,
- turn_id=record.turn_id,
- )
- entry_id = (
- int(entry["id"]) if isinstance(entry, dict) and entry.get("id") is not None else None
- )
- attempt_recorded = await store.append_assessment_attempt(
+ existing_attempt = await store.get_assessment_attempt(attempt_id)
+ if (
+ existing_attempt is None
+ and record.source != "mastery_path"
+ and item["mastery_path_id"]
+ and item["knowledge_point_id"]
+ and not await asyncio.to_thread(
+ _is_trusted_linkage, item["mastery_path_id"], item["knowledge_point_id"]
+ )
+ ):
+ item["mastery_path_id"] = ""
+ item["knowledge_point_id"] = ""
+ diagnostics.append("dropped_invalid_mastery_linkage")
+ entry_id, upserted, attempt_recorded = await store.record_assessment(
record.session_id or None,
- entry_id,
+ item,
{
**record.model_dump(mode="json"),
"attempt_id": attempt_id,
@@ -433,15 +467,23 @@ async def record_assessment(record: AssessmentRecord) -> AssessmentOutcome:
) from exc
if item["mastery_path_id"] and item["knowledge_point_id"]:
try:
+ persisted = await store.get_assessment_attempt(attempt_id)
+ if persisted is None:
+ raise ValueError(f"Missing durable assessment attempt {attempt_id!r}")
+ linked_record = AssessmentRecord.model_validate(persisted)
applied = await asyncio.to_thread(
_apply_linked_retention,
- record,
- result=item["result"],
+ linked_record,
+ result=build_grade_result(
+ result=str(persisted.get("result") or ""),
+ is_correct=persisted.get("is_correct"),
+ ),
attempt_id=attempt_id,
)
+ await store.mark_assessment_link_applied(attempt_id)
if applied:
diagnostics.append("linked_retention_updated")
- except Exception:
+ except Exception as exc:
logger.warning(
"Assessment %s retained its linkage but could not update path %s objective %s",
attempt_id,
@@ -449,7 +491,9 @@ async def record_assessment(record: AssessmentRecord) -> AssessmentOutcome:
item["knowledge_point_id"],
exc_info=True,
)
- diagnostics.append("linked_retention_failed")
+ raise RecordAssessmentError(
+ f"Failed to update linked retention for assessment {attempt_id!r}"
+ ) from exc
return AssessmentOutcome(
entry_id=entry_id,
upserted=bool(upserted),
@@ -459,6 +503,35 @@ async def record_assessment(record: AssessmentRecord) -> AssessmentOutcome:
)
+async def reconcile_linked_assessments() -> tuple[int, int]:
+ """Replay durable cross-surface attempts left pending by an interrupted run."""
+ from deeptutor.services.session import get_sqlite_session_store
+
+ store = get_sqlite_session_store()
+ attempts = await store.pending_linked_assessments()
+ recovered = 0
+ failed = 0
+ for attempt in attempts:
+ attempt_id = str(attempt.get("attempt_id") or "")
+ try:
+ record = AssessmentRecord.model_validate(attempt)
+ await asyncio.to_thread(
+ _apply_linked_retention,
+ record,
+ result=build_grade_result(
+ result=str(attempt.get("result") or ""),
+ is_correct=attempt.get("is_correct"),
+ ),
+ attempt_id=attempt_id,
+ )
+ await store.mark_assessment_link_applied(attempt_id)
+ recovered += 1
+ except Exception:
+ failed += 1
+ logger.exception("Could not reconcile linked assessment %s", attempt_id)
+ return recovered, failed
+
+
__all__ = [
"ASSESSMENT_RESULTS",
"ASSESSMENT_SOURCES",
@@ -473,6 +546,7 @@ __all__ = [
"build_grade_result",
"is_correct_to_result",
"record_assessment",
+ "reconcile_linked_assessments",
"result_to_is_correct",
"to_notebook_item",
]
diff --git a/deeptutor/learning/tests/test_assessment.py b/deeptutor/learning/tests/test_assessment.py
index a1af16b4a..f562429b4 100644
--- a/deeptutor/learning/tests/test_assessment.py
+++ b/deeptutor/learning/tests/test_assessment.py
@@ -17,6 +17,7 @@ from deeptutor.learning.assessment import (
AssessmentRecord,
RecordAssessmentError,
is_correct_to_result,
+ reconcile_linked_assessments,
record_assessment,
result_to_is_correct,
to_notebook_item,
@@ -231,6 +232,62 @@ def test_reanswer_keeps_immutable_attempts_and_updates_latest_projection(
assert [attempt["result"] for attempt in attempts] == ["incorrect", "correct"]
+def test_old_submission_retry_cannot_overwrite_newer_answer(store: SQLiteSessionStore) -> None:
+ asyncio.run(store.create_session(title="S", session_id="session-1"))
+ wrong = _mastery_record(attempt_id="old", user_answer="3", result="incorrect")
+ right = _mastery_record(attempt_id="new", user_answer="4", result="correct", is_correct=True)
+ asyncio.run(record_assessment(wrong))
+ asyncio.run(record_assessment(right))
+ retried = asyncio.run(record_assessment(wrong))
+
+ latest = asyncio.run(store.find_notebook_entry("session-1", "q-1", turn_id="turn-1"))
+ attempts = asyncio.run(store.list_assessment_attempts("session-1", question_id="q-1"))
+ assert retried.attempt_recorded is False
+ assert retried.upserted is False
+ assert latest["user_answer"] == "4"
+ assert latest["result"] == "correct"
+ assert len(attempts) == 2
+
+
+def test_submission_id_cannot_be_reused_for_different_answer(store: SQLiteSessionStore) -> None:
+ asyncio.run(store.create_session(title="S", session_id="session-1"))
+ asyncio.run(record_assessment(_mastery_record(attempt_id="same", user_answer="3")))
+ with pytest.raises(RecordAssessmentError):
+ asyncio.run(record_assessment(_mastery_record(attempt_id="same", user_answer="4")))
+ assert len(asyncio.run(store.list_assessment_attempts("session-1"))) == 1
+
+
+def test_projection_failure_rolls_back_event(
+ store: SQLiteSessionStore, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ asyncio.run(store.create_session(title="S", session_id="session-1"))
+
+ def fail_projection(*_args, **_kwargs):
+ raise RuntimeError("projection failed")
+
+ monkeypatch.setattr(store, "_upsert_notebook_entries_in_conn", fail_projection)
+ with pytest.raises(RecordAssessmentError):
+ asyncio.run(record_assessment(_mastery_record(attempt_id="will-rollback")))
+ assert asyncio.run(store.list_assessment_attempts("session-1")) == []
+ assert asyncio.run(store.list_notebook_entries(session_id="session-1"))["total"] == 0
+
+
+def test_unknown_cross_surface_objective_keeps_unlinked_attempt(store: SQLiteSessionStore) -> None:
+ asyncio.run(store.create_session(title="S", session_id="session-1"))
+ record = _mastery_record(
+ source="book",
+ mastery_path_id="nonexistent-path",
+ knowledge_point_id="nonexistent-kp",
+ attempt_id="unlinked",
+ )
+ outcome = asyncio.run(record_assessment(record))
+ latest = asyncio.run(store.find_notebook_entry("session-1", "q-1", turn_id="turn-1"))
+ attempts = asyncio.run(store.list_assessment_attempts("session-1", question_id="q-1"))
+ assert "dropped_invalid_mastery_linkage" in outcome.diagnostics
+ assert latest["mastery_path_id"] == ""
+ assert attempts[0]["mastery_path_id"] == ""
+
+
def test_linked_book_assessment_updates_mastery_retention_once(
store: SQLiteSessionStore,
tmp_path: Path,
@@ -286,6 +343,99 @@ def test_linked_book_assessment_updates_mastery_retention_once(
assert linked.repetition_states["kp-1"].review_count == 1
+def test_linked_evidence_retries_after_restart_in_event_order(
+ store: SQLiteSessionStore,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ asyncio.run(store.create_session(title="S", session_id="session-1"))
+ learning_root = tmp_path / "learning"
+ initial_store = LearningStore(root=learning_root)
+ initial_store.save(
+ LearningProgress(
+ book_id="path-1",
+ modules=[
+ LearningModule(
+ id="module-1",
+ name="Module",
+ order=0,
+ knowledge_points=[
+ KnowledgePoint(
+ id="kp-1",
+ name="Concept",
+ type=KnowledgeType.CONCEPT,
+ module_id="module-1",
+ )
+ ],
+ )
+ ],
+ knowledge_types={"kp-1": KnowledgeType.CONCEPT},
+ )
+ )
+ monkeypatch.setattr("deeptutor.learning.assessment._get_learning_store", lambda: initial_store)
+ import deeptutor.learning.assessment as assessment_module
+
+ apply_retention = assessment_module._apply_linked_retention
+
+ def interrupted(*_args, **_kwargs):
+ raise RuntimeError("interrupted after event commit")
+
+ monkeypatch.setattr(assessment_module, "_apply_linked_retention", interrupted)
+ old = AssessmentRecord(
+ session_id="session-1",
+ turn_id="book-turn",
+ question_id="book-q",
+ question="Explain the concept",
+ user_answer="wrong",
+ result="incorrect",
+ is_correct=False,
+ source="book",
+ assessment_type="focus_check",
+ mastery_path_id="path-1",
+ knowledge_point_id="kp-1",
+ attempt_id="book-old",
+ created_at=1_000_000.0,
+ )
+ with pytest.raises(RecordAssessmentError):
+ asyncio.run(record_assessment(old))
+ assert len(asyncio.run(store.list_assessment_attempts("session-1"))) == 1
+ assert initial_store.load("path-1").learning_evidence == []
+
+ restarted_sessions = SQLiteSessionStore(db_path=store.db_path)
+ restarted_learning = LearningStore(root=learning_root)
+ monkeypatch.setattr(
+ "deeptutor.services.session.get_sqlite_session_store", lambda: restarted_sessions
+ )
+ monkeypatch.setattr(
+ "deeptutor.learning.assessment._get_learning_store", lambda: restarted_learning
+ )
+ monkeypatch.setattr(assessment_module, "_apply_linked_retention", apply_retention)
+ newer = old.model_copy(
+ update={
+ "attempt_id": "book-new",
+ "user_answer": "right",
+ "result": "correct",
+ "is_correct": True,
+ "created_at": 1_100_000.0,
+ }
+ )
+ asyncio.run(record_assessment(newer))
+ assert asyncio.run(reconcile_linked_assessments()) == (1, 0)
+ retried_old = old.model_copy(update={"created_at": 1_200_000.0})
+ outcome = asyncio.run(record_assessment(retried_old))
+
+ linked = restarted_learning.load("path-1")
+ state = linked.repetition_states["kp-1"]
+ assert outcome.attempt_recorded is False
+ assert outcome.diagnostics == []
+ assert len(linked.learning_evidence) == 2
+ assert state.review_count == 2
+ assert state.last_review_at == newer.created_at
+ assert next(e for e in linked.learning_evidence if e.evidence_id == "book-old").timestamp == (
+ old.created_at
+ )
+
+
def test_missing_session_raises_record_error() -> None:
record = _mastery_record(session_id="no-such-session")
with pytest.raises(RecordAssessmentError):
diff --git a/deeptutor/services/session/sqlite_store.py b/deeptutor/services/session/sqlite_store.py
index 142320031..655c29dd8 100644
--- a/deeptutor/services/session/sqlite_store.py
+++ b/deeptutor/services/session/sqlite_store.py
@@ -410,7 +410,8 @@ class SQLiteSessionStore:
mastery_path_id TEXT NOT NULL DEFAULT '',
knowledge_point_id TEXT NOT NULL DEFAULT '',
occurred_at REAL NOT NULL,
- assessment_json TEXT NOT NULL
+ assessment_json TEXT NOT NULL,
+ linked_applied INTEGER NOT NULL DEFAULT 0
);
CREATE INDEX IF NOT EXISTS idx_assessment_attempts_session_time
@@ -494,6 +495,7 @@ class SQLiteSessionStore:
self._migrate_notebook_entries_add_assessment_v2(conn)
self._migrate_notebook_entry_origins(conn)
self._migrate_assessment_attempt_origins(conn)
+ self._migrate_assessment_attempt_link_state(conn)
self._migrate_turn_runtime_columns(conn)
from deeptutor.services.practice.storage import initialize_practice
@@ -1010,7 +1012,8 @@ class SQLiteSessionStore:
mastery_path_id TEXT NOT NULL DEFAULT '',
knowledge_point_id TEXT NOT NULL DEFAULT '',
occurred_at REAL NOT NULL,
- assessment_json TEXT NOT NULL
+ assessment_json TEXT NOT NULL,
+ linked_applied INTEGER NOT NULL DEFAULT 0
)
"""
)
@@ -1051,6 +1054,22 @@ class SQLiteSessionStore:
finally:
conn.execute("PRAGMA foreign_keys = ON")
+ @staticmethod
+ def _migrate_assessment_attempt_link_state(conn: sqlite3.Connection) -> None:
+ columns = {
+ row[1] for row in conn.execute("PRAGMA table_info(assessment_attempts)").fetchall()
+ }
+ if "linked_applied" not in columns:
+ conn.execute(
+ "ALTER TABLE assessment_attempts ADD COLUMN linked_applied INTEGER NOT NULL DEFAULT 0"
+ )
+ conn.execute(
+ "CREATE INDEX IF NOT EXISTS idx_assessment_attempts_pending_link "
+ "ON assessment_attempts(occurred_at) WHERE linked_applied = 0 "
+ "AND mastery_path_id != '' AND knowledge_point_id != '' "
+ "AND source != 'mastery_path' AND result NOT IN ('ungraded', 'voided')"
+ )
+
async def _run(self, fn, *args):
async with self._lock:
return await asyncio.to_thread(fn, *args)
@@ -2959,151 +2978,156 @@ class SQLiteSessionStore:
raise ValueError(f"{origin_type} question origins require origin_ref")
return navigation_session, origin_type, origin_ref
- def _upsert_notebook_entries_sync(
+ def _upsert_notebook_entries_in_conn(
self,
+ conn: sqlite3.Connection,
session_id: str | None,
items: list[dict[str, Any]],
) -> int:
if not items:
return 0
now = time.time()
- with self._connect() as conn:
- upserted = 0
- for item in items:
- navigation_session, origin_type, origin_ref = self._notebook_origin(
- session_id, item
- )
- if navigation_session is not None and (
- conn.execute(
- "SELECT id FROM sessions WHERE id = ?", (navigation_session,)
- ).fetchone()
- is None
- ):
- raise ValueError(f"Session not found: {navigation_session}")
- question = (item.get("question") or "").strip()
- question_id = (item.get("question_id") or "").strip()
- if not question or not question_id:
- continue
- turn_id = (item.get("turn_id") or "").strip()
- # ``user_answer_images`` is an optional list of records
- # ``[{id, url, filename, mime_type}, …]``. We serialise it
- # here so callers that only know about text don't need to
- # know JSON. ``None`` keeps the existing column value on
- # UPDATE (avoid clobbering stored images on a partial
- # upsert that only changes ``is_correct``).
- images_value = item.get("user_answer_images")
- images_json = _json_dumps(images_value) if isinstance(images_value, list) else None
- source = str(item.get("source") or "deep_question")
- if source not in ASSESSMENT_SOURCES:
- source = "deep_question"
- is_correct = 1 if item.get("is_correct") else 0
- existing = conn.execute(
- """
- SELECT is_correct FROM notebook_entries
- WHERE origin_type = ? AND origin_ref = ?
- AND turn_id = ? AND question_id = ?
- """,
- (origin_type, origin_ref, turn_id, question_id),
- ).fetchone()
- previous = bool(existing["is_correct"]) if existing is not None else None
- if previous is None or previous == bool(is_correct):
- score_trend = "new" if previous is None else "unchanged"
- else:
- score_trend = "improved" if is_correct else "declined"
- provenance = (
- source,
- str(item.get("material_id") or ""),
- str(item.get("material_title") or ""),
- str(item.get("section_id") or ""),
- str(item.get("section_title") or ""),
- score_trend,
- )
- assessment = self._notebook_assessment_values(item, is_correct)
- resolved_on_insert = (
- 0
- if assessment[1] == "ungraded"
- else 1
- if assessment[1] == "voided" or is_correct
- else 0
- )
+ upserted = 0
+ for item in items:
+ navigation_session, origin_type, origin_ref = self._notebook_origin(session_id, item)
+ if navigation_session is not None and (
conn.execute(
- """
- INSERT INTO notebook_entries (
- session_id, origin_type, origin_ref, turn_id, question_id,
- question, question_type, options_json, correct_answer,
- explanation, difficulty, user_answer,
- user_answer_images_json, source, material_id,
- material_title, section_id, section_title, score_trend,
- assessment_type, result, mastery_path_id, knowledge_point_id,
- attempt_count, hints_used, confidence, response_time, quality,
- is_correct, resolved, bookmarked, followup_session_id,
- created_at, updated_at
- ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, '', ?, ?)
- ON CONFLICT(origin_type, origin_ref, turn_id, question_id) DO UPDATE SET
- session_id = excluded.session_id,
- question = excluded.question,
- question_type = excluded.question_type,
- options_json = excluded.options_json,
- correct_answer = excluded.correct_answer,
- explanation = excluded.explanation,
- difficulty = excluded.difficulty,
- user_answer = excluded.user_answer,
- user_answer_images_json = CASE
- WHEN ? THEN notebook_entries.user_answer_images_json
- ELSE excluded.user_answer_images_json
- END,
- source = excluded.source,
- material_id = excluded.material_id,
- material_title = excluded.material_title,
- section_id = excluded.section_id,
- section_title = excluded.section_title,
- score_trend = excluded.score_trend,
- assessment_type = excluded.assessment_type,
- result = excluded.result,
- mastery_path_id = excluded.mastery_path_id,
- knowledge_point_id = excluded.knowledge_point_id,
- attempt_count = excluded.attempt_count,
- hints_used = excluded.hints_used,
- confidence = excluded.confidence,
- response_time = excluded.response_time,
- quality = excluded.quality,
- is_correct = excluded.is_correct,
- resolved = CASE
- WHEN excluded.result = 'ungraded' THEN notebook_entries.resolved
- WHEN excluded.result = 'voided' THEN 1
- WHEN excluded.is_correct = 1 THEN 1
- WHEN excluded.is_correct = 0 AND notebook_entries.is_correct = 1 THEN 0
- ELSE notebook_entries.resolved
- END,
- updated_at = excluded.updated_at
- """,
- (
- navigation_session,
- origin_type,
- origin_ref,
- turn_id,
- question_id,
- question,
- item.get("question_type") or "",
- _json_dumps(item.get("options") or {}),
- item.get("correct_answer") or "",
- item.get("explanation") or "",
- item.get("difficulty") or "",
- item.get("user_answer") or "",
- images_json if images_json is not None else "[]",
- *provenance,
- *assessment,
- is_correct,
- resolved_on_insert,
- now,
- now,
- images_json is None,
- ),
- )
- upserted += 1
- conn.commit()
+ "SELECT id FROM sessions WHERE id = ?", (navigation_session,)
+ ).fetchone()
+ is None
+ ):
+ raise ValueError(f"Session not found: {navigation_session}")
+ question = (item.get("question") or "").strip()
+ question_id = (item.get("question_id") or "").strip()
+ if not question or not question_id:
+ continue
+ turn_id = (item.get("turn_id") or "").strip()
+ # ``user_answer_images`` is an optional list of records
+ # ``[{id, url, filename, mime_type}, …]``. We serialise it
+ # here so callers that only know about text don't need to
+ # know JSON. ``None`` keeps the existing column value on
+ # UPDATE (avoid clobbering stored images on a partial
+ # upsert that only changes ``is_correct``).
+ images_value = item.get("user_answer_images")
+ images_json = _json_dumps(images_value) if isinstance(images_value, list) else None
+ source = str(item.get("source") or "deep_question")
+ if source not in ASSESSMENT_SOURCES:
+ source = "deep_question"
+ is_correct = 1 if item.get("is_correct") else 0
+ existing = conn.execute(
+ """
+ SELECT is_correct FROM notebook_entries
+ WHERE origin_type = ? AND origin_ref = ?
+ AND turn_id = ? AND question_id = ?
+ """,
+ (origin_type, origin_ref, turn_id, question_id),
+ ).fetchone()
+ previous = bool(existing["is_correct"]) if existing is not None else None
+ if previous is None or previous == bool(is_correct):
+ score_trend = "new" if previous is None else "unchanged"
+ else:
+ score_trend = "improved" if is_correct else "declined"
+ provenance = (
+ source,
+ str(item.get("material_id") or ""),
+ str(item.get("material_title") or ""),
+ str(item.get("section_id") or ""),
+ str(item.get("section_title") or ""),
+ score_trend,
+ )
+ assessment = self._notebook_assessment_values(item, is_correct)
+ resolved_on_insert = (
+ 0
+ if assessment[1] == "ungraded"
+ else 1
+ if assessment[1] == "voided" or is_correct
+ else 0
+ )
+ conn.execute(
+ """
+ INSERT INTO notebook_entries (
+ session_id, origin_type, origin_ref, turn_id, question_id,
+ question, question_type, options_json, correct_answer,
+ explanation, difficulty, user_answer,
+ user_answer_images_json, source, material_id,
+ material_title, section_id, section_title, score_trend,
+ assessment_type, result, mastery_path_id, knowledge_point_id,
+ attempt_count, hints_used, confidence, response_time, quality,
+ is_correct, resolved, bookmarked, followup_session_id,
+ created_at, updated_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, '', ?, ?)
+ ON CONFLICT(origin_type, origin_ref, turn_id, question_id) DO UPDATE SET
+ session_id = excluded.session_id,
+ question = excluded.question,
+ question_type = excluded.question_type,
+ options_json = excluded.options_json,
+ correct_answer = excluded.correct_answer,
+ explanation = excluded.explanation,
+ difficulty = excluded.difficulty,
+ user_answer = excluded.user_answer,
+ user_answer_images_json = CASE
+ WHEN ? THEN notebook_entries.user_answer_images_json
+ ELSE excluded.user_answer_images_json
+ END,
+ source = excluded.source,
+ material_id = excluded.material_id,
+ material_title = excluded.material_title,
+ section_id = excluded.section_id,
+ section_title = excluded.section_title,
+ score_trend = excluded.score_trend,
+ assessment_type = excluded.assessment_type,
+ result = excluded.result,
+ mastery_path_id = excluded.mastery_path_id,
+ knowledge_point_id = excluded.knowledge_point_id,
+ attempt_count = excluded.attempt_count,
+ hints_used = excluded.hints_used,
+ confidence = excluded.confidence,
+ response_time = excluded.response_time,
+ quality = excluded.quality,
+ is_correct = excluded.is_correct,
+ resolved = CASE
+ WHEN excluded.result = 'ungraded' THEN notebook_entries.resolved
+ WHEN excluded.result = 'voided' THEN 1
+ WHEN excluded.is_correct = 1 THEN 1
+ WHEN excluded.is_correct = 0 AND notebook_entries.is_correct = 1 THEN 0
+ ELSE notebook_entries.resolved
+ END,
+ updated_at = excluded.updated_at
+ """,
+ (
+ navigation_session,
+ origin_type,
+ origin_ref,
+ turn_id,
+ question_id,
+ question,
+ item.get("question_type") or "",
+ _json_dumps(item.get("options") or {}),
+ item.get("correct_answer") or "",
+ item.get("explanation") or "",
+ item.get("difficulty") or "",
+ item.get("user_answer") or "",
+ images_json if images_json is not None else "[]",
+ *provenance,
+ *assessment,
+ is_correct,
+ resolved_on_insert,
+ now,
+ now,
+ images_json is None,
+ ),
+ )
+ upserted += 1
return upserted
+ def _upsert_notebook_entries_sync(
+ self,
+ session_id: str | None,
+ items: list[dict[str, Any]],
+ ) -> int:
+ with self._connect() as conn:
+ return self._upsert_notebook_entries_in_conn(conn, session_id, items)
+
async def upsert_notebook_entries(
self,
session_id: str | None,
@@ -3174,6 +3198,164 @@ class SQLiteSessionStore:
attempt,
)
+ def _record_assessment_sync(
+ self,
+ session_id: str | None,
+ item: dict[str, Any],
+ attempt: dict[str, Any],
+ ) -> tuple[int, bool, bool]:
+ """Commit the evidence event and its latest-card projection together.
+
+ The event is inserted first inside the transaction. A retry with the
+ same submission id leaves the latest card alone, even if a newer
+ attempt has since changed it.
+ """
+ attempt_id = str(attempt.get("attempt_id") or "").strip()
+ question_id = str(attempt.get("question_id") or "").strip()
+ if not attempt_id or not question_id:
+ raise ValueError("attempt_id and question_id are required")
+ navigation_session, origin_type, origin_ref = self._notebook_origin(session_id, attempt)
+ turn_id = str(attempt.get("turn_id") or "").strip()
+ with self._connect() as conn:
+ conn.execute("BEGIN IMMEDIATE")
+ existing = conn.execute(
+ "SELECT assessment_json, notebook_entry_id FROM assessment_attempts "
+ "WHERE attempt_id = ?",
+ (attempt_id,),
+ ).fetchone()
+ if existing is not None:
+ original = _json_loads(str(existing["assessment_json"]), {})
+ identity_fields = (
+ "origin_type",
+ "origin_ref",
+ "turn_id",
+ "question_id",
+ "source",
+ "assessment_type",
+ "user_answer",
+ "result",
+ "mastery_path_id",
+ "knowledge_point_id",
+ )
+ if any(original.get(key) != attempt.get(key) for key in identity_fields):
+ raise ValueError(f"Conflicting assessment submission id: {attempt_id}")
+ entry_id = existing["notebook_entry_id"]
+ if entry_id is None:
+ row = conn.execute(
+ "SELECT id FROM notebook_entries WHERE origin_type = ? "
+ "AND origin_ref = ? AND turn_id = ? AND question_id = ?",
+ (origin_type, origin_ref, turn_id, question_id),
+ ).fetchone()
+ entry_id = row["id"] if row is not None else None
+ return int(entry_id) if entry_id is not None else 0, False, False
+
+ if (
+ navigation_session is not None
+ and conn.execute(
+ "SELECT id FROM sessions WHERE id = ?", (navigation_session,)
+ ).fetchone()
+ is None
+ ):
+ raise ValueError(f"Session not found: {navigation_session}")
+ if str(attempt.get("source") or "") == "immersive_reading":
+ row = conn.execute(
+ "SELECT COUNT(*) AS count FROM assessment_attempts "
+ "WHERE origin_type = ? AND origin_ref = ? AND turn_id = ? AND question_id = ?",
+ (origin_type, origin_ref, turn_id, question_id),
+ ).fetchone()
+ count = int(row["count"]) + 1
+ item = {**item, "attempt_count": count}
+ attempt = {**attempt, "attempt_count": count}
+ conn.execute(
+ """
+ INSERT INTO assessment_attempts (
+ attempt_id, notebook_entry_id, session_id, origin_type,
+ origin_ref, turn_id, question_id, source, assessment_type, result,
+ mastery_path_id, knowledge_point_id, occurred_at,
+ assessment_json
+ ) VALUES (?, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ """,
+ (
+ attempt_id,
+ navigation_session,
+ origin_type,
+ origin_ref,
+ turn_id,
+ question_id,
+ str(attempt.get("source") or "deep_question"),
+ str(attempt.get("assessment_type") or "quiz"),
+ str(attempt.get("result") or "ungraded"),
+ str(attempt.get("mastery_path_id") or ""),
+ str(attempt.get("knowledge_point_id") or ""),
+ float(attempt.get("occurred_at") or time.time()),
+ _json_dumps(attempt),
+ ),
+ )
+ upserted = self._upsert_notebook_entries_in_conn(conn, session_id, [item])
+ row = conn.execute(
+ "SELECT id FROM notebook_entries WHERE origin_type = ? "
+ "AND origin_ref = ? AND turn_id = ? AND question_id = ?",
+ (origin_type, origin_ref, turn_id, question_id),
+ ).fetchone()
+ if row is None:
+ raise ValueError("Assessment projection was not persisted")
+ entry_id = int(row["id"])
+ conn.execute(
+ "UPDATE assessment_attempts SET notebook_entry_id = ? WHERE attempt_id = ?",
+ (entry_id, attempt_id),
+ )
+ return entry_id, bool(upserted), True
+
+ async def record_assessment(
+ self,
+ session_id: str | None,
+ item: dict[str, Any],
+ attempt: dict[str, Any],
+ ) -> tuple[int, bool, bool]:
+ """Atomically append one assessment and refresh its Question Bank card."""
+ return await self._run(self._record_assessment_sync, session_id, item, attempt)
+
+ def _get_assessment_attempt_sync(self, attempt_id: str) -> dict[str, Any] | None:
+ with self._connect() as conn:
+ row = conn.execute(
+ "SELECT assessment_json FROM assessment_attempts WHERE attempt_id = ?",
+ (attempt_id,),
+ ).fetchone()
+ if row is None:
+ return None
+ value = _json_loads(str(row["assessment_json"]), {})
+ return value if isinstance(value, dict) else None
+
+ async def get_assessment_attempt(self, attempt_id: str) -> dict[str, Any] | None:
+ return await self._run(self._get_assessment_attempt_sync, attempt_id)
+
+ def _mark_assessment_link_applied_sync(self, attempt_id: str) -> None:
+ with self._connect() as conn:
+ conn.execute(
+ "UPDATE assessment_attempts SET linked_applied = 1 WHERE attempt_id = ?",
+ (attempt_id,),
+ )
+
+ async def mark_assessment_link_applied(self, attempt_id: str) -> None:
+ await self._run(self._mark_assessment_link_applied_sync, attempt_id)
+
+ def _pending_linked_assessments_sync(self) -> list[dict[str, Any]]:
+ with self._connect() as conn:
+ rows = conn.execute(
+ "SELECT assessment_json FROM assessment_attempts WHERE linked_applied = 0 "
+ "AND mastery_path_id != '' AND knowledge_point_id != '' "
+ "AND source != 'mastery_path' AND result NOT IN ('ungraded', 'voided') "
+ "ORDER BY occurred_at, attempt_id"
+ ).fetchall()
+ return [
+ value
+ for row in rows
+ if isinstance(value := _json_loads(str(row["assessment_json"]), {}), dict)
+ ]
+
+ async def pending_linked_assessments(self) -> list[dict[str, Any]]:
+ return await self._run(self._pending_linked_assessments_sync)
+
def _list_assessment_attempts_sync(
self,
session_id: str,
diff --git a/tests/api/test_book_quiz_attempt_notebook.py b/tests/api/test_book_quiz_attempt_notebook.py
index 4771fa110..95b5b8562 100644
--- a/tests/api/test_book_quiz_attempt_notebook.py
+++ b/tests/api/test_book_quiz_attempt_notebook.py
@@ -15,11 +15,13 @@ from deeptutor.services.session.sqlite_store import SQLiteSessionStore
class _FakeLearningStore:
def __init__(self) -> None:
self.saved: list[Progress] = []
+ self.current: Progress | None = None
def load_progress(self, book_id: str) -> Progress:
- return Progress(book_id=book_id)
+ return self.current or Progress(book_id=book_id)
def save_progress(self, progress: Progress) -> None:
+ self.current = progress
self.saved.append(progress)
@@ -129,3 +131,38 @@ def test_quiz_attempt_does_not_create_a_synthetic_chat_session(tmp_path, monkeyp
assert entries["items"][0]["session_id"] == ""
assert entries["items"][0]["origin_type"] == "document_analysis"
assert entries["items"][0]["origin_ref"] == "book:book-1"
+
+
+def test_book_submission_retry_is_idempotent_but_new_submission_is_evidence(
+ tmp_path, monkeypatch
+) -> None:
+ store = SQLiteSessionStore(db_path=tmp_path / "sessions.db")
+ asyncio.run(store.create_session(session_id="page-chat-1", title="Page 1 chat"))
+ resolved = _FakeResolvedBook()
+ monkeypatch.setattr(book_router, "_resolve_book_or_404", lambda _: resolved)
+ monkeypatch.setattr(session_package, "get_sqlite_session_store", lambda: store)
+ app = FastAPI()
+ app.include_router(book_router.router, prefix="/api")
+ payload = {
+ "book_id": "book-1",
+ "page_id": "page-1",
+ "block_id": "block-1",
+ "question_id": "q1",
+ "user_answer": "A",
+ "is_correct": False,
+ "submission_id": "click-1",
+ }
+ with TestClient(app) as client:
+ assert client.post("/api/books/quiz-attempt", json=payload).status_code == 200
+ assert client.post("/api/books/quiz-attempt", json=payload).status_code == 200
+ assert (
+ client.post(
+ "/api/books/quiz-attempt", json={**payload, "submission_id": "click-2"}
+ ).status_code
+ == 200
+ )
+
+ assert len(resolved.learning.current.quiz_attempts) == 2
+ attempts = asyncio.run(store.list_assessment_attempts("page-chat-1", question_id="q1"))
+ assert len(attempts) == 2
+ assert [item["attempt_count"] for item in attempts] == [1, 2]
diff --git a/tests/api/test_reading_quiz_answers.py b/tests/api/test_reading_quiz_answers.py
index 1cc401ca7..1b8be8383 100644
--- a/tests/api/test_reading_quiz_answers.py
+++ b/tests/api/test_reading_quiz_answers.py
@@ -195,6 +195,37 @@ def test_repeat_submission_is_idempotent(store: SQLiteSessionStore) -> None:
assert listing["total"] == 2
+def test_reading_submission_id_distinguishes_retry_from_new_attempt(
+ store: SQLiteSessionStore,
+) -> None:
+ asyncio.run(store.create_session(title="Reading", session_id="reading-session"))
+ asyncio.run(store.put_reading_quiz_pending(MATERIAL_ID, LOCATOR, _quiz_questions()))
+ payload = _payload(answers=_answers(("q_1", 1)), submission_id="click-1")
+ with TestClient(_build_app(store)) as client:
+ assert (
+ client.post(
+ f"/api/reading/materials/{MATERIAL_ID}/extensions/quiz/answers", json=payload
+ ).status_code
+ == 200
+ )
+ assert (
+ client.post(
+ f"/api/reading/materials/{MATERIAL_ID}/extensions/quiz/answers", json=payload
+ ).status_code
+ == 200
+ )
+ assert (
+ client.post(
+ f"/api/reading/materials/{MATERIAL_ID}/extensions/quiz/answers",
+ json={**payload, "submission_id": "click-2"},
+ ).status_code
+ == 200
+ )
+ attempts = asyncio.run(store.list_assessment_attempts("reading-session", question_id="q_1"))
+ assert len(attempts) == 2
+ assert [item["attempt_count"] for item in attempts] == [1, 2]
+
+
@pytest.mark.parametrize("selected_index", [-1, 2])
def test_invalid_selection_does_not_save_any_part_of_batch(store, selected_index):
asyncio.run(store.put_reading_quiz_pending(MATERIAL_ID, LOCATOR, _quiz_questions()))
diff --git a/web/app/(workspace)/learning/books/BooksRoute.tsx b/web/app/(workspace)/learning/books/BooksRoute.tsx
index 3a6275811..e3e1815a2 100644
--- a/web/app/(workspace)/learning/books/BooksRoute.tsx
+++ b/web/app/(workspace)/learning/books/BooksRoute.tsx
@@ -153,6 +153,7 @@ function BookPageInner() {
* every single book, as the first thing generation ever said.
*/
const revisionRef = useRef<number | undefined>(undefined)
+ const pendingQuizSubmissions = useRef(new Map<string, { answer: string; id: string }>())
// ── Data loaders ───────────────────────────────────────────────────
@@ -866,6 +867,11 @@ function BookPageInner() {
guard('Record answer', async () => {
if (!detail || !selectedPage) return
const bookId = detail.book.id
+ const key = `${bookId}:${selectedPage.id}:${block.id}:${args.questionId || ''}`
+ const answer = `${args.userAnswer || ''}:${String(args.isCorrect)}`
+ const pending = pendingQuizSubmissions.current.get(key)
+ const submissionId = pending?.answer === answer ? pending.id : crypto.randomUUID()
+ pendingQuizSubmissions.current.set(key, { answer, id: submissionId })
const { progress } = await bookApi.recordQuizAttempt({
book_id: bookId,
page_id: selectedPage.id,
@@ -873,7 +879,9 @@ function BookPageInner() {
question_id: args.questionId,
user_answer: args.userAnswer,
is_correct: args.isCorrect,
+ submission_id: submissionId,
})
+ pendingQuizSubmissions.current.delete(key)
setDetail(current =>
current && current.book.id === bookId ? { ...current, progress } : current
)
diff --git a/web/components/reading/ReadingExtensionBar.tsx b/web/components/reading/ReadingExtensionBar.tsx
index 6d97970c2..28a83c0ae 100644
--- a/web/components/reading/ReadingExtensionBar.tsx
+++ b/web/components/reading/ReadingExtensionBar.tsx
@@ -1,6 +1,6 @@
"use client";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
import { Loader2, Sparkles, Square, Volume2, X } from "lucide-react";
import { useTranslation } from "react-i18next";
import {
@@ -352,21 +352,27 @@ function QuizQuestions({
const [answers, setAnswers] = useState<Record<string, number>>({});
const [verdicts, setVerdicts] = useState<Record<string, boolean>>({});
const [saving, setSaving] = useState<Record<string, boolean>>({});
+ const pendingSubmissions = useRef<Record<string, { selected: number; id: string }>>({});
async function persistAnswer(question: QuizQuestion, index: number, choiceIndex: number) {
const questionId = question.id || `q_${index + 1}`;
const key = question.id || String(index);
+ const pending = pendingSubmissions.current[key];
+ const submissionId = pending?.selected === choiceIndex ? pending.id : crypto.randomUUID();
+ pendingSubmissions.current[key] = { selected: choiceIndex, id: submissionId };
setSaving((current) => ({ ...current, [key]: true }));
try {
const results = await submitReadingQuizAnswers(materialId, {
locator,
session_id: sessionId || "",
+ submission_id: submissionId,
answers: [{ question_id: questionId, selected_index: choiceIndex }],
});
const verdict = results.find((item) => item.question_id === questionId);
if (!verdict) throw new Error(t("Failed to save answer. Please try again."));
setAnswers((current) => ({ ...current, [key]: choiceIndex }));
setVerdicts((current) => ({ ...current, [key]: verdict.is_correct }));
+ delete pendingSubmissions.current[key];
} catch (error) {
onError(error instanceof Error ? error.message : String(error));
} finally {
diff --git a/web/contracts/generated/api.ts b/web/contracts/generated/api.ts
index 82060494b..4b32920ff 100644
--- a/web/contracts/generated/api.ts
+++ b/web/contracts/generated/api.ts
@@ -3377,6 +3377,24 @@ export interface paths {
readonly patch?: never;
readonly trace?: never;
};
+ readonly "/api/mastery-paths/topics/{path_id}/review-settings": {
+ readonly parameters: {
+ readonly query?: never;
+ readonly header?: never;
+ readonly path?: never;
+ readonly cookie?: never;
+ };
+ /** Get Review Settings */
+ readonly get: operations["get_review_settings_api_mastery_paths_topics__path_id__review_settings_get"];
+ /** Update Review Settings */
+ readonly put: operations["update_review_settings_api_mastery_paths_topics__path_id__review_settings_put"];
+ readonly post?: never;
+ readonly delete?: never;
+ readonly options?: never;
+ readonly head?: never;
+ readonly patch?: never;
+ readonly trace?: never;
+ };
readonly "/api/mastery-paths/topics/{path_id}/sessions": {
readonly parameters: {
readonly query?: never;
@@ -8031,6 +8049,30 @@ export interface paths {
readonly patch?: never;
readonly trace?: never;
};
+ readonly "/api/settings/voice-math-speak": {
+ readonly parameters: {
+ readonly query?: never;
+ readonly header?: never;
+ readonly path?: never;
+ readonly cookie?: never;
+ };
+ readonly get?: never;
+ /**
+ * Update Voice Math Speak
+ * @description Persist whether TTS verbalizes LaTeX as spoken math.
+ *
+ * A personal UI preference (any authenticated user). The voice router reads
+ * this on each synthesis call; chat does not send a per-request override.
+ * Dollar-sign delimiters are stripped even when this is off.
+ */
+ readonly put: operations["update_voice_math_speak_api_settings_voice_math_speak_put"];
+ readonly post?: never;
+ readonly delete?: never;
+ readonly options?: never;
+ readonly head?: never;
+ readonly patch?: never;
+ readonly trace?: never;
+ };
readonly "/api/settings/voice/preview": {
readonly parameters: {
readonly query?: never;
@@ -11798,7 +11840,7 @@ export interface components {
* Language
* @enum {string}
*/
- readonly language: "zh" | "en";
+ readonly language: "zh" | "en" | "fr";
};
/** LearnerOverrideRequest */
readonly LearnerOverrideRequest: {
@@ -12758,6 +12800,18 @@ export interface components {
readonly options: {
readonly [key: string]: string;
};
+ /**
+ * Origin Ref
+ * @default
+ */
+ readonly origin_ref: string;
+ /**
+ * Origin Type
+ * @default conversation
+ * @enum {string}
+ */
+ readonly origin_type:
+ "conversation" | "external_import" | "document_analysis";
/** Practice */
readonly practice?: {
readonly [key: string]: unknown;
@@ -12805,7 +12859,10 @@ export interface components {
* @default
*/
readonly section_title: string;
- /** Session Id */
+ /**
+ * Session Id
+ * @default
+ */
readonly session_id: string;
/**
* Session Title
@@ -13311,6 +13368,11 @@ export interface components {
* @default
*/
readonly source_anchor: string;
+ /**
+ * Submission Id
+ * @default
+ */
+ readonly submission_id: string;
/**
* Turn Id
* @default
@@ -13332,6 +13394,11 @@ export interface components {
* @default
*/
readonly question_id: string;
+ /**
+ * Submission Id
+ * @default
+ */
+ readonly submission_id: string;
/**
* User Answer
* @default
@@ -13615,6 +13682,14 @@ export interface components {
/** Version */
readonly version: number;
};
+ /**
+ * ReviewSettingsRequest
+ * @description A per-path recall target; higher values schedule shorter intervals.
+ */
+ readonly ReviewSettingsRequest: {
+ /** Desired Retention */
+ readonly desired_retention: number;
+ };
/** RoundSummaryRequest */
readonly RoundSummaryRequest: {
/** Partner Id */
@@ -14563,9 +14638,9 @@ export interface components {
/** Code Block Wrap Long Lines */
readonly code_block_wrap_long_lines?: boolean | null;
/** Language */
- readonly language?: ("zh" | "en") | null;
+ readonly language?: ("zh" | "en" | "fr") | null;
/** Response Language */
- readonly response_language?: ("zh" | "en") | null;
+ readonly response_language?: ("zh" | "en" | "fr") | null;
/** Sidebar Description */
readonly sidebar_description?: string | null;
readonly sidebar_nav_order?:
@@ -14837,6 +14912,18 @@ export interface components {
readonly options?: {
readonly [key: string]: string;
} | null;
+ /**
+ * Origin Ref
+ * @default
+ */
+ readonly origin_ref: string;
+ /**
+ * Origin Type
+ * @default conversation
+ * @enum {string}
+ */
+ readonly origin_type:
+ "conversation" | "external_import" | "document_analysis";
/** Quality */
readonly quality?: number | null;
/** Question */
@@ -14865,7 +14952,10 @@ export interface components {
* @default
*/
readonly section_title: string;
- /** Session Id */
+ /**
+ * Session Id
+ * @default
+ */
readonly session_id: string;
/**
* Source
@@ -15055,6 +15145,11 @@ export interface components {
/** Voice Autoplay */
readonly voice_autoplay: boolean;
};
+ /** VoiceMathSpeakUpdate */
+ readonly VoiceMathSpeakUpdate: {
+ /** Voice Math Speak */
+ readonly voice_math_speak: boolean;
+ };
/** VoicePreviewPayload */
readonly VoicePreviewPayload: {
/** Catalog */
@@ -15570,6 +15665,8 @@ export type SchemaResolveRequest = components["schemas"]["ResolveRequest"];
export type SchemaResumeBookRequest =
components["schemas"]["ResumeBookRequest"];
export type SchemaReviewRequest = components["schemas"]["ReviewRequest"];
+export type SchemaReviewSettingsRequest =
+ components["schemas"]["ReviewSettingsRequest"];
export type SchemaRoundSummaryRequest =
components["schemas"]["RoundSummaryRequest"];
export type SchemaRunStartRequest = components["schemas"]["RunStartRequest"];
@@ -15686,6 +15783,8 @@ export type SchemaVideoLearningSettingsRequest =
components["schemas"]["VideoLearningSettingsRequest"];
export type SchemaVoiceAutoplayUpdate =
components["schemas"]["VoiceAutoplayUpdate"];
+export type SchemaVoiceMathSpeakUpdate =
+ components["schemas"]["VoiceMathSpeakUpdate"];
export type SchemaVoicePreviewPayload =
components["schemas"]["VoicePreviewPayload"];
export type SchemaWebSourceInfo = components["schemas"]["WebSourceInfo"];
@@ -22739,6 +22838,80 @@ export interface operations {
};
};
};
+ readonly get_review_settings_api_mastery_paths_topics__path_id__review_settings_get: {
+ readonly parameters: {
+ readonly query?: never;
+ readonly header?: {
+ readonly Authorization?: string | null;
+ };
+ readonly path: {
+ readonly path_id: string;
+ };
+ readonly cookie?: {
+ readonly dt_token?: string | null;
+ };
+ };
+ readonly requestBody?: never;
+ readonly responses: {
+ /** @description Successful Response */
+ readonly 200: {
+ headers: {
+ readonly [name: string]: unknown;
+ };
+ content: {
+ readonly "application/json": unknown;
+ };
+ };
+ /** @description Validation Error */
+ readonly 422: {
+ headers: {
+ readonly [name: string]: unknown;
+ };
+ content: {
+ readonly "application/json": components["schemas"]["HTTPValidationError"];
+ };
+ };
+ };
+ };
+ readonly update_review_settings_api_mastery_paths_topics__path_id__review_settings_put: {
+ readonly parameters: {
+ readonly query?: never;
+ readonly header?: {
+ readonly Authorization?: string | null;
+ };
+ readonly path: {
+ readonly path_id: string;
+ };
+ readonly cookie?: {
+ readonly dt_token?: string | null;
+ };
+ };
+ readonly requestBody: {
+ readonly content: {
+ readonly "application/json": components["schemas"]["ReviewSettingsRequest"];
+ };
+ };
+ readonly responses: {
+ /** @description Successful Response */
+ readonly 200: {
+ headers: {
+ readonly [name: string]: unknown;
+ };
+ content: {
+ readonly "application/json": unknown;
+ };
+ };
+ /** @description Validation Error */
+ readonly 422: {
+ headers: {
+ readonly [name: string]: unknown;
+ };
+ content: {
+ readonly "application/json": components["schemas"]["HTTPValidationError"];
+ };
+ };
+ };
+ };
readonly list_topic_sessions_api_mastery_paths_topics__path_id__sessions_get: {
readonly parameters: {
readonly query?: never;
@@ -28137,8 +28310,11 @@ export interface operations {
readonly query: {
/** @description Return 204 No Content instead of 404 when the entry is absent — used by the quiz viewer to probe not-yet-saved questions without logging noisy 404s. */
readonly missing_ok?: boolean;
+ readonly origin_ref?: string;
+ readonly origin_type?:
+ "conversation" | "external_import" | "document_analysis";
readonly question_id: string;
- readonly session_id: string;
+ readonly session_id?: string;
readonly turn_id?: string | null;
};
readonly header?: {
@@ -33711,6 +33887,43 @@ export interface operations {
};
};
};
+ readonly update_voice_math_speak_api_settings_voice_math_speak_put: {
+ readonly parameters: {
+ readonly query?: never;
+ readonly header?: {
+ readonly Authorization?: string | null;
+ };
+ readonly path?: never;
+ readonly cookie?: {
+ readonly dt_token?: string | null;
+ };
+ };
+ readonly requestBody: {
+ readonly content: {
+ readonly "application/json": components["schemas"]["VoiceMathSpeakUpdate"];
+ };
+ };
+ readonly responses: {
+ /** @description Successful Response */
+ readonly 200: {
+ headers: {
+ readonly [name: string]: unknown;
+ };
+ content: {
+ readonly "application/json": unknown;
+ };
+ };
+ /** @description Validation Error */
+ readonly 422: {
+ headers: {
+ readonly [name: string]: unknown;
+ };
+ content: {
+ readonly "application/json": components["schemas"]["HTTPValidationError"];
+ };
+ };
+ };
+ };
readonly preview_voice_api_settings_voice_preview_post: {
readonly parameters: {
readonly query?: never;
diff --git a/web/contracts/schema/openapi.json b/web/contracts/schema/openapi.json
index f1ea5e9ba..4c251cec4 100644
--- a/web/contracts/schema/openapi.json
+++ b/web/contracts/schema/openapi.json
@@ -4347,7 +4347,8 @@
"language": {
"enum": [
"zh",
- "en"
+ "en",
+ "fr"
],
"title": "Language",
"type": "string"
@@ -6103,6 +6104,21 @@
"title": "Options",
"type": "object"
},
+ "origin_ref": {
+ "default": "",
+ "title": "Origin Ref",
+ "type": "string"
+ },
+ "origin_type": {
+ "default": "conversation",
+ "enum": [
+ "conversation",
+ "external_import",
+ "document_analysis"
+ ],
+ "title": "Origin Type",
+ "type": "string"
+ },
"practice": {
"anyOf": [
{
@@ -6197,6 +6213,7 @@
"type": "string"
},
"session_id": {
+ "default": "",
"title": "Session Id",
"type": "string"
},
@@ -6243,7 +6260,6 @@
},
"required": [
"id",
- "session_id",
"question",
"created_at",
"updated_at"
@@ -7235,6 +7251,12 @@
"title": "Source Anchor",
"type": "string"
},
+ "submission_id": {
+ "default": "",
+ "maxLength": 200,
+ "title": "Submission Id",
+ "type": "string"
+ },
"turn_id": {
"default": "",
"title": "Turn Id",
@@ -7278,6 +7300,12 @@
"title": "Question Id",
"type": "string"
},
+ "submission_id": {
+ "default": "",
+ "maxLength": 200,
+ "title": "Submission Id",
+ "type": "string"
+ },
"user_answer": {
"default": "",
"title": "User Answer",
@@ -7937,6 +7965,22 @@
"title": "ReviewRequest",
"type": "object"
},
+ "ReviewSettingsRequest": {
+ "description": "A per-path recall target; higher values schedule shorter intervals.",
+ "properties": {
+ "desired_retention": {
+ "maximum": 0.99,
+ "minimum": 0.7,
+ "title": "Desired Retention",
+ "type": "number"
+ }
+ },
+ "required": [
+ "desired_retention"
+ ],
+ "title": "ReviewSettingsRequest",
+ "type": "object"
+ },
"RoundSummaryRequest": {
"properties": {
"partner_id": {
@@ -10073,7 +10117,8 @@
{
"enum": [
"zh",
- "en"
+ "en",
+ "fr"
],
"type": "string"
},
@@ -10088,7 +10133,8 @@
{
"enum": [
"zh",
- "en"
+ "en",
+ "fr"
],
"type": "string"
},
@@ -11015,6 +11061,21 @@
],
"title": "Options"
},
+ "origin_ref": {
+ "default": "",
+ "title": "Origin Ref",
+ "type": "string"
+ },
+ "origin_type": {
+ "default": "conversation",
+ "enum": [
+ "conversation",
+ "external_import",
+ "document_analysis"
+ ],
+ "title": "Origin Type",
+ "type": "string"
+ },
"quality": {
"anyOf": [
{
@@ -11066,6 +11127,7 @@
"type": "string"
},
"session_id": {
+ "default": "",
"title": "Session Id",
"type": "string"
},
@@ -11108,7 +11170,6 @@
}
},
"required": [
- "session_id",
"question_id",
"question"
],
@@ -11420,6 +11481,19 @@
"title": "VoiceAutoplayUpdate",
"type": "object"
},
+ "VoiceMathSpeakUpdate": {
+ "properties": {
+ "voice_math_speak": {
+ "title": "Voice Math Speak",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "voice_math_speak"
+ ],
+ "title": "VoiceMathSpeakUpdate",
+ "type": "object"
+ },
"VoicePreviewPayload": {
"properties": {
"catalog": {
@@ -26220,6 +26294,158 @@
]
}
},
+ "/api/mastery-paths/topics/{path_id}/review-settings": {
+ "get": {
+ "operationId": "get_review_settings_api_mastery_paths_topics__path_id__review_settings_get",
+ "parameters": [
+ {
+ "in": "path",
+ "name": "path_id",
+ "required": true,
+ "schema": {
+ "title": "Path Id",
+ "type": "string"
+ }
+ },
+ {
+ "in": "header",
+ "name": "Authorization",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Authorization"
+ }
+ },
+ {
+ "in": "cookie",
+ "name": "dt_token",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Dt Token"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "Successful Response"
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ "description": "Validation Error"
+ }
+ },
+ "summary": "Get Review Settings",
+ "tags": [
+ "mastery-path"
+ ]
+ },
+ "put": {
+ "operationId": "update_review_settings_api_mastery_paths_topics__path_id__review_settings_put",
+ "parameters": [
+ {
+ "in": "path",
+ "name": "path_id",
+ "required": true,
+ "schema": {
+ "title": "Path Id",
+ "type": "string"
+ }
+ },
+ {
+ "in": "header",
+ "name": "Authorization",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Authorization"
+ }
+ },
+ {
+ "in": "cookie",
+ "name": "dt_token",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Dt Token"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ReviewSettingsRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "Successful Response"
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ "description": "Validation Error"
+ }
+ },
+ "summary": "Update Review Settings",
+ "tags": [
+ "mastery-path"
+ ]
+ }
+ },
"/api/mastery-paths/topics/{path_id}/sessions": {
"get": {
"operationId": "list_topic_sessions_api_mastery_paths_topics__path_id__sessions_get",
@@ -37271,12 +37497,38 @@
{
"in": "query",
"name": "session_id",
- "required": true,
+ "required": false,
"schema": {
+ "default": "",
"title": "Session Id",
"type": "string"
}
},
+ {
+ "in": "query",
+ "name": "origin_type",
+ "required": false,
+ "schema": {
+ "default": "conversation",
+ "enum": [
+ "conversation",
+ "external_import",
+ "document_analysis"
+ ],
+ "title": "Origin Type",
+ "type": "string"
+ }
+ },
+ {
+ "in": "query",
+ "name": "origin_ref",
+ "required": false,
+ "schema": {
+ "default": "",
+ "title": "Origin Ref",
+ "type": "string"
+ }
+ },
{
"in": "query",
"name": "question_id",
@@ -49362,6 +49614,80 @@
]
}
},
+ "/api/settings/voice-math-speak": {
+ "put": {
+ "description": "Persist whether TTS verbalizes LaTeX as spoken math.\n\nA personal UI preference (any authenticated user). The voice router reads\nthis on each synthesis call; chat does not send a per-request override.\nDollar-sign delimiters are stripped even when this is off.",
+ "operationId": "update_voice_math_speak_api_settings_voice_math_speak_put",
+ "parameters": [
+ {
+ "in": "header",
+ "name": "Authorization",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Authorization"
+ }
+ },
+ {
+ "in": "cookie",
+ "name": "dt_token",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Dt Token"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/VoiceMathSpeakUpdate"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {}
+ }
+ },
+ "description": "Successful Response"
+ },
+ "422": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HTTPValidationError"
+ }
+ }
+ },
+ "description": "Validation Error"
+ }
+ },
+ "summary": "Update Voice Math Speak",
+ "tags": [
+ "settings"
+ ]
+ }
+ },
"/api/settings/voice/preview": {
"post": {
"description": "Audition the model being edited without saving or activating its catalog.",
diff --git a/web/lib/book-api.ts b/web/lib/book-api.ts
index d7998ac96..8ea9bd3b7 100644
--- a/web/lib/book-api.ts
+++ b/web/lib/book-api.ts
@@ -361,6 +361,7 @@ export const bookApi = {
user_answer?: string;
/** Omit for a written answer the reader revealed but didn't self-grade. */
is_correct?: boolean;
+ submission_id?: string;
}) =>
request<{ progress: Progress }>("/books/quiz-attempt", {
method: "POST",
diff --git a/web/lib/reading-api.ts b/web/lib/reading-api.ts
index a818d99fc..cd4ba2205 100644
--- a/web/lib/reading-api.ts
+++ b/web/lib/reading-api.ts
@@ -371,6 +371,7 @@ export async function submitReadingQuizAnswers(
section_title?: string;
session_id?: string;
turn_id?: string;
+ submission_id?: string;
answers: ReadingQuizAnswer[];
},
): Promise<ReadingQuizAnswerVerdict[]> {
@@ -386,6 +387,7 @@ export async function submitReadingQuizAnswers(
section_title: payload.section_title || "",
session_id: payload.session_id || "",
turn_id: payload.turn_id || "",
+ submission_id: payload.submission_id || "",
answers: payload.answers.map((row) => ({
question_id: row.question_id,
selected_index: row.selected_index,