Skip to content

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

Merge PR #1954: prepare source evidence through a generic capability prerequisite contract

Bingxi Zhao (Frank)3196b6d792cb
diff --cc deeptutor/agents/loop/agent_loop.py
index 99b33a9f4,ade408911..b951818c4
--- a/deeptutor/agents/loop/agent_loop.py
+++ b/deeptutor/agents/loop/agent_loop.py
@@@ -475,6 -450,10 +475,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
++ 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.
raise
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
# 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.stage
call_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_id
trace_meta = build_trace_metadata(
call_id=call_id,
phase=stage,
diff --cc deeptutor/capabilities/mastery/loop.py
index 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_lesson
if 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.py
index 1babecff1,c3d2070f9..65421dfce
--- a/deeptutor/capabilities/mastery/pipeline.py
+++ b/deeptutor/capabilities/mastery/pipeline.py
@@@ -69,6 -69,143 +69,168 @@@ class MasteryLoopPipeline(AgenticLoopPi
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)
++ 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.py
index 3ad8b7dd8,1dbdf003f..636b2c84d
--- a/deeptutor/capabilities/mastery/tools.py
+++ b/deeptutor/capabilities/mastery/tools.py
@@@ -870,7 -846,7 +870,7 @@@ class MasteryNoteExplainedTool(BaseTool
def 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.py
index 43c515f27,43c515f27..cf15d45e1
--- a/deeptutor/core/capability_protocol.py
+++ b/deeptutor/core/capability_protocol.py
@@@ -18,6 -18,6 +18,10 @@@ from .context import UnifiedContex
from .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.py
index b371d23d0,963d06bb8..62682e0a4
--- a/deeptutor/learning/lesson_evidence.py
+++ b/deeptutor/learning/lesson_evidence.py
@@@ -16,6 -15,6 +16,7 @@@ from pathlib import Pat
import time
from typing import Any
++from deeptutor.core.capability_protocol import CapabilityPrerequisiteError
from deeptutor.learning.policy import find_knowledge_point
from 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.py
index 000000000,9b82703fe..b3defcd9c
mode 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 True
diff --cc tests/capabilities/test_mastery_demand_preparation.py
index 000000000,4f61d6b98..d3d03af19
mode 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")]) == 1
diff --cc tests/services/rag/test_mastery_source_pages.py
index 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.fixture
def 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