DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
perf(mastery): project working brief and defer outline schemas
yepyhun36fc20196dd9
diff --git a/deeptutor/capabilities/mastery/loop.py b/deeptutor/capabilities/mastery/loop.pyindex 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_modefrom deeptutor.capabilities.mastery.tools import MasteryStatusToolbinding = (@@ -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 Nonediff --git a/deeptutor/capabilities/mastery/pipeline.py b/deeptutor/capabilities/mastery/pipeline.pyindex 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.pyindex 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.pyindex 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 = registryself._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)continueif not self._is_allowed(name):@@ -181,7 +184,7 @@ class DeferredToolLoader:already.append(name)continuetool = 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)continueif self._live_schemas is not None:diff --git a/tests/capabilities/test_mastery_deferred_outline.py b/tests/capabilities/test_mastery_deferred_outline.pynew file mode 100644index 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.pynew file mode 100644index 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"}