DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(reading): make selection actions reliable and sync reading sessions
Bingxi Zhao (Frank)66ba712172ca
diff --git a/deeptutor/api/routers/reading_extensions.py b/deeptutor/api/routers/reading_extensions.pyindex b664f355d..e9fbcee22 100644--- a/deeptutor/api/routers/reading_extensions.py+++ b/deeptutor/api/routers/reading_extensions.py@@ -80,7 +80,27 @@ def _normal(value: str) -> str:def _verified_selection(candidate: str, unit_text: str) -> str:value = _normal(candidate)- return value if value and value in _normal(unit_text) else ""+ if not value:+ return ""+ unit = _normal(unit_text)+ if value in unit:+ return value+ # A PDF's text layer and its extracted text disagree about where the+ # breaks go: margin line numbers the extractor put on their own lines+ # ("Language\n1\nModels") reach the browser glued to the word before them+ # ("Language1 Models"). Whitespace carries no content, so match without+ # it, and hand the extension the material's own spelling of the span.+ compact: list[str] = []+ positions: list[int] = []+ for index, character in enumerate(unit):+ if not character.isspace():+ compact.append(character)+ positions.append(index)+ needle = re.sub(r"\s+", "", value)+ found = "".join(compact).find(needle)+ if found < 0:+ return ""+ return unit[positions[found] : positions[found + len(needle) - 1] + 1]def _discard_late_worker_result(worker: asyncio.Future) -> None:diff --git a/deeptutor/api/routers/sessions.py b/deeptutor/api/routers/sessions.pyindex 9aa42b647..4cdb66a9d 100644--- a/deeptutor/api/routers/sessions.py+++ b/deeptutor/api/routers/sessions.py@@ -12,6 +12,7 @@ from fastapi import APIRouter, HTTPException, Query, Requestfrom pydantic import BaseModel, Field, field_validatorfrom deeptutor.learning.storage import LearningStore+from deeptutor.reading.catalog_store import ReadingCatalogStorefrom deeptutor.response_languages import validate_reply_language_overridefrom deeptutor.services.session import get_session_store, get_sqlite_session_storefrom deeptutor.services.session.organization import (@@ -248,6 +249,12 @@ async def rename_session(session_id: str, payload: SessionRenameRequest):updated = await store.update_session_title(session_id, payload.title)if not updated:raise HTTPException(status_code=404, detail="Session not found")+ # The reader keeps its own list of a collection's conversations; the+ # sidebar is where they are renamed, so the list has to hear about it.+ try:+ await asyncio.to_thread(ReadingCatalogStore().retitle_session, session_id, payload.title)+ except Exception:+ logger.exception("failed to retitle reading conversation %s", session_id)session = await store.get_session(session_id)return {"session": session}@@ -418,6 +425,10 @@ async def _cleanup_deleted_session(session_id: str) -> None:await get_attachment_store().delete_session(session_id)except Exception:logger.exception("failed to clean up attachments for session %s", session_id)+ try:+ await asyncio.to_thread(ReadingCatalogStore().forget_session, session_id)+ except Exception:+ logger.exception("failed to detach reading collections for session %s", session_id)@router.post("/{session_id}/restore")diff --git a/deeptutor/reading/quiz.py b/deeptutor/reading/quiz.pyindex fa441123d..14ffceb5b 100644--- a/deeptutor/reading/quiz.py+++ b/deeptutor/reading/quiz.py@@ -14,8 +14,8 @@ from deeptutor.reading.extensions import (ReadingExtensionResult,)from deeptutor.services.llm import complete+from deeptutor.services.llm.structured_retry import json_with_reasoning_retryfrom deeptutor.services.prompt.language import is_chinese as _is_zh-from deeptutor.utils.json_parser import parse_json_response_SYSTEM_EN = """You write a short comprehension quiz from one verified reading context.@@ -63,9 +63,8 @@ def _normalise(value: str) -> str:return " ".join(value.casefold().split())-def _quiz(raw: str, context: ReadingContext) -> _Quiz:- data: Any = parse_json_response(raw, fallback=None)- if not isinstance(data, dict):+def _quiz(data: Any, context: ReadingContext) -> _Quiz:+ if not isinstance(data, dict) or not data:raise ValueError("Reading quiz model returned invalid JSON.")try:quiz = _Quiz.model_validate({"questions": data.get("questions")})@@ -99,16 +98,23 @@ class ReadingQuizExtension:from deeptutor.services.model_selection.tasks import TaskKind, task_llm_scope- with task_llm_scope(TaskKind.READING_QUIZ):- raw = await complete(+ async def _run(reasoning_effort: str | None) -> str:+ return await complete(prompt=_prompt(context),system_prompt=_SYSTEM_ZH if _is_zh(context.locale) else _SYSTEM_EN,temperature=0.3,- max_tokens=1000,+ max_tokens=2_500,max_retries=0,response_format={"type": "json_object"},+ reasoning_effort=reasoning_effort,+ )++ with task_llm_scope(TaskKind.READING_QUIZ):+ data = await json_with_reasoning_retry(+ _run,+ expected_key="questions",)- quiz = _quiz(raw, context)+ quiz = _quiz(data, context)return ReadingExtensionResult(type="quiz",title="阅读测验" if _is_zh(context.locale) else "Reading quiz",diff --git a/deeptutor/reading/study_guidance.py b/deeptutor/reading/study_guidance.pyindex 7eb952b0d..5e78a3fa7 100644--- a/deeptutor/reading/study_guidance.py+++ b/deeptutor/reading/study_guidance.py@@ -14,8 +14,8 @@ from deeptutor.reading.extensions import (ReadingExtensionResult,)from deeptutor.services.llm import complete+from deeptutor.services.llm.structured_retry import json_with_reasoning_retryfrom deeptutor.services.prompt.language import is_chinese as _is_zh-from deeptutor.utils.json_parser import parse_json_response_SYSTEM_EN = """You design the learner's next three study moves from one verified reading selection.@@ -48,9 +48,8 @@ class _Guidance(BaseModel):return value-def _guidance(raw: str) -> _Guidance:- data: Any = parse_json_response(raw, fallback=None)- if not isinstance(data, dict):+def _guidance(data: Any) -> _Guidance:+ if not isinstance(data, dict) or not data:raise ValueError("Study guidance model returned invalid JSON.")try:return _Guidance.model_validate({"focus": data.get("focus"), "steps": data.get("steps")})@@ -79,16 +78,20 @@ class StudyGuidanceExtension:from deeptutor.services.model_selection.tasks import TaskKind, task_llm_scope- with task_llm_scope(TaskKind.READING_GUIDANCE):- raw = await complete(+ async def _run(reasoning_effort: str | None) -> str:+ return await complete(prompt=_prompt(context),system_prompt=_SYSTEM_ZH if _is_zh(context.locale) else _SYSTEM_EN,temperature=0.2,- max_tokens=500,+ max_tokens=2_000,max_retries=0,response_format={"type": "json_object"},+ reasoning_effort=reasoning_effort,)- guidance = _guidance(raw)++ with task_llm_scope(TaskKind.READING_GUIDANCE):+ data = await json_with_reasoning_retry(_run, expected_key="steps")+ guidance = _guidance(data)return ReadingExtensionResult(type="card",title="学习引导" if _is_zh(context.locale) else "Study guidance",diff --git a/deeptutor/reading/vocabulary.py b/deeptutor/reading/vocabulary.pyindex bac33bd2d..8e9540d99 100644--- a/deeptutor/reading/vocabulary.py+++ b/deeptutor/reading/vocabulary.py@@ -15,8 +15,8 @@ from deeptutor.reading.extensions import (ReadingExtensionResult,)from deeptutor.services.llm import complete+from deeptutor.services.llm.structured_retry import json_with_reasoning_retryfrom deeptutor.services.prompt.language import is_chinese as _is_zh-from deeptutor.utils.json_parser import parse_json_response_SYSTEM_EN = """You explain vocabulary from one verified reading selection.@@ -70,9 +70,8 @@ def _term_comes_from_selection(term: str, selection: str) -> bool:return normalized_term in normalized_selection-def _vocabulary(raw: str, selection: str) -> _Vocabulary:- data: Any = parse_json_response(raw, fallback=None)- if not isinstance(data, dict):+def _vocabulary(data: Any, selection: str) -> _Vocabulary:+ if not isinstance(data, dict) or not data:raise ValueError("Vocabulary model returned invalid JSON.")try:vocabulary = _Vocabulary.model_validate({"terms": data.get("terms")})@@ -105,16 +104,20 @@ class VocabularyExtension:from deeptutor.services.model_selection.tasks import TaskKind, task_llm_scope- with task_llm_scope(TaskKind.READING_VOCABULARY):- raw = await complete(+ async def _run(reasoning_effort: str | None) -> str:+ return await complete(prompt=_prompt(context),system_prompt=_SYSTEM_ZH if _is_zh(context.locale) else _SYSTEM_EN,temperature=0.2,- max_tokens=800,+ max_tokens=2_000,max_retries=0,response_format={"type": "json_object"},+ reasoning_effort=reasoning_effort,)- vocabulary = _vocabulary(raw, context.selection)++ with task_llm_scope(TaskKind.READING_VOCABULARY):+ data = await json_with_reasoning_retry(_run, expected_key="terms")+ vocabulary = _vocabulary(data, context.selection)return ReadingExtensionResult(type="card",title="词汇帮助" if _is_zh(context.locale) else "Vocabulary help",diff --git a/tests/api/test_sessions_permanent_delete.py b/tests/api/test_sessions_permanent_delete.pyindex 49a853d42..93d2cbfd8 100644--- a/tests/api/test_sessions_permanent_delete.py+++ b/tests/api/test_sessions_permanent_delete.py@@ -20,6 +20,8 @@ async def test_delete_removes_conversation_descendants_and_messages(tmp_path, molearning = SimpleNamespace(detach_session=Mock())monkeypatch.setattr(router, "get_attachment_store", lambda: attachments)monkeypatch.setattr(router, "LearningStore", lambda: learning)+ reading = SimpleNamespace(forget_session=Mock())+ monkeypatch.setattr(router, "ReadingCatalogStore", lambda: reading)runtime = SimpleNamespace(cancel_turn=AsyncMock())monkeypatch.setattr("deeptutor.services.session.get_turn_runtime_manager", lambda: runtime)monkeypatch.setattr(@@ -35,6 +37,7 @@ async def test_delete_removes_conversation_descendants_and_messages(tmp_path, moassert await store.restore_session(sid) is Falseattachments.delete_session.assert_any_await(sid)learning.detach_session.assert_any_call(sid)+ reading.forget_session.assert_any_call(sid)runtime.cancel_turn.assert_any_await(f"turn-{sid}")assert await store.get_session("other") is not Noneassert len(await store.get_messages("other")) == 1diff --git a/tests/reading/test_extension_router.py b/tests/reading/test_extension_router.pyindex 3057aa7ec..eb7b5d7ee 100644--- a/tests/reading/test_extension_router.py+++ b/tests/reading/test_extension_router.py@@ -140,6 +140,43 @@ def test_selection_requirement_rejects_unverified_text(material, monkeypatch):assert response.status_code == 400+def test_selection_matches_across_line_breaks_the_text_layer_dropped(monkeypatch, tmp_path):+ # Margin line numbers: extracted onto their own lines, but the browser's+ # selection glues each one to the word before it.+ monkeypatch.setenv("DEEPTUTOR_HOME", str(tmp_path))+ PathService.reset_instance()+ source = tmp_path / "paper.txt"+ source.write_text(+ "applications for Large Language\n1\nModels (LLMs). However, current LLMs rely on "+ "static pre-training knowledge\n2\nand lack adaptation.",+ encoding="utf-8",+ )+ manifest = ReadingStore().ingest(source)+ captured = {}++ def run(_action, context):+ captured.update(context.model_dump())+ return ReadingExtensionResult(type="card", payload={"body": "ok"})++ client = _client(monkeypatch, _extension(run, requires=("selection",)))+ try:+ response = client.post(+ f"/api/reading/materials/{manifest.material_id}/extensions/sample/actions/open",+ json={+ "locator": 1,+ "selection": "Large Language1 Models (LLMs). However, current LLMs rely on "+ "static pre-training knowledge2 and lack",+ },+ )+ finally:+ PathService.reset_instance()+ assert response.status_code == 200, response.text+ assert captured["selection"] == (+ "Large Language 1 Models (LLMs). However, current LLMs rely on "+ "static pre-training knowledge 2 and lack"+ )++def test_oversized_unit_returns_protocol_error(material, monkeypatch):unit_path = ReadingStore().root / material.material_id / "units" / "0001.txt"unit_path.write_text("x" * 60_001, encoding="utf-8")diff --git a/tests/reading/test_quiz.py b/tests/reading/test_quiz.pyindex 1db496077..50ccc0288 100644--- a/tests/reading/test_quiz.py+++ b/tests/reading/test_quiz.py@@ -12,6 +12,7 @@ from deeptutor.api.routers import reading_extensionsfrom deeptutor.reading import ReadingStorefrom deeptutor.reading.extensions import ReadingContext, ReadingExtensionRegistryfrom deeptutor.reading.quiz import ReadingQuizExtension+from deeptutor.services.llm.reasoning_params import RETRY_REASONING_EFFORTfrom deeptutor.services.path_service import PathService@@ -73,6 +74,41 @@ async def test_quiz_returns_a_bounded_quiz_without_grounding_metadata(monkeypatc"correct_choice_index": 1,}assert calls[0]["response_format"] == {"type": "json_object"}+ assert len(calls) == 1+++async def test_quiz_retries_an_empty_model_answer_with_lower_reasoning(monkeypatch):+ calls = []++ async def complete(**kwargs):+ calls.append(kwargs)+ return "" if len(calls) == 1 else _model_response()++ monkeypatch.setattr("deeptutor.reading.quiz.complete", complete)+ result = await ReadingQuizExtension().run_action("start", _context())++ assert len(result.payload["questions"]) == 3+ assert [call["reasoning_effort"] for call in calls] == [+ None,+ RETRY_REASONING_EFFORT,+ ]+ assert calls[0]["prompt"] == calls[1]["prompt"]+++async def test_quiz_stops_after_two_empty_model_answers(monkeypatch):+ calls = []++ async def complete(**kwargs):+ calls.append(kwargs)+ return ""++ monkeypatch.setattr("deeptutor.reading.quiz.complete", complete)+ with pytest.raises(ValueError, match="invalid JSON"):+ await ReadingQuizExtension().run_action("start", _context())++ assert len(calls) == 2@pytest.mark.asyncio@@ -182,10 +218,12 @@ def test_quiz_crosses_the_api_boundary_with_stored_text(monkeypatch, tmp_path):encoding="utf-8",)material = ReadingStore().ingest(source)- captured = {}+ calls = []async def complete(**kwargs):- captured.update(kwargs)+ calls.append(kwargs)+ if len(calls) == 1:+ return ""return _model_response(evidence="verified phrase supports the answer")monkeypatch.setattr("deeptutor.reading.quiz.complete", complete)@@ -207,7 +245,8 @@ def test_quiz_crosses_the_api_boundary_with_stored_text(monkeypatch, tmp_path):body = response.json()assert body["type"] == "quiz"assert len(body["payload"]["questions"]) == 3- prompt = json.loads(captured["prompt"])+ assert len(calls) == 2+ prompt = json.loads(calls[1]["prompt"])assert prompt["selection"] == "verified phrase supports the answer"assert ("Stored passage where a verified phrase supports the answer."diff --git a/tests/reading/test_study_guidance.py b/tests/reading/test_study_guidance.pyindex c4497983e..ef29a57d2 100644--- a/tests/reading/test_study_guidance.py+++ b/tests/reading/test_study_guidance.py@@ -12,6 +12,7 @@ from deeptutor.api.routers import reading_extensionsfrom deeptutor.reading import ReadingStorefrom deeptutor.reading.extensions import ReadingContext, ReadingExtensionRegistryfrom deeptutor.reading.study_guidance import StudyGuidanceExtension+from deeptutor.services.llm.reasoning_params import RETRY_REASONING_EFFORTfrom deeptutor.services.path_service import PathService@@ -57,6 +58,52 @@ async def test_study_guidance_returns_a_bounded_card(monkeypatch):assert prompt["selection"] == "verified phrase"assert "Before context" in prompt["surrounding_context"]assert calls[0]["response_format"] == {"type": "json_object"}+ assert len(calls) == 1+++async def test_study_guidance_retries_an_empty_model_answer_with_lower_reasoning(monkeypatch):+ calls = []++ async def complete(**kwargs):+ calls.append(kwargs)+ if len(calls) == 1:+ return ""+ return json.dumps(+ {+ "focus": "Connect the phrase to its surrounding argument.",+ "steps": [+ "Locate the two claims nearest the selected phrase.",+ "Explain how the phrase links those two claims.",+ "Rewrite the linked idea in one sentence.",+ ],+ }+ )++ monkeypatch.setattr("deeptutor.reading.study_guidance.complete", complete)+ result = await StudyGuidanceExtension().run_action("guide", _context())++ assert len(result.payload["steps"]) == 3+ assert [call["reasoning_effort"] for call in calls] == [+ None,+ RETRY_REASONING_EFFORT,+ ]+ assert calls[0]["prompt"] == calls[1]["prompt"]+++async def test_study_guidance_stops_after_two_empty_model_answers(monkeypatch):+ calls = []++ async def complete(**kwargs):+ calls.append(kwargs)+ return ""++ monkeypatch.setattr("deeptutor.reading.study_guidance.complete", complete)+ with pytest.raises(ValueError, match="invalid JSON"):+ await StudyGuidanceExtension().run_action("guide", _context())++ assert len(calls) == 2@pytest.mark.asynciodiff --git a/tests/reading/test_vocabulary.py b/tests/reading/test_vocabulary.pyindex 573795a0b..04f90e2db 100644--- a/tests/reading/test_vocabulary.py+++ b/tests/reading/test_vocabulary.py@@ -12,6 +12,7 @@ from deeptutor.api.routers import reading_extensionsfrom deeptutor.reading import ReadingStorefrom deeptutor.reading.extensions import ReadingContext, ReadingExtensionRegistryfrom deeptutor.reading.vocabulary import VocabularyExtension+from deeptutor.services.llm.reasoning_params import RETRY_REASONING_EFFORTfrom deeptutor.services.path_service import PathService@@ -64,6 +65,41 @@ async def test_vocabulary_returns_a_bounded_card(monkeypatch):assert prompt["selection"] == "verified phrase"assert "Before context" in prompt["surrounding_context"]assert calls[0]["response_format"] == {"type": "json_object"}+ assert len(calls) == 1+++async def test_vocabulary_retries_an_empty_model_answer_with_lower_reasoning(monkeypatch):+ calls = []++ async def complete(**kwargs):+ calls.append(kwargs)+ return "" if len(calls) == 1 else _model_response()++ monkeypatch.setattr("deeptutor.reading.vocabulary.complete", complete)+ result = await VocabularyExtension().run_action("explain", _context())++ assert result.payload["terms"][0]["term"] == "verified"+ assert [call["reasoning_effort"] for call in calls] == [+ None,+ RETRY_REASONING_EFFORT,+ ]+ assert calls[0]["prompt"] == calls[1]["prompt"]+++async def test_vocabulary_stops_after_two_empty_model_answers(monkeypatch):+ calls = []++ async def complete(**kwargs):+ calls.append(kwargs)+ return ""++ monkeypatch.setattr("deeptutor.reading.vocabulary.complete", complete)+ with pytest.raises(ValueError, match="invalid JSON"):+ await VocabularyExtension().run_action("explain", _context())++ assert len(calls) == 2@pytest.mark.asyncio