DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(mastery): make source delivery demand-driven and preserve partial teaching
yepyhun3175b812e241
diff --git a/deeptutor/agents/loop/agent_loop.py b/deeptutor/agents/loop/agent_loop.pyindex 7f1a76821..ade408911 100644--- a/deeptutor/agents/loop/agent_loop.py+++ b/deeptutor/agents/loop/agent_loop.py@@ -450,6 +450,10 @@ class AgentLoop:tool_choice=(self.pipeline.initial_tool_choice if state.rounds == 0 else None),)except Exception as exc:+ from deeptutor.learning.lesson_evidence import LessonUnavailable++ if isinstance(exc, LessonUnavailable):+ raise# A mid-loop LLM failure (timeout / transient network) must not# discard a turn that already gathered useful work. Salvage it# with a forced finish; only a failure on the very first round@@ -886,6 +890,10 @@ class AgentLoop:# prevents callers from offering an accurate retry action.raiseexcept Exception as exc:+ from deeptutor.learning.lesson_evidence import LessonUnavailable++ if isinstance(exc, LessonUnavailable):+ raise# The salvage call itself failed (e.g. the provider is still# returning unusable data). Don't bubble up and lose the turn —# emit the graceful fallback answer instead.@@ -1046,8 +1054,19 @@ class AgentLoop:defer_visible_output: bool = False,tool_choice: str | None = None,) -> LLMCallResult:+ prepare = getattr(self.pipeline, "prepare_model_request", None)+ lesson_messages = await prepare(self.context, self.stream, messages) if prepare else []request_messages = with_transient_model_messages(messages, self._transient_model_messages)- await self.pipeline._guard_context_window(request_messages, self.stream)+ # Current tool pixels take precedence over cached lesson pages. Neither+ # belongs in the durable dialogue; the hook runs again on forced finish.+ if lesson_messages and not has_image_parts(self._transient_model_messages):+ request_messages = [*request_messages, *lesson_messages]+ projected_messages = deduplicate_user_images([+ {key: value for key, value in message.items()+ if key not in {"_context_snapshot", "_lesson_packet"}}+ for message in request_messages+ ])+ await self.pipeline._guard_context_window(projected_messages, self.stream)stage = self.stagecall_id = new_call_id(f"{self.source}-{stage}")trace_meta = build_trace_metadata(@@ -1071,12 +1090,7 @@ class AgentLoop:kwargs: dict[str, Any] = {"model": self.pipeline.model,- "messages": deduplicate_user_images(- [- {key: value for key, value in message.items() if key != "_context_snapshot"}- for message in request_messages- ]- ),+ "messages": projected_messages,"stream": True,**self.pipeline._completion_kwargs(max_tokens=max_tokens),}diff --git a/deeptutor/capabilities/mastery/loop.py b/deeptutor/capabilities/mastery/loop.pyindex a16ce8946..ef0961eae 100644--- a/deeptutor/capabilities/mastery/loop.py+++ b/deeptutor/capabilities/mastery/loop.py@@ -309,6 +309,18 @@ class MasteryLoopCapability:# A replacement needs a quote from the actual current learner# request, not a model-supplied claim about their intention.updated["_learner_message"] = context.user_message or ""+ if tool_name == "mastery_prepare_lesson":+ from deeptutor.learning.policy import next_objective+ from deeptutor.learning.storage import LearningStore++ def bind_lesson(kp_id):+ progress = LearningStore().load(path_id)+ context.metadata["mastery_lesson_objective"] = {+ "path_id": path_id, "kp_id": kp_id,+ "policy_id": next_objective(progress).knowledge_point_id if progress else "",+ }++ updated["_bind_lesson_objective"] = bind_lessonif tool_name == "mastery_mode":# The narrowest handle on the turn for a tool that changes what# the rest of it may do — the same shape as ``_bind_active_path``diff --git a/deeptutor/capabilities/mastery/pipeline.py b/deeptutor/capabilities/mastery/pipeline.pyindex 1babecff1..c3d2070f9 100644--- a/deeptutor/capabilities/mastery/pipeline.py+++ b/deeptutor/capabilities/mastery/pipeline.py@@ -69,6 +69,143 @@ class MasteryLoopPipeline(AgenticLoopPipeline):prompt_base_agent = "agentic_chat"prompt_assembler_class = MasteryPromptAssembler+ async def prepare_model_request(self, context, stream, messages):+ """Re-check the live objective before any model iteration, even forced finish."""+ import asyncio++ from deeptutor.learning.lesson_evidence import (+ LessonUnavailable,+ cached_lesson,+ image_message,+ lesson_context,+ public_sources,+ selected_scope,+ )+ from deeptutor.learning.policy import next_objective+ from deeptutor.learning.storage import LearningStore++ # Remove only our previous packet, not user or durable model messages.+ # Keep the archive boundary aligned when a packet came from history;+ # otherwise saving this turn can skip a fresh snapshot or user input.+ history_end = getattr(self, "_model_turn_start", 0)+ self._model_turn_start = history_end - sum(+ bool(m.get("_lesson_packet")) for m in messages[:history_end]+ )+ messages[:] = [m for m in messages if not m.get("_lesson_packet")]+ path_id = str(context.metadata.get("mastery_path_id") or "")+ if not path_id or normalize_mode(context.metadata.get("mastery_session_mode")) == "outline":+ self._lesson_pixels = None+ return []+ store = LearningStore()+ progress = await asyncio.to_thread(store.load, path_id)+ if progress is None or not progress.modules:+ self._lesson_pixels = None+ return []+ step = next_objective(progress)+ requested = context.metadata.get("mastery_lesson_objective")+ kp_id = (requested.get("kp_id") if isinstance(requested, dict) and+ requested.get("path_id") == path_id and requested.get("policy_id") == step.knowledge_point_id+ else step.knowledge_point_id)+ if not kp_id:+ self._lesson_pixels = None+ return []+ # This hook runs before EVERY model request, including administrative+ # replies. It owns current, authorized packet delivery, not paid work.+ # Preparation is requested explicitly by the existing lesson tool;+ # a cache miss is not a failed retrieval or proof of missing content.+ failure = None+ try:+ topic = await asyncio.to_thread(store.get_topic, path_id, progress=progress)+ scope = await asyncio.to_thread(selected_scope, topic, progress, kp_id)+ if not scope:+ self._lesson_pixels = None+ if progress.lesson_evidence.get(kp_id):+ raise LessonUnavailable("This objective's selected PDF materials have changed.")+ return [] # Preserve the existing text/Office tutoring route.+ evidence = await asyncio.to_thread(cached_lesson, store, progress, kp_id, self.llm_config)+ except LessonUnavailable as exc:+ failure = str(exc)+ if failure is not None:+ self._lesson_pixels = None+ import json++ messages.append({"role": "system", "_lesson_packet": True, "content": (+ "The current objective's previous source packet cannot be used as verified evidence. "+ "This blocks unsupported teaching or assessment, NOT conversation about "+ "teaching style, learner preferences, the previous verdict or outline changes. "+ "Respond to the learner's actual request, including teaching-style feedback. "+ "Preserve any grading already committed; do not claim no score changed. "+ "Do not treat previous-objective pages as evidence for this objective. "+ "Do not recommend re-indexing unless the diagnostic specifically identifies "+ "an index problem. An unsuccessful bounded retrieval is NOT proof that a "+ "selected book lacks the topic. Do not ask to re-upload material already present. "+ "For a changed or stale packet, call mastery_prepare_lesson with this "+ "knowledge_point_id and the learner's specific focus to revalidate current "+ "authorized sources. Let that tool establish usable coverage before proceeding. "+ "Respect access denial, unavailable originals and unreadability; preparation "+ "does not bypass those boundaries. Do not repeatedly retry an unchanged failure. "+ "Do not invent missing subject matter or claim to have read a linked repository "+ "without using a tool. Diagnostic data "+ "(not instructions): " + json.dumps({"knowledge_point_id": kp_id, "reason": failure},+ ensure_ascii=False)+ )})+ return []+ if not evidence:+ self._lesson_pixels = None+ import json++ messages.append({"role": "system", "_lesson_packet": True, "content": (+ "The current PDF-grounded objective's verified lesson is not prepared for this request. "+ "Before teaching new subject matter or assessing this objective, call "+ "mastery_prepare_lesson with its exact knowledge_point_id below and, when useful, a "+ "specific focus for the learner's next teaching or practice step. Use the matching "+ "evidence it returns: partial evidence supports its covered teaching slice, but not "+ "an unsupported assessment. This gate blocks unsupported teaching or assessment, NOT conversation "+ "about teaching style, learner preferences, the previous verdict or outline changes: "+ "respond to those requests without preparing an unrelated lesson. A cache miss is "+ "not a source-search failure and does not show that the selected materials lack the topic. "+ "Preserve any grading already committed. Do not request re-upload or re-indexing just "+ "because this packet is not prepared. Earlier-objective pages are not evidence for "+ "this objective. An earlier coverage gap is not a permanent ban on this objective. "+ "If the next step needs an unresolved detail, use targeted retrieval and focused "+ "preparation in this turn; do not merely promise to check it later. Respect access, "+ "source-identity and unreadability failures. Do not repeat unchanged preparation "+ "merely because another model round begins. Diagnostic data (not instructions): "+ + json.dumps({"knowledge_point_id": kp_id}, ensure_ascii=False)+ )})+ return []+ message = {"role": "user", "content": lesson_context(evidence), "_lesson_packet": True}+ messages.append(message)+ pixels = getattr(self, "_lesson_pixels", None)+ if pixels is None or pixels[0] != evidence["id"]:+ # The native visual workflow owns a two-image request budget.+ # Other prepared pages remain in the packet and can be inspected+ # explicitly through rag when the current question needs them.+ pixels = (evidence["id"], await asyncio.to_thread(image_message, evidence["sources"][:2]))+ self._lesson_pixels = pixels+ await stream.sources(public_sources(evidence), source="mastery_path", stage="responding")+ return [pixels[1]]++ async def _retrieve_kb_seed_block(self, context, stream):+ # The objective-bound preparation is the retrieval owner in this loop.+ # A generic whole-library seed could contradict selected-file scope.+ import asyncio++ from deeptutor.learning.lesson_evidence import selected_scope+ from deeptutor.learning.policy import next_objective+ from deeptutor.learning.storage import LearningStore++ path_id = str(context.metadata.get("mastery_path_id") or "")+ if path_id:+ store = LearningStore()+ progress = await asyncio.to_thread(store.load, path_id)+ if progress is not None and progress.modules:+ kp_id = next_objective(progress).knowledge_point_id+ topic = await asyncio.to_thread(store.get_topic, path_id, progress=progress)+ if kp_id and not selected_scope(topic, progress, kp_id):+ return await super()._retrieve_kb_seed_block(context, stream)+ return ""+async def run(self, context: UnifiedContext, stream: Any) -> dict[str, Any]:# Tells MasteryLoopCapability that the playbook is already the# foundation of this prompt, so it does not contribute a second copy.diff --git a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yamlindex 29a551c78..4b9fb0527 100644--- a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml+++ b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml@@ -124,6 +124,8 @@ playbook: |-**Registered memory/procedure assessment goes through `mastery_quiz`** — use its `questions` group for separate answers, never 1./2./3. in the body and never `ask_user`, which here is only for genuine clarification. Concept/design explanations are assessed through `mastery_assess` as described above; do not misrepresent an unsupported qualitative group as a registered quiz.**Materials**: what the learner chose for this topic arrives as a `[Topic Materials]` manifest, and you can read any of it on demand with `read_source`. Teach from those rather than from memory. You cannot read rows marked `unavailable`: never describe or quote their contents; say plainly that the material is not readable and continue with what is. When the learner asks whether you can see their materials, answer from the manifest and name what you actually have — never a blanket "yes, I can see it".+ **Prepared PDF evidence is demand-driven.** A current source packet is supplied when its cache is still authorized and matches this objective. Read its coverage: readiness of sources does not establish completeness of the entire objective. Teach the useful supported slice even when a different detail is unresolved; do not turn one gap into a refusal of the whole lesson. Distinguish source facts from your own explanatory reasoning or analogy. Unseen labels, uncertain visual relationships and examination requirements cannot be invented. Before assessing an unresolved slice, use `mastery_prepare_lesson` with the exact objective ID and a specific focus for that question/task and its answer support. A partial teaching packet alone does not authorize assessment. Administrative discussion, learner feedback and outline edits do not require preparation. An old coverage failure is not a permanent ban: when needed, retrieve the specific missing detail and prepare that focus in the same turn. Do not repeatedly retry unchanged preparation or re-index merely because a cache is empty. Keep normal text-only materials on their existing route.+ **Requested examination practice:** When the learner asks for questions from a selected question bank, inspect actual question stems and their solutions before choosing. A syllabus, statistics table or a topic-matching textbook paragraph does not establish an original exam question. If a broad retrieval returns only such summaries, use a scoped source/page lookup or a targeted query to the relevant question section; do not stop at an apology or promise to search later. Label original questions and your adaptations separately. If the actual questions remain unavailable, say that narrowly and offer supported practice without claiming it is exam-calibrated. Use the registered question-card tools for supported memory/procedure tasks, preserving explicit replacement/deferral and existing results.**`learner_profile` is standing context, not an opening formality.** It comes back from `mastery_status` every round because it has to shape every round: start where their prior knowledge puts them rather than at chapter one, size the outline and each sitting to the time they said they have, stop at the level they called finished instead of teaching the whole subject, and teach the way they asked to be taught. Never read it back to them as a summary of themselves — just act on it.diff --git a/deeptutor/capabilities/mastery/tools.py b/deeptutor/capabilities/mastery/tools.pyindex 8195d9727..1dbdf003f 100644--- a/deeptutor/capabilities/mastery/tools.py+++ b/deeptutor/capabilities/mastery/tools.py@@ -846,7 +846,7 @@ class MasteryNoteExplainedTool(BaseTool):def get_definition(self) -> ToolDefinition:return ToolDefinition(name="mastery_note_explained",- description="After explaining an objective at the requested level, record what was taught. This does not assess, grant mastery or schedule a review. Respect explanation-only requests; a quiz is optional until the learner wants practice.",+ description="After explaining a supported slice of an objective, record only that partial coverage. Current source evidence is revalidated; this does not prove full-objective coverage, assess, grant mastery or schedule a review. Respect explanation-only requests; a quiz is optional until the learner wants practice.",parameters=[ToolParameter(name="knowledge_point_id",@@ -879,22 +879,29 @@ class MasteryNoteExplainedTool(BaseTool):def note(tx):import time+ from deeptutor.learning.lesson_evidence import validate_evidence+if find_knowledge_point(tx.progress, kp_id)[0] is None:raise ValueError("Unknown objective; refresh mastery_status.")+ validate_evidence(+ service.store, tx.progress, kp_id, tx.progress.lesson_evidence.get(kp_id, {}),+ allow_partial=True,+ )tx.progress.explained_objectives[kp_id] = {"summary": summary,+ "coverage": "partial","timestamp": time.time(),"session_id": _resolve_session_id(kwargs),"turn_id": _resolve_turn_id(kwargs),}- tx.emit("objective.explained", {"knowledge_point_id": kp_id, "summary": summary})+ tx.emit("objective.explained", {"knowledge_point_id": kp_id, "summary": summary, "coverage": "partial"})try:await asyncio.to_thread(service.store.mutate, path_id, note)except (ValueError, FileNotFoundError) as exc:return ToolResult(content=str(exc), success=False)return _json_result(- {"knowledge_point_id": kp_id, "stage": "explained", "mastery_credit": False},+ {"knowledge_point_id": kp_id, "stage": "explained", "coverage": "partial", "mastery_credit": False},meta_key="mastery_note_explained",)diff --git a/deeptutor/services/session/model_history.py b/deeptutor/services/session/model_history.pyindex fe9b4ada2..121ace2c4 100644--- a/deeptutor/services/session/model_history.py+++ b/deeptutor/services/session/model_history.py@@ -24,6 +24,7 @@ _MESSAGE_KEYS = frozenset("thinking_blocks","_provider_response_state","_context_snapshot",+ "_lesson_packet",})diff --git a/tests/agents/chat/test_mastery_source_request_boundary.py b/tests/agents/chat/test_mastery_source_request_boundary.pynew file mode 100644index 000000000..9b82703fe--- /dev/null+++ b/tests/agents/chat/test_mastery_source_request_boundary.py@@ -0,0 +1,98 @@+"""Source preparation must actually run at the native model-request boundary."""+import json++import pytest++from deeptutor.agents.chat.agentic_pipeline import AgenticChatPipeline+from deeptutor.agents.loop import agent_loop as loop_module+from deeptutor.core.context import UnifiedContext+from deeptutor.learning.lesson_evidence import LessonUnavailable+from deeptutor.services.session.model_history import normalize_model_turn+from tests.agents.chat.test_agent_loop import _isolated_runtime as _isolated_runtime+from tests.agents.chat.test_agent_loop import _llm_chunk, _Registry, _run, _ScriptedChatClient+++def pixels(label):+ return {"role": "user", "content": [+ {"type": "image_url", "image_url": {"url": "data:image/png;base64," + label}}+ ]}++[email protected]("forced_finish", [False, True])+async def test_native_boundary_refreshes_each_round_and_keeps_tool_pixels_ephemeral(monkeypatch, forced_finish):+ class Registry(_Registry):+ async def execute(self, name, **kwargs):+ result = await super().execute(name, **kwargs)+ result.model_message = pixels("fresh-tool-image")+ return result++ client = _ScriptedChatClient([+ [_llm_chunk(tool_calls=[{"id": "inspect", "name": "web_search", "arguments": '{"query":"figure"}'}])],+ [_llm_chunk(content="A supported explanation.")],+ ])+ pipeline = AgenticChatPipeline(language="en")+ pipeline.registry = Registry()+ monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _: ["web_search"])+ monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)+ if forced_finish:+ pipeline._max_rounds = 1+ monkeypatch.setattr(loop_module, "MAX_SETTLEMENT_ROUNDS", 0)+ checks = []++ async def prepare(context, stream, messages):+ checks.append(True)+ messages[:] = [m for m in messages if not m.get("_lesson_packet")]+ messages.append({"role": "user", "content": "current authorized source packet", "_lesson_packet": True})+ return [pixels("cached-page-image")]++ monkeypatch.setattr(pipeline, "prepare_model_request", prepare, raising=False)+ context = UnifiedContext(session_id="synthetic-source", user_message="Inspect the figure")+ await _run(pipeline, context)+ assert len(checks) == client.call_count == 2+ assert "cached-page-image" in json.dumps(client.calls[0]["messages"])+ assert "fresh-tool-image" in json.dumps(client.calls[1]["messages"])+ assert "cached-page-image" not in json.dumps(client.calls[1]["messages"])+ assert all("_lesson_packet" not in m for call in client.calls for m in call["messages"])+ assert "base64" not in json.dumps(context.runtime.model_turn)+ messages = client.calls[1]["messages"]+ call_index = next(i for i, m in enumerate(messages) if m.get("tool_calls"))+ assert messages[call_index + 1]["tool_call_id"] == "inspect"+ assert ("tools" not in client.calls[1]) is forced_finish++[email protected]("forced_finish", [False, True])+async def test_source_check_failure_cannot_be_bypassed_by_finishing(monkeypatch, forced_finish):+ client = _ScriptedChatClient([+ [_llm_chunk(tool_calls=[{"id": "change", "name": "web_search", "arguments": '{"query":"change"}'}])],+ [_llm_chunk(content="Must not run.")],+ ])+ pipeline = AgenticChatPipeline(language="en")+ pipeline.registry = _Registry()+ monkeypatch.setattr(pipeline, "_compose_enabled_tools", lambda _: ["web_search"])+ monkeypatch.setattr(pipeline, "_build_openai_client", lambda: client)+ if forced_finish:+ pipeline._max_rounds = 1+ monkeypatch.setattr(loop_module, "MAX_SETTLEMENT_ROUNDS", 0)+ checks = []++ async def prepare(context, stream, messages):+ checks.append(True)+ if len(checks) > 1:+ raise LessonUnavailable("Selected source access changed")+ return []++ monkeypatch.setattr(pipeline, "prepare_model_request", prepare, raising=False)+ with pytest.raises(LessonUnavailable):+ await _run(pipeline, UnifiedContext(user_message="Teach"))+ assert client.call_count == 1+++def test_durable_packet_marker_survives_normalization_for_later_refresh():+ record = normalize_model_turn({"version": 1, "messages": [+ {"role": "user", "content": "Teach"},+ {"role": "user", "content": "old source packet", "_lesson_packet": True},+ {"role": "assistant", "content": "Explanation"},+ ]})+ assert record["messages"][1]["_lesson_packet"] is Truediff --git a/tests/capabilities/test_mastery_demand_preparation.py b/tests/capabilities/test_mastery_demand_preparation.pynew file mode 100644index 000000000..4f61d6b98--- /dev/null+++ b/tests/capabilities/test_mastery_demand_preparation.py@@ -0,0 +1,221 @@+"""Preparation is demand-driven; cache misses are not missing subject matter."""++from types import SimpleNamespace+from unittest.mock import AsyncMock, Mock++import pytest++from deeptutor.capabilities.mastery.pipeline import MasteryLoopPipeline+from deeptutor.core.context import UnifiedContext+from deeptutor.learning import lesson_evidence, policy, storage+++def preparation(monkeypatch):+ progress = SimpleNamespace(book_id="path", modules=[object()], lesson_evidence={})+ store = SimpleNamespace(load=Mock(return_value=progress), get_topic=Mock(return_value=object()))+ monkeypatch.setattr(storage, "LearningStore", lambda: store)+ monkeypatch.setattr(policy, "next_objective", lambda _: SimpleNamespace(knowledge_point_id="next"))+ monkeypatch.setattr(lesson_evidence, "objective_fingerprint", lambda *args: "current")+ scope = Mock(return_value={"selected": ["lesson.pdf"]})+ cache = Mock(return_value=None)+ paid = AsyncMock(side_effect=lesson_evidence.LessonUnavailable("Coverage incomplete"))+ monkeypatch.setattr(lesson_evidence, "selected_scope", scope)+ monkeypatch.setattr(lesson_evidence, "cached_lesson", cache)+ monkeypatch.setattr(lesson_evidence, "prepare_lesson", paid)+ stream = SimpleNamespace(sources=AsyncMock())+ pipeline = MasteryLoopPipeline(language="en")+ return SimpleNamespace(progress=progress, store=store, scope=scope, cache=cache,+ paid=paid, stream=stream, pipeline=pipeline)++[email protected]("learner_message", [+ "Why did the outline order not change?",+ "Miért nem rendezted át a vázlatot?",+ "Continue the next lesson",+])+async def test_cache_miss_never_starts_automatic_paid_preparation(preparation, learner_message):+ context = UnifiedContext(user_message=learner_message, metadata={"mastery_path_id": "path"})+ messages = [{"role": "user", "content": learner_message},+ {"role": "tool", "content": "Earlier assessment already saved"}]+ for _ in range(3):+ assert await preparation.pipeline.prepare_model_request(context, preparation.stream, messages) == []+ preparation.paid.assert_not_awaited()+ assert messages[0]["content"] == learner_message+ assert messages[1]["content"] == "Earlier assessment already saved"+ packets = [m for m in messages if m.get("_lesson_packet")]+ assert len(packets) == 1+ assert "mastery_prepare_lesson" in packets[0]["content"]+ assert "not prepared" in packets[0]["content"]+ assert "NOT conversation" in packets[0]["content"]+ assert "unavailable" not in packets[0]["content"]+++async def test_valid_packet_is_reused_without_new_preparation(preparation, monkeypatch):+ evidence = {"id": "verified", "sources": [{"ref": "one"}, {"ref": "two"}, {"ref": "three"}]}+ preparation.cache.return_value = evidence+ pixels = Mock(return_value={"role": "user", "content": "verified pixels"})+ monkeypatch.setattr(lesson_evidence, "image_message", pixels)+ monkeypatch.setattr(lesson_evidence, "lesson_context", lambda _: "VERIFIED ACTIVE LESSON")+ monkeypatch.setattr(lesson_evidence, "public_sources", lambda _: [])+ context = UnifiedContext(metadata={"mastery_path_id": "path"})+ messages = []+ for _ in range(2):+ assert await preparation.pipeline.prepare_model_request(context, preparation.stream, messages)+ preparation.paid.assert_not_awaited()+ assert pixels.call_count == 1+ assert pixels.call_args.args == (evidence["sources"][:2],)+ preparation.stream.sources.assert_awaited_once()+ assert len(messages) == 1 and messages[0]["content"] == "VERIFIED ACTIVE LESSON"+++async def test_stale_packet_offers_authorized_refresh_without_automatic_paid_work(preparation):+ preparation.cache.side_effect = lesson_evidence.LessonUnavailable("Selected sources changed")+ context = UnifiedContext(user_message="Continue the lesson", metadata={"mastery_path_id": "path"})+ messages = []+ assert await preparation.pipeline.prepare_model_request(context, preparation.stream, messages) == []+ notice = messages[0]["content"]+ assert "mastery_prepare_lesson" in notice and '"knowledge_point_id": "next"' in notice+ assert "access denial" in notice and "unchanged" in notice+ preparation.paid.assert_not_awaited()+++async def test_cache_is_checked_again_after_state_changes(preparation, monkeypatch):+ preparation.cache.side_effect = [{"id": "first", "sources": []}, None]+ monkeypatch.setattr(lesson_evidence, "image_message", lambda _: {"content": "old pixels"})+ monkeypatch.setattr(lesson_evidence, "lesson_context", lambda _: "OLD VERIFIED PACKET")+ monkeypatch.setattr(lesson_evidence, "public_sources", lambda _: [])+ context = UnifiedContext(metadata={"mastery_path_id": "path"})+ messages = []+ assert await preparation.pipeline.prepare_model_request(context, preparation.stream, messages)+ assert await preparation.pipeline.prepare_model_request(context, preparation.stream, messages) == []+ assert preparation.pipeline._lesson_pixels is None+ assert "OLD VERIFIED PACKET" not in str(messages)+ assert "not prepared" in messages[-1]["content"]+ preparation.paid.assert_not_awaited()+++async def test_text_only_route_does_not_acquire_a_pdf_gate(preparation):+ preparation.scope.return_value = {}+ context = UnifiedContext(metadata={"mastery_path_id": "path"})+ messages = [{"role": "user", "content": "Explain a text-only subject"}]+ preparation.pipeline._lesson_pixels = ("previous", {"content": "old PDF"})+ assert await preparation.pipeline.prepare_model_request(context, preparation.stream, messages) == []+ assert len(messages) == 1+ assert preparation.pipeline._lesson_pixels is None+ preparation.paid.assert_not_awaited()+++async def test_removed_pdf_scope_is_not_a_text_only_fallback(preparation):+ preparation.scope.return_value = {}+ preparation.progress.lesson_evidence = {"next": {"id": "previous-source"}}+ context = UnifiedContext(metadata={"mastery_path_id": "path"})+ messages = []+ assert await preparation.pipeline.prepare_model_request(context, preparation.stream, messages) == []+ assert "materials have changed" in messages[-1]["content"]+ preparation.paid.assert_not_awaited()+++async def test_access_failure_is_reported_without_paid_recovery(preparation):+ preparation.scope.side_effect = lesson_evidence.LessonUnavailable("Selected material access denied")+ context = UnifiedContext(user_message="Explain the outline change", metadata={"mastery_path_id": "path"})+ messages = [{"role": "user", "content": context.user_message}]+ assert await preparation.pipeline.prepare_model_request(context, preparation.stream, messages) == []+ assert "Selected material access denied" in messages[-1]["content"]+ assert "NOT conversation" in messages[-1]["content"]+ assert messages[0]["content"] == context.user_message+ preparation.paid.assert_not_awaited()+++async def test_outline_mode_does_not_load_or_prepare_lesson(preparation):+ context = UnifiedContext(metadata={"mastery_path_id": "path", "mastery_session_mode": "outline"})+ assert await preparation.pipeline.prepare_model_request(context, preparation.stream, []) == []+ preparation.store.load.assert_not_called()+ preparation.paid.assert_not_awaited()+++async def test_prepare_tool_passes_focused_task_and_runtime_request(monkeypatch):+ from deeptutor.capabilities.mastery import tools+ from deeptutor.services.llm import config++ evidence = {"id": "packet", "coverage": {"complete": False, "missing": "One detail"}}+ prepare = AsyncMock(return_value=evidence)+ monkeypatch.setattr(tools, "_new_service", lambda: SimpleNamespace(store="store"))+ monkeypatch.setattr(lesson_evidence, "prepare_lesson", prepare)+ monkeypatch.setattr(lesson_evidence, "lesson_context", lambda _: "Teach the supported part")+ monkeypatch.setattr(lesson_evidence, "public_sources", lambda _: [])+ monkeypatch.setattr(config, "get_llm_config", lambda: "config")+ result = await tools.MasteryPrepareLessonTool().execute(+ _mastery_path_id="path", knowledge_point_id="objective",+ focus="Original practice questions about the taught comparison",+ _learner_message="Use the actual question bank, then a similar problem.",+ refresh=True,+ )+ assert result.success+ assert prepare.call_args.kwargs["focus"] == "Original practice questions about the taught comparison"+ assert prepare.call_args.kwargs["learner_request"] == "Use the actual question bank, then a similar problem."+ assert prepare.call_args.kwargs["refresh"] is True+++async def test_partial_packet_is_delivered_without_automatic_retry(preparation, monkeypatch):+ evidence = {"id": "partial", "sources": [],+ "coverage": {"complete": False, "missing": "One unverified detail"}}+ preparation.cache.return_value = evidence+ monkeypatch.setattr(lesson_evidence, "image_message", lambda _: {"content": "pixels"})+ monkeypatch.setattr(lesson_evidence, "public_sources", lambda _: [])+ context = UnifiedContext(user_message="Please continue", metadata={"mastery_path_id": "path"})+ messages = []+ await preparation.pipeline.prepare_model_request(context, preparation.stream, messages)+ assert "partial" in messages[-1]["content"].lower()+ assert "One unverified detail" in messages[-1]["content"]+ preparation.paid.assert_not_awaited()+++async def test_explicit_focus_is_runtime_bound_and_expires_when_policy_advances(preparation, monkeypatch):+ from deeptutor.capabilities.mastery.loop import MasteryLoopCapability++ context = UnifiedContext(user_message="Explain the earlier objective", metadata={+ "mastery_mode": True, "mastery_path_id": "path",+ })+ forged = Mock()+ bound = MasteryLoopCapability().augment_kwargs(+ "mastery_prepare_lesson", {"_bind_lesson_objective": forged}, context)+ bound["_bind_lesson_objective"]("reviewed")+ assert context.metadata["mastery_lesson_objective"] == {+ "path_id": "path", "kp_id": "reviewed", "policy_id": "next",+ }+ messages = []+ await preparation.pipeline.prepare_model_request(context, preparation.stream, messages)+ assert preparation.cache.call_args.args[2] == "reviewed"+ monkeypatch.setattr(policy, "next_objective", lambda _: SimpleNamespace(knowledge_point_id="advanced"))+ await preparation.pipeline.prepare_model_request(context, preparation.stream, messages)+ assert preparation.cache.call_args.args[2] == "advanced"+ forged.assert_not_called()+ preparation.paid.assert_not_awaited()+++async def test_historical_packet_refresh_preserves_archive_boundary_and_literal_user_text(preparation):+ context = UnifiedContext(metadata={"mastery_path_id": "path"})+ messages = [+ {"role": "user", "content": "old learner question"},+ {"role": "user", "content": "old packet", "_lesson_packet": True},+ {"role": "assistant", "content": "old explanation"},+ {"role": "user", "content": "I literally wrote old packet in my question"},+ ]+ preparation.pipeline._model_turn_start = 3+ await preparation.pipeline.prepare_model_request(context, preparation.stream, messages)+ assert preparation.pipeline._model_turn_start == 2+ assert messages[2]["content"] == "I literally wrote old packet in my question"+ assert len([m for m in messages if m.get("_lesson_packet")]) == 1diff --git a/tests/services/rag/test_mastery_source_pages.py b/tests/services/rag/test_mastery_source_pages.pyindex 4cc39bf79..09c4d2e7c 100644--- a/tests/services/rag/test_mastery_source_pages.py+++ b/tests/services/rag/test_mastery_source_pages.py@@ -32,6 +32,51 @@ from deeptutor.services.rag.source_pages import ()+async def test_successful_explicit_preparation_supersedes_same_turn_failure(material, monkeypatch):+ from unittest.mock import AsyncMock++ from deeptutor.capabilities.mastery.pipeline import MasteryLoopPipeline+ from deeptutor.capabilities.mastery.tools import MasteryPrepareLessonTool+ from deeptutor.core.context import UnifiedContext+ from deeptutor.runtime.stream_bus import StreamBus++ _install_preparation(material, monkeypatch)+ actual_prepare = lessons.prepare_lesson+ automatic = AsyncMock(side_effect=lessons.LessonUnavailable("Initial coverage incomplete"))+ monkeypatch.setattr(lessons, "prepare_lesson", automatic)+ monkeypatch.setattr("deeptutor.learning.storage.LearningStore", lambda: material.store)+ monkeypatch.setattr("deeptutor.capabilities.mastery.tools._new_service", lambda: LearningService(material.store))+ monkeypatch.setattr("deeptutor.services.llm.config.get_llm_config", lambda: material.config)+ pipeline = MasteryLoopPipeline(language="en")+ pipeline.llm_config = material.config+ context = UnifiedContext(user_message="Continue teaching", metadata={"mastery_path_id": "path"})+ messages = [{"role": "user", "content": context.user_message}]+ stream = StreamBus()+ assert await pipeline.prepare_model_request(context, stream, messages) == []+ assert "not prepared" in messages[-1]["content"]+ automatic.assert_not_awaited()+ before = material.store.load("path").model_dump()+ with pytest.raises(MasteryInteractionError):+ LearningService(material.store).register_question("path", PendingQuestion(+ question_id="unsupported", knowledge_point_id="kp", expected_answer="lipids"))+ assert material.store.load("path").model_dump() == before+ failed = await MasteryPrepareLessonTool().execute(+ knowledge_point_id="kp", _mastery_path_id="path")+ assert not failed.success and "Initial coverage incomplete" in failed.content+ assert await pipeline.prepare_model_request(context, stream, messages) == []+ assert automatic.await_count == 1 # The explicit tool attempt, not the hook.+ monkeypatch.setattr(lessons, "prepare_lesson", actual_prepare)+ prepared = await MasteryPrepareLessonTool().execute(+ knowledge_point_id="kp", _mastery_path_id="path")+ assert prepared.success and "VERIFIED ACTIVE LESSON" in prepared.content+ assert await pipeline.prepare_model_request(context, stream, messages)+ assert automatic.await_count == 1+ assert len([m for m in messages if m.get("_lesson_packet")]) == 1+ assert "VERIFIED ACTIVE LESSON" in messages[-1]["content"]+ assert not material.store.load("path").mastery_levels++@pytest.fixturedef material(tmp_path, monkeypatch):raw = tmp_path / "kb" / "raw"@@ -73,6 +118,37 @@ def material(tmp_path, monkeypatch):config=SimpleNamespace(model="vision-test", binding="openai"))+def test_source_guard_rejects_recording_unprepared_teaching(material, monkeypatch):+ from deeptutor.capabilities.mastery import tools++ monkeypatch.setattr(tools, "_new_service", lambda: LearningService(material.store))+ before = material.store.load("path").model_dump()+ result = asyncio.run(tools.MasteryNoteExplainedTool().execute(+ _mastery_path_id="path", knowledge_point_id="kp", summary="A proposed explanation"))+ assert not result.success+ assert material.store.load("path").model_dump() == before+++def test_source_guard_records_only_partial_coverage_and_rechecks_access(material, monkeypatch):+ from deeptutor.capabilities.mastery import tools++ _install_preparation(material, monkeypatch, rankings=[_partial_selection()])+ asyncio.run(lessons.prepare_lesson(material.store, "path", "kp", material.config))+ monkeypatch.setattr(tools, "_new_service", lambda: LearningService(material.store))+ result = asyncio.run(tools.MasteryNoteExplainedTool().execute(+ _mastery_path_id="path", knowledge_point_id="kp", summary="Only the supported bilayer slice"))+ assert result.success, result.content+ progress = material.store.load("path")+ assert progress.explained_objectives["kp"]["coverage"] == "partial"+ assert not progress.mastery_levels and not progress.quiz_attempts and not progress.learning_evidence+ before = progress.model_dump()+ monkeypatch.setattr("deeptutor.multi_user.knowledge_access.resolve_for_rag", lambda _: None)+ denied = asyncio.run(tools.MasteryNoteExplainedTool().execute(+ _mastery_path_id="path", knowledge_point_id="kp", summary="An unsupported later claim"))+ assert not denied.success+ assert material.store.load("path").model_dump() == before++def test_physical_pages_beyond_64_and_unlocated_text_preserved(material):pages = [d for d in material.documents if "page_index" in d.metadata]assert len(pages) == 72