Skip to content

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

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.py
index 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.py
index 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, Request
from pydantic import BaseModel, Field, field_validator
from deeptutor.learning.storage import LearningStore
+from deeptutor.reading.catalog_store import ReadingCatalogStore
from deeptutor.response_languages import validate_reply_language_override
from deeptutor.services.session import get_session_store, get_sqlite_session_store
from 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.py
index 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_retry
from 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.py
index 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_retry
from 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.py
index 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_retry
from 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.py
index 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, mo
learning = 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, mo
assert await store.restore_session(sid) is False
attachments.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 None
assert len(await store.get_messages("other")) == 1
diff --git a/tests/reading/test_extension_router.py b/tests/reading/test_extension_router.py
index 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.py
index 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_extensions
from deeptutor.reading import ReadingStore
from deeptutor.reading.extensions import ReadingContext, ReadingExtensionRegistry
from deeptutor.reading.quiz import ReadingQuizExtension
+from deeptutor.services.llm.reasoning_params import RETRY_REASONING_EFFORT
from 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.py
index 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_extensions
from deeptutor.reading import ReadingStore
from deeptutor.reading.extensions import ReadingContext, ReadingExtensionRegistry
from deeptutor.reading.study_guidance import StudyGuidanceExtension
+from deeptutor.services.llm.reasoning_params import RETRY_REASONING_EFFORT
from 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.asyncio
diff --git a/tests/reading/test_vocabulary.py b/tests/reading/test_vocabulary.py
index 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_extensions
from deeptutor.reading import ReadingStore
from deeptutor.reading.extensions import ReadingContext, ReadingExtensionRegistry
from deeptutor.reading.vocabulary import VocabularyExtension
+from deeptutor.services.llm.reasoning_params import RETRY_REASONING_EFFORT
from 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