Skip to content

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

perf(mastery): project working brief and defer outline schemas

yepyhun36fc20196dd9
diff --git a/deeptutor/capabilities/mastery/loop.py b/deeptutor/capabilities/mastery/loop.py
index 6cda7ed87..a1cd2db77 100644
--- a/deeptutor/capabilities/mastery/loop.py
+++ b/deeptutor/capabilities/mastery/loop.py
@@ -423,6 +423,7 @@ class MasteryLoopCapability:
context.extension("mastery").pop("status_snapshot", None)
if not self.is_active(context) or not context.metadata.get("mastery_path_id"):
return None
+ from deeptutor.capabilities.mastery.mode import normalize_mode
from deeptutor.capabilities.mastery.tools import MasteryStatusTool
binding = (
@@ -430,7 +431,8 @@ class MasteryLoopCapability:
context.metadata.get("mastery_session_mode"),
)
result = await MasteryStatusTool().execute(
- **self.augment_kwargs("mastery_status", {}, context)
+ **self.augment_kwargs("mastery_status", {}, context),
+ _working_brief=normalize_mode(context.metadata.get("mastery_session_mode")) != "outline",
)
if not result.success:
return None
diff --git a/deeptutor/capabilities/mastery/pipeline.py b/deeptutor/capabilities/mastery/pipeline.py
index df5878e40..ac30b2449 100644
--- a/deeptutor/capabilities/mastery/pipeline.py
+++ b/deeptutor/capabilities/mastery/pipeline.py
@@ -76,6 +76,46 @@ class MasteryLoopPipeline(AgenticLoopPipeline):
prompt_base_agent = "agentic_chat"
prompt_assembler_class = MasteryPromptAssembler
+ async def _prepare_deferred_tools(self, context):
+ await super()._prepare_deferred_tools(context)
+ self._deferred_outline_names = set()
+ if normalize_mode(context.metadata.get("mastery_session_mode")) == "outline":
+ return
+ if (context.allowed_builtin_tools is not None
+ and "load_tools" not in context.allowed_builtin_tools):
+ return # A restricted caller must retain eager access to owned tools.
+ from deeptutor.runtime.providers.view import ProviderToolView
+ from deeptutor.runtime.registry.deferred_tools import (
+ DeferredToolLoader,
+ render_deferred_tools_manifest,
+ )
+ from deeptutor.services.mcp import load_loaded_tools
+
+ view = self._tool_view
+ names = {"mastery_build", "mastery_revise", "mastery_revise_batch"}
+ owned = set(self._capability_owned_tools(context))
+ local = [view.registry.get(name) for name in sorted(names & owned)]
+ local = [tool for tool in local if tool is not None]
+ if not local:
+ return
+ self._deferred_outline_names = {tool.name for tool in local}
+ pool = (*view.pool, *local)
+ loaded = load_loaded_tools(context.session_id)
+ if view.loader:
+ loaded |= view.loader.loaded_names
+ loader = DeferredToolLoader(registry=view.registry, session_id=context.session_id,
+ loaded=loaded, allowed={tool.name for tool in pool},
+ capability_names=self._deferred_outline_names)
+ self._tool_view = ProviderToolView(registry=view.registry, loader=loader, pool=pool,
+ manifest="\n\n".join(filter(None, [view.manifest,
+ render_deferred_tools_manifest(local, language=self.language)])))
+ self._deferred_loader = loader
+ self._deferred_pool = list(pool)
+
+ def _compose_enabled_tools(self, context):
+ deferred = getattr(self, "_deferred_outline_names", set())
+ return [name for name in super()._compose_enabled_tools(context) if name not in deferred]
+
async def _capability_pre_loop_briefings(self, context, stream):
briefing = await super()._capability_pre_loop_briefings(context, stream)
snapshot = context.extension("mastery").get("status_snapshot")
diff --git a/deeptutor/capabilities/mastery/tools.py b/deeptutor/capabilities/mastery/tools.py
index d988ccaf0..70c613034 100644
--- a/deeptutor/capabilities/mastery/tools.py
+++ b/deeptutor/capabilities/mastery/tools.py
@@ -704,6 +704,45 @@ async def _unbuilt_status_message(
class MasteryStatusTool(BaseTool):
"""Read current state, or refresh a current-turn runtime snapshot."""
+ @staticmethod
+ def _working_brief(payload: dict, progress: LearningProgress, focus_id: str = "") -> dict:
+ """Project relevant state; this never alters the stored path or transcript."""
+ from deeptutor.learning.policy import due_reviews
+
+ selected = {payload["next"]["knowledge_point_id"], focus_id} - {""}
+ reviews = due_reviews(progress)
+ selected.update(task.knowledge_point_id for task in reviews[:3])
+ if progress.pending_question is not None:
+ selected.add(progress.pending_question.knowledge_point_id)
+ selected.update(q.knowledge_point_id for q in getattr(progress.pending_question, "questions", ()))
+ points = {kp.id: kp for module in progress.modules for kp in module.knowledge_points}
+ # Preserve the prerequisite closure, even across module boundaries.
+ todo = list(selected)
+ while todo:
+ point = points.get(todo.pop())
+ for prerequisite in point.prerequisite_ids if point else ():
+ if prerequisite not in selected:
+ selected.add(prerequisite)
+ todo.append(prerequisite)
+ overview = payload["map"]
+ payload["map"] = {**overview, "modules": [
+ {**module, "knowledge_points": [kp for kp in module["knowledge_points"] if kp["id"] in selected]}
+ for module in overview["modules"]
+ if any(kp["id"] in selected for kp in module["knowledge_points"])
+ ]}
+ for key in ("learning_stages", "visual_requirements"):
+ payload[key] = {kp: value for kp, value in payload[key].items() if kp in selected}
+ payload["due_review_ids"] = [task.knowledge_point_id for task in reviews[:3]]
+ payload["state_scope"] = "working_brief"
+ payload["inspection_instruction"] = (
+ "This is the current working brief, not the full outline. Counts describe the whole path; "
+ "only the current/focused objective, pending group, prerequisites and first three due "
+ "reviews are expanded. Call mastery_status for the full map before selecting an omitted "
+ "lesson or editing the outline. "
+ "Current learner requests and fresh corrections override historical summaries."
+ )
+ return payload
+
def get_definition(self) -> ToolDefinition:
return ToolDefinition(
name="mastery_status",
@@ -714,7 +753,9 @@ class MasteryStatusTool(BaseTool):
"(new / learning / mastered). Use the current-turn runtime snapshot "
"when supplied; otherwise call this FIRST. Refresh after changing "
"the path, mode, outline, or progress when updated state is needed. "
- "Never guess the next objective or reuse an earlier turn's snapshot."
+ "Never guess the next objective or reuse an earlier turn's snapshot. "
+ "The automatic working brief omits unrelated outline details; call this tool "
+ "for the full map before selecting another lesson or editing the outline."
),
parameters=[],
)
@@ -820,6 +861,8 @@ class MasteryStatusTool(BaseTool):
"call ends the turn."
)
payload["pending_interaction"] = pending_interaction
+ if kwargs.get("_working_brief"):
+ payload = self._working_brief(payload, progress)
return _json_result(payload, meta_key="mastery_status")
diff --git a/deeptutor/runtime/registry/deferred_tools.py b/deeptutor/runtime/registry/deferred_tools.py
index 0d08f8f26..9351122ab 100644
--- a/deeptutor/runtime/registry/deferred_tools.py
+++ b/deeptutor/runtime/registry/deferred_tools.py
@@ -127,6 +127,7 @@ class DeferredToolLoader:
session_id: str,
loaded: set[str],
allowed: set[str] | None = None,
+ capability_names: set[str] | None = None,
) -> None:
self._registry = registry
self._session_id = session_id
@@ -136,6 +137,8 @@ class DeferredToolLoader:
# Enforced here, not only at manifest time, so the model cannot load
# an off-list tool by guessing its name.
self._allowed = set(allowed) if allowed is not None else None
+ # Capability-owned schemas may be deferred without changing global tools.
+ self._capability_names = set(capability_names or ())
self._loaded = {name for name in self._loaded if self._is_allowed(name)}
self._live_schemas: list[dict[str, Any]] | None = None
@@ -156,7 +159,7 @@ class DeferredToolLoader:
stale: set[str] = set()
for name in sorted(self._loaded):
tool = self._registry.get(name)
- if tool is None or not getattr(tool, "deferred", False):
+ if tool is None or not (getattr(tool, "deferred", False) or name in self._capability_names):
stale.add(name)
continue
if not self._is_allowed(name):
@@ -181,7 +184,7 @@ class DeferredToolLoader:
already.append(name)
continue
tool = self._registry.get(name)
- if tool is None or not getattr(tool, "deferred", False) or not self._is_allowed(name):
+ if tool is None or not (getattr(tool, "deferred", False) or name in self._capability_names) or not self._is_allowed(name):
unknown.append(name)
continue
if self._live_schemas is not None:
diff --git a/tests/capabilities/test_mastery_deferred_outline.py b/tests/capabilities/test_mastery_deferred_outline.py
new file mode 100644
index 000000000..a947970a1
--- /dev/null
+++ b/tests/capabilities/test_mastery_deferred_outline.py
@@ -0,0 +1,80 @@
+"""Outline schemas use the native loader while ordinary tutoring stays small."""
+
+import json
+
+import pytest
+
+from deeptutor.agents.loop.pipeline import AgenticLoopPipeline
+from deeptutor.capabilities.mastery.pipeline import MasteryLoopPipeline
+from deeptutor.core.context import UnifiedContext
+from deeptutor.runtime.providers.view import ProviderToolView
+
+
+async def test_outline_tools_remain_discoverable_and_load_in_the_same_live_surface(monkeypatch):
+ async def providers(self, context):
+ self._tool_view = ProviderToolView.empty(self.registry)
+ self._deferred_loader = None
+ self._deferred_pool = []
+
+ monkeypatch.setattr(AgenticLoopPipeline, "_prepare_deferred_tools", providers)
+ monkeypatch.setattr("deeptutor.services.mcp.load_loaded_tools", lambda _: set())
+ monkeypatch.setattr("deeptutor.services.mcp.session_state.record_loaded_tools", lambda *_: None)
+ pipeline = MasteryLoopPipeline(language="en")
+ context = UnifiedContext(session_id="synthetic", metadata={"mastery_mode": True,
+ "mastery_path_id": "p", "mastery_session_mode": "study"})
+ await pipeline._prepare_deferred_tools(context)
+ names = pipeline._compose_enabled_tools(context)
+ assert "mastery_build" not in names
+ assert "mastery_revise" not in names
+ assert "load_tools" in names and "mastery_profile" in names and "mastery_quiz" in names
+ manifest = pipeline._deferred_tools_manifest()
+ assert all(name in manifest for name in ("mastery_build", "mastery_revise"))
+ schemas = pipeline._build_llm_tool_schemas(names, context)
+ pipeline._tool_view.attach(schemas)
+ initial_size = len(json.dumps(schemas))
+ loaded = pipeline._deferred_loader.load(["mastery_revise"])
+ assert loaded["loaded"] == ["mastery_revise"]
+ assert sum(s["function"]["name"] == "mastery_revise" for s in schemas) == 1
+ assert len(json.dumps(schemas)) > initial_size
+ assert pipeline._deferred_loader.load(["mastery_revise"])["already_loaded"]
+ assert not getattr(pipeline.registry.get("mastery_build"), "deferred", False)
+
+
+async def test_outline_mode_keeps_immediately_needed_schemas(monkeypatch):
+ async def providers(self, context):
+ self._tool_view = ProviderToolView.empty(self.registry)
+ self._deferred_loader = None
+ monkeypatch.setattr(AgenticLoopPipeline, "_prepare_deferred_tools", providers)
+ pipeline = MasteryLoopPipeline(language="en")
+ context = UnifiedContext(metadata={"mastery_mode": True, "mastery_session_mode": "outline"})
+ await pipeline._prepare_deferred_tools(context)
+ assert "mastery_build" in pipeline._compose_enabled_tools(context)
+ context.metadata["mastery_session_mode"] = "study"
+ context.allowed_builtin_tools = []
+ await pipeline._prepare_deferred_tools(context)
+ assert "mastery_build" in pipeline._compose_enabled_tools(context)
+
+
+async def test_loaded_outline_schema_survives_a_later_turn_with_provider_loader(monkeypatch):
+ from deeptutor.runtime.registry.deferred_tools import DeferredToolLoader
+
+ async def providers(self, context):
+ # The external provider loader knows no capability names; the local
+ # overlay must restore previously loaded outline tools from the session.
+ loader = DeferredToolLoader(registry=self.registry, session_id="synthetic", loaded=set(), allowed=set())
+ self._tool_view = ProviderToolView(registry=self.registry, loader=loader, pool=(), manifest="")
+ self._deferred_loader = loader
+ monkeypatch.setattr(AgenticLoopPipeline, "_prepare_deferred_tools", providers)
+ monkeypatch.setattr("deeptutor.services.mcp.load_loaded_tools", lambda _: {"mastery_revise"})
+ pipeline = MasteryLoopPipeline(language="en")
+ context = UnifiedContext(session_id="synthetic", metadata={"mastery_mode": True,
+ "mastery_path_id": "p", "mastery_session_mode": "study"})
+ await pipeline._prepare_deferred_tools(context)
+ schemas = pipeline._build_llm_tool_schemas(pipeline._compose_enabled_tools(context), context)
+ pipeline._tool_view.attach(schemas)
+ assert sum(s["function"]["name"] == "mastery_revise" for s in schemas) == 1
+ assert pipeline._deferred_loader.load(["mastery_status", "not_authorized"])["unknown"] == [
+ "mastery_status", "not_authorized"]
diff --git a/tests/capabilities/test_mastery_working_brief.py b/tests/capabilities/test_mastery_working_brief.py
new file mode 100644
index 000000000..eed3c9f3a
--- /dev/null
+++ b/tests/capabilities/test_mastery_working_brief.py
@@ -0,0 +1,66 @@
+"""The automatic snapshot is small; full state remains explicitly inspectable."""
+
+import json
+
+import pytest
+
+from deeptutor.capabilities.mastery.loop import MasteryLoopCapability
+from deeptutor.capabilities.mastery.tools import MasteryStatusTool
+from deeptutor.core.context import UnifiedContext
+from deeptutor.learning.models import KnowledgePoint, LearningModule, LearningProgress
+from deeptutor.learning.service import LearningService
+from deeptutor.learning.storage import LearningStore
+
+
+async def test_runtime_brief_retains_live_objective_prerequisites_and_discovery(tmp_path, monkeypatch):
+ store = LearningStore(root=tmp_path)
+ service = LearningService(store)
+ service.save(LearningProgress(book_id="path", modules=[LearningModule(id=f"m{i}", name=f"Module {i}", order=i,
+ objective=f"Understand module {i}", knowledge_points=[KnowledgePoint(id=f"p{i}-{j}",
+ name=f"Objective {i}-{j}", module_id=f"m{i}", type="concept",
+ prerequisite_ids=["p1-0"] if (i, j) == (0, 0) else [],
+ topic_source_ids=["selected-source"]) for j in range(8)]) for i in range(10)]))
+ monkeypatch.setattr("deeptutor.capabilities.mastery.tools._new_service", lambda: service)
+ before = store.load("path").model_dump()
+ full = await MasteryStatusTool().execute(_mastery_path_id="path")
+ context = UnifiedContext(metadata={"mastery_mode": True, "mastery_path_id": "path",
+ "mastery_session_mode": "study"})
+ block = await MasteryLoopCapability().pre_loop(context, None)
+ brief = json.loads(block.content[block.content.index('{'):])
+ assert brief["state_scope"] == "working_brief"
+ assert brief["next"] == json.loads(full.content)["next"]
+ assert brief["path_revision"] == before["version"]
+ points = {p["id"]: p for m in brief["map"]["modules"] for p in m["knowledge_points"]}
+ assert set(points) == {"p0-0", "p1-0"}
+ assert points["p0-0"]["topic_source_ids"] == ["selected-source"]
+ assert brief["map"]["counts"]["total"] == 80
+ assert "mastery_status" in brief["inspection_instruction"]
+ assert len(block.content) < len(full.content) * 0.3
+ assert store.load("path").model_dump() == before
+ # Outline work needs the entire map, including objective IDs for edits.
+ context.metadata["mastery_session_mode"] = "outline"
+ outline = await MasteryLoopCapability().pre_loop(context, None)
+ assert 'p9-7' in outline.content
+
+
+async def test_native_pending_question_and_profile_remain_exact(tmp_path, monkeypatch):
+ from deeptutor.learning.models import LearnerProfile, PendingQuestion
+
+ store = LearningStore(root=tmp_path)
+ service = LearningService(store)
+ service.save(LearningProgress(book_id="path", modules=[LearningModule(id="m", name="Module", order=0,
+ knowledge_points=[KnowledgePoint(id=p, name=p, module_id="m", type="memory") for p in ("one", "two")])],
+ pending_question=PendingQuestion(question_id="pending", knowledge_point_id="two", module_id="m",
+ prompt="Which relationship applies?", expected_answer="private key"),
+ learner_profile=LearnerProfile(preferences="Use connected explanations", time_budget="Two weeks")))
+ monkeypatch.setattr("deeptutor.capabilities.mastery.tools._new_service", lambda: service)
+ context = UnifiedContext(metadata={"mastery_mode": True, "mastery_path_id": "path"})
+ block = await MasteryLoopCapability().pre_loop(context, None)
+ brief = json.loads(block.content[block.content.index('{'):])
+ full = json.loads((await MasteryStatusTool().execute(_mastery_path_id="path")).content)
+ assert brief["next"]["pending_question"] == full["next"]["pending_question"]
+ assert brief["learner_profile"] == full["learner_profile"]
+ assert "private key" not in block.content
+ assert {p["id"] for m in brief["map"]["modules"] for p in m["knowledge_points"]} == {"two"}