DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
Merge PR #1954: prepare source evidence through a generic capability prerequisite contract
Bingxi Zhao (Frank)3196b6d792cb
diff --cc deeptutor/agents/loop/agent_loop.pyindex 99b33a9f4,ade408911..b951818c4--- a/deeptutor/agents/loop/agent_loop.py+++ b/deeptutor/agents/loop/agent_loop.py@@@ -475,6 -450,10 +475,10 @@@ class AgentLooptool_choice=(self.pipeline.initial_tool_choice if state.rounds == 0 else None),)except Exception as exc:- from deeptutor.learning.lesson_evidence import LessonUnavailable++ from deeptutor.core.capability_protocol import CapabilityPrerequisiteError+- if isinstance(exc, LessonUnavailable):++ if isinstance(exc, CapabilityPrerequisiteError):+ 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@@@ -920,6 -890,10 +924,10 @@@# prevents callers from offering an accurate retry action.raiseexcept Exception as exc:- from deeptutor.learning.lesson_evidence import LessonUnavailable++ from deeptutor.core.capability_protocol import CapabilityPrerequisiteError+- if isinstance(exc, LessonUnavailable):++ if isinstance(exc, CapabilityPrerequisiteError):+ 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.@@@ -1080,23 -1054,21 +1088,31 @@@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)- # Guard the same request representation we send. Raw repeated images- # must not cause tool evidence to be snipped before image projection.+ # 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)+ projected_messages = deduplicate_user_images(+ [- {key: value for key, value in message.items() if key != "_context_snapshot"}++ {++ 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, tool_schemas=tool_schemas+ )stage = self.stagecall_id = new_call_id(f"{self.source}-{stage}")+ # Runtime-only invocation identity: reviewed mutations can require a+ # subsequent model call, rather than trust an LLM-supplied argument.+ self.context.extension("agent_loop")["model_call_id"] = call_idtrace_meta = build_trace_metadata(call_id=call_id,phase=stage,diff --cc deeptutor/capabilities/mastery/loop.pyindex 496f1516d,ef0961eae..cd11f7fce--- a/deeptutor/capabilities/mastery/loop.py+++ b/deeptutor/capabilities/mastery/loop.py@@@ -359,6 -309,18 +359,21 @@@ 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 "",++ "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 --cc deeptutor/capabilities/mastery/pipeline.pyindex 1babecff1,c3d2070f9..65421dfce--- a/deeptutor/capabilities/mastery/pipeline.py+++ b/deeptutor/capabilities/mastery/pipeline.py@@@ -69,6 -69,143 +69,168 @@@ class MasteryLoopPipeline(AgenticLoopPiprompt_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)++ 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)++ 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)- )})++ 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)- )})++ 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]))++ 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")++ 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 --cc deeptutor/capabilities/mastery/tools.pyindex 3ad8b7dd8,1dbdf003f..636b2c84d--- a/deeptutor/capabilities/mastery/tools.py+++ b/deeptutor/capabilities/mastery/tools.py@@@ -870,7 -846,7 +870,7 @@@ class MasteryNoteExplainedTool(BaseTooldef get_definition(self) -> ToolDefinition:return ToolDefinition(name="mastery_note_explained",- description="After publicly explaining part of an objective, record that delivered explanation with an exact quote. Never record a planned explanation or treat this as complete-objective coverage, assessment or mastery. 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.",++ description="After publicly explaining a source-supported slice of an objective, record that delivered explanation with an exact quote. Current source evidence is revalidated. Never record a planned explanation or treat this as complete-objective coverage, assessment or mastery. A quiz is optional until the learner wants practice.",parameters=[ToolParameter(name="knowledge_point_id",@@@ -963,12 -879,16 +963,21 @@@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, {}),++ service.store,++ tx.progress,++ kp_id,++ tx.progress.lesson_evidence.get(kp_id, {}),+ allow_partial=True,+ )tx.progress.explained_objectives[kp_id] = {"summary": summary,+ "explanation_quote": quote,+ "delivery": provenance,"coverage": "partial","timestamp": time.time(),"session_id": _resolve_session_id(kwargs),diff --cc deeptutor/core/capability_protocol.pyindex 43c515f27,43c515f27..cf15d45e1--- a/deeptutor/core/capability_protocol.py+++ b/deeptutor/core/capability_protocol.py@@@ -18,6 -18,6 +18,10 @@@ from .context import UnifiedContexfrom .stream import StreamEvent++class CapabilityPrerequisiteError(ValueError):++ """A required capability precondition failed; never bypass it by forced finish."""++++class StreamBusProtocol(Protocol):"""Minimal output port required by a turn capability."""@@@ -91,6 -91,6 +95,7 @@@ def __getattr__(name: str)__all__ = [++ "CapabilityPrerequisiteError","CapabilityManifest","StreamBusProtocol","TurnCapability",diff --cc deeptutor/learning/lesson_evidence.pyindex b371d23d0,963d06bb8..62682e0a4--- a/deeptutor/learning/lesson_evidence.py+++ b/deeptutor/learning/lesson_evidence.py@@@ -16,6 -15,6 +16,7 @@@ from pathlib import Patimport timefrom typing import Any++from deeptutor.core.capability_protocol import CapabilityPrerequisiteErrorfrom deeptutor.learning.policy import find_knowledge_pointfrom deeptutor.services.rag.source_pages import (CATALOG_FILENAME,@@@ -32,7 -31,7 +33,7 @@@ PREPARATION_VERSION =MAX_LESSON_PAGES = 6--class LessonUnavailable(ValueError):++class LessonUnavailable(CapabilityPrerequisiteError):"""Stop source-grounded tutoring, rather than silently fall back to guesses."""diff --cc tests/agents/chat/test_mastery_source_request_boundary.pyindex 000000000,9b82703fe..b3defcd9cmode 000000,100644..100644--- a/tests/agents/chat/test_mastery_source_request_boundary.py+++ b/tests/agents/chat/test_mastery_source_request_boundary.py@@@ -1,0 -1,98 +1,129 @@@+ """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.capability_protocol import CapabilityPrerequisiteError+ 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}}- ]}++ return {++ "role": "user",++ "content": [{"type": "image_url", "image_url": {"url": "data:image/png;base64," + label}}],++ }+++ @pytest.mark.asyncio+ @pytest.mark.parametrize("forced_finish", [False, True])-async def test_native_boundary_refreshes_each_round_and_keeps_tool_pixels_ephemeral(monkeypatch, forced_finish):++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.")],- ])++ 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})++ 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+++ @pytest.mark.asyncio+ @pytest.mark.parametrize("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.")],- ])[email protected]("error_type", [LessonUnavailable, CapabilityPrerequisiteError])++async def test_source_check_failure_cannot_be_bypassed_by_finishing(++ monkeypatch, forced_finish, error_type++):++ 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")++ raise error_type("Selected source access changed")+ return []++ monkeypatch.setattr(pipeline, "prepare_model_request", prepare, raising=False)- with pytest.raises(LessonUnavailable):++ with pytest.raises(error_type):+ 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"},- ]})++ 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 --cc tests/capabilities/test_mastery_demand_preparation.pyindex 000000000,4f61d6b98..d3d03af19mode 000000,100644..100644--- a/tests/capabilities/test_mastery_demand_preparation.py+++ b/tests/capabilities/test_mastery_demand_preparation.py@@@ -1,0 -1,221 +1,286 @@@+ """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+++ @pytest.fixture+ 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(++ 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)++ return SimpleNamespace(++ progress=progress,++ store=store,++ scope=scope,++ cache=cache,++ paid=paid,++ stream=stream,++ pipeline=pipeline,++ )+++ @pytest.mark.asyncio[email protected]("learner_message", [- "Why did the outline order not change?",- "Miért nem rendezted át a vázlatot?",- "Continue the next lesson",-])++ "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"}]++ 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) == []++ 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"]+++ @pytest.mark.asyncio+ 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)++ 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"+++ @pytest.mark.asyncio+ 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"})++ context = UnifiedContext(++ user_message="Continue the lesson", 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)++ == []++ )+ 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()+++ @pytest.mark.asyncio+ 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 (++ 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()+++ @pytest.mark.asyncio+ 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 (++ 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()+++ @pytest.mark.asyncio+ 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 (++ await preparation.pipeline.prepare_model_request(context, preparation.stream, messages)++ == []++ )+ assert "materials have changed" in messages[-1]["content"]+ preparation.paid.assert_not_awaited()+++ @pytest.mark.asyncio+ 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"})++ 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 (++ 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()+++ @pytest.mark.asyncio+ async def test_outline_mode_does_not_load_or_prepare_lesson(preparation):- context = UnifiedContext(metadata={"mastery_path_id": "path", "mastery_session_mode": "outline"})++ 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()+++ @pytest.mark.asyncio+ 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",++ _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["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+++ @pytest.mark.asyncio+ async def test_partial_packet_is_delivered_without_automatic_retry(preparation, monkeypatch):- evidence = {"id": "partial", "sources": [],- "coverage": {"complete": False, "missing": "One unverified detail"}}++ 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()+++ @pytest.mark.asyncio-async def test_explicit_focus_is_runtime_bound_and_expires_when_policy_advances(preparation, monkeypatch):++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",- })++ 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)++ "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",++ "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"))++ 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()+++ @pytest.mark.asyncio-async def test_historical_packet_refresh_preserves_archive_boundary_and_literal_user_text(preparation):++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 --cc tests/services/rag/test_mastery_source_pages.pyindex 86d91558f,09c4d2e7c..fd2b7a8a2--- a/tests/services/rag/test_mastery_source_pages.py+++ b/tests/services/rag/test_mastery_source_pages.py@@@ -33,6 -32,51 +33,59 @@@ from deeptutor.services.rag.source_page)+ @pytest.mark.asyncio+ 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.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"))++ 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")++ 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")++ 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"@@@ -63,77 -99,56 +116,143 @@@def resolve(kb, key):target = (raw / key).resolve()- return target if kb == "selected" and target.is_relative_to(raw.resolve()) and target.is_file() else None+ return (+ target+ if kb == "selected" and target.is_relative_to(raw.resolve()) and target.is_file()+ else None+ )monkeypatch.setattr("deeptutor.multi_user.knowledge_access.resolve_kb_document_path", resolve)- monkeypatch.setattr("deeptutor.multi_user.knowledge_access.resolve_for_rag",- lambda kb: SimpleNamespace(base_dir=raw.parent.parent, name="kb") if kb == "selected" else None)- monkeypatch.setattr("deeptutor.services.rag.embedding_signature.signature_from_embedding_config", lambda: None)- monkeypatch.setattr("deeptutor.services.rag.index_versioning.resolve_storage_dir_for_read", lambda *args: storage)+ monkeypatch.setattr(+ "deeptutor.multi_user.knowledge_access.resolve_for_rag",+ lambda kb: (+ SimpleNamespace(base_dir=raw.parent.parent, name="kb") if kb == "selected" else None+ ),+ )+ monkeypatch.setattr(+ "deeptutor.services.rag.embedding_signature.signature_from_embedding_config", lambda: None+ )+ monkeypatch.setattr(+ "deeptutor.services.rag.index_versioning.resolve_storage_dir_for_read",+ lambda *args: storage,+ )monkeypatch.setattr("deeptutor.services.llm.capabilities.supports_vision", lambda *args: True)store = LearningStore(tmp_path / "learning")- progress = LearningProgress(book_id="path", modules=[LearningModule(id="m", name="Cells", order=0,- knowledge_points=[KnowledgePoint(id="kp", name="Sejthártya szerkezete", type="memory", module_id="m", topic_source_ids=["s"])])])+ progress = LearningProgress(+ book_id="path",+ modules=[+ LearningModule(+ id="m",+ name="Cells",+ order=0,+ knowledge_points=[+ KnowledgePoint(+ id="kp",+ name="Sejthártya szerkezete",+ type="memory",+ module_id="m",+ topic_source_ids=["s"],+ )+ ],+ )+ ],+ )store.save(progress)- store.put_topic(TopicMetadata(path_id="path"), [TopicSource(id="s", kind=TopicSourceKind.FILE,- label="Lesson", source_id="lesson.pdf", metadata={"kb_name": "selected", "path": "lesson.pdf"})])- ref = SourceRef(kb_ref="selected", document_key="lesson.pdf", source_digest=source_digest(path), page_index=70)- return SimpleNamespace(path=path, raw=raw, documents=documents, storage=storage, store=store, ref=ref,- config=SimpleNamespace(model="vision-test", binding="openai"))+ store.put_topic(+ TopicMetadata(path_id="path"),+ [+ TopicSource(+ id="s",+ kind=TopicSourceKind.FILE,+ label="Lesson",+ source_id="lesson.pdf",+ metadata={"kb_name": "selected", "path": "lesson.pdf"},+ )+ ],+ )+ ref = SourceRef(+ kb_ref="selected",+ document_key="lesson.pdf",+ source_digest=source_digest(path),+ page_index=70,+ )+ return SimpleNamespace(+ path=path,+ raw=raw,+ documents=documents,+ storage=storage,+ store=store,+ ref=ref,+ 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"))++ 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"))++ from deeptutor.runtime.stream_bus import StreamBus++++ explanation = "The membrane's bilayer forms the supported boundary around the cell."++ bus = StreamBus(assign_seq=True)++ asyncio.run(bus.content(explanation, source="mastery_path", stage="responding"))++ teaching = {++ "_session_id": "session",++ "_turn_id": "turn",++ "explanation_quote": explanation,++ "_teaching_delivery": lambda: {++ "path_id": "path",++ "session_id": "session",++ "turn_id": "turn",++ "segments": bus.public_content_snapshot(source="mastery_path", stage="responding"),++ },++ }++ result = asyncio.run(++ tools.MasteryNoteExplainedTool().execute(++ _mastery_path_id="path",++ knowledge_point_id="kp",++ summary="Only the supported bilayer slice",++ **teaching,++ )++ )+ 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++ 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"))++ denied = asyncio.run(++ tools.MasteryNoteExplainedTool().execute(++ _mastery_path_id="path",++ knowledge_point_id="kp",++ summary="An unsupported later claim",++ **teaching,++ )++ )+ 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