DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""Turn-runtime wiring for immersive reading.
The reader's state reaches the model through three seams in
``turn_runtime``: normalisation of the client's fields, the request snapshot
persisted with the user message, and the recovery of that snapshot on a
regenerate. Each is covered here because each fails silently — a turn simply
loses its grounding and the answer quietly gets worse.
"""
from __future__ import annotations
from pathlib import Path
import pytest
from deeptutor.reading.catalog_store import ReadingCatalogStore
from deeptutor.services.path_service import PathService
from deeptutor.services.session.sqlite_store import SQLiteSessionStore
from deeptutor.services.session.turn_runtime import (
READING_SELECTION_MAX_CHARS,
TurnRuntimeManager,
_reading_material_id,
_reading_references,
_reading_viewport,
_request_snapshot_metadata,
_workspace_mode,
)
# ---------------------------------------------------------------------------
# material id normalisation
# ---------------------------------------------------------------------------
@pytest.mark.parametrize(
"value",
["0123456789abcdef", "ABCDEF0123456789", " 0123456789abcdef ", "0123abcd"],
)
def test_content_hash_shaped_ids_are_accepted_and_lowercased(value: str) -> None:
assert _reading_material_id(value) == value.strip().lower()
@pytest.mark.parametrize(
"value",
[
None,
"",
" ",
"../../etc/passwd",
"not-hex",
"0123", # too short to be a content hash
"z" * 16,
"0123456789abcdef/../..",
123,
{"id": "0123456789abcdef"},
],
)
def test_anything_not_shaped_like_a_material_id_is_rejected(value: object) -> None:
"""The id becomes a filesystem path, so the shape is enforced at the edge."""
assert _reading_material_id(value) == ""
# ---------------------------------------------------------------------------
# viewport normalisation
# ---------------------------------------------------------------------------
def test_viewport_carries_locator_and_selection() -> None:
assert _reading_viewport({"locator": 12, "selection": "some text"}) == {
"locator": 12,
"selection": "some text",
}
def test_absent_viewport_fields_are_omitted_not_zeroed() -> None:
""" "No selection" and "an empty selection" must not look the same."""
assert _reading_viewport({"locator": 3}) == {"locator": 3}
assert _reading_viewport({"selection": "x"}) == {"selection": "x"}
assert _reading_viewport({}) == {}
assert _reading_viewport({"locator": 0, "selection": " "}) == {}
@pytest.mark.parametrize("value", [None, "not a dict", 7, [1, 2]])
def test_malformed_viewport_degrades_to_empty(value: object) -> None:
assert _reading_viewport(value) == {}
def test_nonsense_locators_are_dropped() -> None:
assert _reading_viewport({"locator": -4}) == {}
assert _reading_viewport({"locator": "abc"}) == {}
assert _reading_viewport({"locator": None}) == {}
def test_selection_is_bounded_because_it_enters_the_prompt() -> None:
viewport = _reading_viewport({"selection": "x" * (READING_SELECTION_MAX_CHARS * 3)})
assert len(viewport["selection"]) == READING_SELECTION_MAX_CHARS
def test_video_viewport_keeps_the_playback_time() -> None:
"""A video question is grounded at the moment the learner paused on."""
assert _reading_viewport({"locator": 7, "time_seconds": 600.461}) == {
"locator": 7,
"time_seconds": 600.461,
}
# 0:00 is a real position, not an absent one.
assert _reading_viewport({"time_seconds": 0}) == {"time_seconds": 0.0}
assert _reading_viewport({"time_seconds": 10**9}) == {"time_seconds": 24 * 60 * 60}
@pytest.mark.parametrize("value", [-1, "abc", float("nan"), float("inf"), True, None])
def test_nonsense_playback_times_are_dropped(value: object) -> None:
assert _reading_viewport({"locator": 2, "time_seconds": value}) == {"locator": 2}
def test_start_turn_accepts_the_video_viewport_the_reader_sends() -> None:
"""The reader reports playback time on every video turn; rejecting it at
the protocol boundary left every question about a video unsent."""
from pydantic import ValidationError
from deeptutor.api.contracts.turn_protocol import StartTurnCommand
command = StartTurnCommand.model_validate(
{
"type": "start_turn",
"protocol_version": "2.0",
"content": "What does this part mean?",
"workspace_mode": "immersive_reading",
"reading_viewport": {"locator": 7, "time_seconds": 600.461},
}
)
assert command.reading_viewport is not None
assert command.reading_viewport.time_seconds == 600.461
with pytest.raises(ValidationError):
StartTurnCommand.model_validate(
{
"type": "start_turn",
"protocol_version": "2.0",
"content": "hi",
"reading_viewport": {"locator": 7, "unknown": 1},
}
)
def test_explicit_reading_references_are_normalized_at_the_turn_boundary() -> None:
assert _reading_references(
[
{
"material_id": "ABCDEF0123456789",
"revision": 4,
"locators": [2, 2, "3"],
},
{"material_id": "../../etc", "revision": 1, "locators": [1]},
]
) == [{"material_id": "abcdef0123456789", "revision": 4, "locators": [2, 3]}]
# ---------------------------------------------------------------------------
# snapshot persistence
# ---------------------------------------------------------------------------
def _snapshot(payload: dict) -> dict:
metadata = _request_snapshot_metadata(
content="hi",
capability="",
payload=payload,
attachments=[],
config={},
notebook_references=[],
history_references=[],
question_notebook_references=[],
book_references=[],
persona="",
memory_references=[],
partner_group_references=[],
llm_selection=None,
)
return metadata["request_snapshot"]
def test_open_material_is_persisted_with_the_user_message() -> None:
"""A regenerate must re-run with the same document open."""
snapshot = _snapshot({"reading_material_id": "0123456789abcdef"})
assert snapshot["readingMaterialId"] == "0123456789abcdef"
def test_the_asked_about_passage_is_persisted_with_the_user_message() -> None:
"""The bubble shows what "this" was, and a regenerate asks about it again."""
snapshot = _snapshot(
{
"reading_material_id": "0123456789abcdef",
"reading_viewport": {"locator": 3, "selection": " the slope of the line "},
}
)
assert snapshot["readingSelection"] == {"quote": "the slope of the line", "locator": 3}
# No passage without a document it came from.
assert "readingSelection" not in _snapshot(
{"reading_viewport": {"locator": 3, "selection": "the slope"}}
)
assert "readingSelection" not in _snapshot(
{"reading_material_id": "0123456789abcdef", "reading_viewport": {"locator": 3}}
)
def test_workspace_mode_is_persisted_independently_of_the_action() -> None:
snapshot = _snapshot(
{
"workspace_mode": "immersive_reading",
"reading_material_id": "0123456789abcdef",
}
)
assert snapshot["workspaceMode"] == "immersive_reading"
@pytest.mark.parametrize(
("value", "capability", "expected"),
[
("immersive_reading", "deep_research", "immersive_reading"),
("mastery_path", "visualize", "mastery_path"),
(None, "immersive_reading", "immersive_reading"),
(None, "mastery_path", "mastery_path"),
("unknown", "chat", ""),
],
)
def test_workspace_mode_is_orthogonal_with_legacy_fallback(
value: object, capability: str, expected: str
) -> None:
assert _workspace_mode(value, capability=capability) == expected
def test_a_plain_chat_turn_carries_no_reading_key() -> None:
assert "readingMaterialId" not in _snapshot({})
assert "readingMaterialId" not in _snapshot({"reading_material_id": ""})
def test_a_bogus_id_is_not_persisted() -> None:
assert "readingMaterialId" not in _snapshot({"reading_material_id": "../../etc"})
@pytest.mark.asyncio
async def test_empty_workspace_starts_in_no_material_mode(
monkeypatch: pytest.MonkeyPatch,
tmp_path: Path,
) -> None:
monkeypatch.setenv("DEEPTUTOR_HOME", str(tmp_path))
PathService.reset_instance()
try:
workspace = ReadingCatalogStore().create_workspace("Empty reading workspace")
runtime = TurnRuntimeManager(SQLiteSessionStore(tmp_path / "turns.sqlite3"))
async def _noop_run_turn(_execution) -> None:
return None
monkeypatch.setattr(runtime, "_run_turn", _noop_run_turn)
_session, turn = await runtime.start_turn(
{
"type": "start_turn",
"capability": "chat",
"workspace_mode": "immersive_reading",
"reading_workspace_id": workspace.workspace_id,
"content": "What can I read here?",
"tools": [],
"knowledge_bases": [],
"attachments": [],
"language": "en",
"config": {},
}
)
assert runtime._executions[turn["id"]].payload["reading_material_id"] == ""
detail = await runtime.store.get_session(_session["id"])
assert detail is not None
assert detail["preferences"]["workspace_mode"] == "immersive_reading"
assert detail["preferences"]["capability"] == "chat"
finally:
PathService.reset_instance()
def test_explicit_reading_references_are_persisted_for_retry() -> None:
snapshot = _request_snapshot_metadata(
content="hi",
capability="chat",
payload={},
attachments=[],
config={},
notebook_references=[],
history_references=[],
partner_group_references=[],
question_notebook_references=[],
book_references=[],
reading_references=[{"material_id": "abcdef0123456789", "revision": 1, "locators": [1, 2]}],
persona="",
memory_references=[],
llm_selection=None,
)["request_snapshot"]
assert snapshot["readingReferences"] == [
{"material_id": "abcdef0123456789", "revision": 1, "locators": [1, 2]}
]