DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
feat(mastery): add reviewed outline previews and retry-safe commits
yepyhunc510b133630a
diff --git a/deeptutor/agents/loop/agent_loop.py b/deeptutor/agents/loop/agent_loop.pyindex 7f1a76821..455a12971 100644--- a/deeptutor/agents/loop/agent_loop.py+++ b/deeptutor/agents/loop/agent_loop.py@@ -1050,6 +1050,9 @@ class AgentLoop:await self.pipeline._guard_context_window(request_messages, self.stream)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 --git a/deeptutor/capabilities/mastery/loop.py b/deeptutor/capabilities/mastery/loop.pyindex cfc870c0f..acf253e7c 100644--- a/deeptutor/capabilities/mastery/loop.py+++ b/deeptutor/capabilities/mastery/loop.py@@ -277,6 +277,10 @@ class MasteryLoopCapability:updated["_mastery_session_mode"] = context.metadata.get("mastery_session_mode")updated["_session_id"] = str(context.session_id or "").strip()updated["_turn_id"] = str(context.metadata.get("turn_id") or "").strip()+ if tool_name == "mastery_revise":+ updated["_revision_request_id"] = str(+ context.extension("agent_loop").get("model_call_id") or ""+ )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 --git a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yamlindex f5ae6c25a..7d0df0c6a 100644--- a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml+++ b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml@@ -63,7 +63,7 @@ session:**This mode is for designing this mastery goal's outline with the learner, not for teaching.**This mode has exactly one product: an outline you both agree on. You do not teach content and you do not examine them — the tools for posing questions are refused here.- **Read which of the two `mastery_status` is describing.** `status: empty` means this goal has no outline yet and your job is the **first draft**; `status: active` means an outline already exists and the learner agreed to it, so your job is to **change** it — `mastery_revise` on the smallest piece that is wrong, not `mastery_build` over the whole thing. Those are entirely different experiences on their side; do not confuse them. When one coordinated change touches several modules, make it a single `mastery_revise` call with `modules=[...]`: they are revised together in one atomic change and one report, instead of replaying the whole outline once per module.+ **Read which of the two `mastery_status` is describing.** `status: empty` means this goal has no outline yet and your job is the **first draft**; `status: active` means an outline already exists and the learner agreed to it, so your job is to **change** it — `mastery_revise` on the smallest piece that is wrong, not `mastery_build` over the whole thing. Those are entirely different experiences on their side; do not confuse them. When one coordinated change touches several modules, make it a single `mastery_revise` call with `modules=[...]`: they are revised together in one atomic change and one report, instead of replaying the whole outline once per module. For a coordinated outline edit, first use `action=preview` with those edits. Inspect the exact old/new changes, resets, interaction effects, and proposed map. If coherent and within the learner's request, call `action=commit` with only that `preview_id` in a later model round. If the proposal needs correction or has gone stale, preview a corrected plan; do not assume dependent edits commute.Every round, `mastery_status` gives you `path_name` and `goal` — `goal` is what the learner wrote themselves when they created this. **You are already standing in that goal**: never ask which learning route they mean, never list their other goals for them to choose from, and never `mastery_switch` away. This is the one they opened.diff --git a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yamlindex 731b0cd67..efe2104cb 100644--- a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml+++ b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml@@ -61,7 +61,7 @@ session:**这个模式是用来和学习者一起定下这条精通之路的大纲的,不是用来上课的。**这个模式只有一个产物:一份两人都认可的大纲。你不教内容,也不考他——出题的工具在这个模式下会被拒绝。- **先看 `mastery_status` 告诉你的是哪一种。** `status` 是 `empty` 说明这个目标还没有大纲,你要做的是**从零起草第一版**;`status` 是 `active` 说明大纲已经存在、学习者认可过,你要做的是**改动它**,那就用 `mastery_revise` 动最小的一块,而不是 `mastery_build` 整张换掉。这两件事在学习者那里是完全不同的体验,别搞混。一次协调的改动涉及多个模块时,用一次 `mastery_revise` 调用、传 `modules=[...]` 一起改:它们会作为一次原子变更一并生效、只回一份报告,而不是每个模块都把整张大纲重播一遍。+ **先看 `mastery_status` 告诉你的是哪一种。** `status` 是 `empty` 说明这个目标还没有大纲,你要做的是**从零起草第一版**;`status` 是 `active` 说明大纲已经存在、学习者认可过,你要做的是**改动它**,那就用 `mastery_revise` 动最小的一块,而不是 `mastery_build` 整张换掉。这两件事在学习者那里是完全不同的体验,别搞混。一次协调的改动涉及多个模块时,用一次 `mastery_revise` 调用、传 `modules=[...]` 一起改:它们会作为一次原子变更一并生效、只回一份报告,而不是每个模块都把整张大纲重播一遍。 协调修改大纲时,先传 `action=preview` 预览这些改动,检查精确的新旧差异、进度重置、交互影响和拟议大纲。若符合学习者的请求且逻辑一致,在后续模型轮次中仅传 `action=commit` 和该 `preview_id` 提交。若方案需要修改或已过时,重新预览;不要假定互相依赖的编辑可以任意合并。`mastery_status` 每一轮都会告诉你 `path_name` 和 `goal`——`goal` 就是学习者创建这个目标时亲手写下的话。**你已经站在这个目标里了**:绝不要问他「你想聊哪条学习路线」,也不要列出他别的目标让他选,更不要 `mastery_switch` 到别处去。他点进来的就是这一个。diff --git a/deeptutor/capabilities/mastery/tools.py b/deeptutor/capabilities/mastery/tools.pyindex 16be981f4..5e10a0730 100644--- a/deeptutor/capabilities/mastery/tools.py+++ b/deeptutor/capabilities/mastery/tools.py@@ -2219,9 +2219,26 @@ class MasteryReviseTool(BaseTool):"SEVERAL modules, pass them together as modules=[{module_id, ""rewrite, add, remove}, ...] in ONE call — they are applied, ""validated and reported as a single atomic revision, instead "- "of one full-outline round per module."+ "of one full-outline round per module. For coordinated outline "+ "edits, action=preview returns the exact proposed state changes "+ "without saving. Review them, then use action=commit with only "+ "that preview_id in a later model round. Omit action for the "+ "existing immediate revision behavior."),parameters=[+ ToolParameter(+ name="action",+ type="string",+ enum=["preview", "commit"],+ description="Preview before a reviewed commit; omit for a direct revision.",+ required=False,+ ),+ ToolParameter(+ name="preview_id",+ type="integer",+ description="Commit only: the identifier returned by the reviewed preview.",+ required=False,+ ),ToolParameter(name="module_id",type="string",@@ -2297,75 +2314,76 @@ class MasteryReviseTool(BaseTool):if not path_id:return _no_path_result()+ from deeptutor.learning.storage import LearningConflictError++ action = kwargs.get("action")+ if action not in (None, "preview", "commit"):+ return ToolResult(content="Use action preview or commit, or omit it.", success=False)+ service = _new_service()+ if action == "commit":+ if any(+ kwargs.get(key) is not None+ for key in ("module_id", "modules", "rewrite", "add", "remove")+ ):+ return ToolResult(+ content="Commit takes only preview_id; omit all revision edits.", success=False+ )+ try:+ progress, receipt = service.commit_module_revision(+ path_id,+ kwargs.get("preview_id"),+ session_id=_resolve_session_id(kwargs),+ turn_id=_resolve_turn_id(kwargs),+ request_id=str(kwargs.get("_revision_request_id") or ""),+ )+ except (ValueError, TypeError, KeyError, LearningConflictError) as exc:+ return ToolResult(content=f"Revision not saved: {exc}", success=False)+ return _json_result(+ {+ "status": "committed",+ **receipt,+ "path_revision": progress.version,+ "map": map_summary(progress),+ },+ meta_key="mastery_revise",+ )+ if kwargs.get("preview_id") is not None:+ return ToolResult(content="Use preview_id only with action commit.", success=False)+specs, spec_error = _revise_specs(kwargs)if spec_error is not None:return ToolResult(content=spec_error, success=False)- service = _new_service()progress = _load_path(service, path_id)if progress is None or not progress.modules:return _no_built_path_result("mastery_revise")- known_modules = {m.id: m for m in progress.modules}- targets: list[LearningModule] = []- for module_id in specs:- target = known_modules.get(module_id)- if target is None:- known = ", ".join(f"{m.id!r} ({m.name})" for m in progress.modules)- return ToolResult(- content=(- f"No module {module_id!r} in this mastery goal. Revise one of: {known}."- ),- success=False,- )- targets.append(target)-- removals = {- str(raw or "").strip() for spec in specs.values() for raw in (spec.get("remove") or [])- }- blocked_by = [- f"{point.name!r} ({point.id})"- for module in progress.modules- for point in module.knowledge_points- if point.id not in removals and any(ref in removals for ref in point.prerequisite_ids)- ]- if blocked_by:- return ToolResult(- content=(- "Those knowledge points are still required by: "- + ", ".join(blocked_by)- + ". Remove or change those prerequisites first."- ),- success=False,+ try:+ applied, targets, revised_by_module, resets_by_module = _plan_module_revision(+ progress, specs)-- taken = {kp.id for m in progress.modules for kp in m.knowledge_points}- revised_by_module: dict[str, list[KnowledgePoint]] = {}- resets_by_module: dict[str, list[str]] = {}- rewrite_ids: dict[str, str] = {}- for target in targets:- revised, error, resets, rewrites = _revise_points(- progress, target, specs[target.id], taken=taken+ except (ValueError, TypeError) as exc:+ return ToolResult(content=str(exc), success=False)+ if action == "preview":+ try:+ result, proposed = service.preview_module_revision(+ path_id,+ applied,+ expected_revision=progress.version,+ session_id=_resolve_session_id(kwargs),+ request_id=str(kwargs.get("_revision_request_id") or ""),+ )+ except (ValueError, TypeError, KeyError, LearningConflictError) as exc:+ return ToolResult(content=f"Revision not saved: {exc}", success=False)+ return _json_result(+ {+ "status": "preview_only_not_saved",+ **result,+ "proposed_map": map_summary(proposed),+ "next_step": "Review every change and objective reset. Commit this preview_id in a later model round if coherent and within the learner's request; otherwise correct the edits and preview again.",+ },+ meta_key="mastery_revision_preview",)- if error:- # First rejection refuses the whole request: a coordinated- # edit must not half-apply because its third module was bad.- return ToolResult(content=error, success=False)- revised_by_module[target.id] = revised- resets_by_module[target.id] = resets- rewrite_ids.update(rewrites)-- applied = [- module.model_copy(deep=True, update={"knowledge_points": revised_by_module[module.id]})- if module.id in revised_by_module- else module.model_copy(deep=True)- for module in sorted(progress.modules, key=lambda m: m.order)- ]- for module in applied:- for point in module.knowledge_points:- point.prerequisite_ids = [- rewrite_ids.get(ref, ref) for ref in point.prerequisite_ids- ]try:progress = service.replace_modules_for_path(path_id,@@ -2702,6 +2720,63 @@ def _revised_point_id(module_id: str, taken: set[str]) -> str:index += 1+def _plan_module_revision(progress: LearningProgress, specs: dict[str, dict[str, Any]]):+ """Shared planner for direct and reviewed revisions; never mutates stored state."""+ known_modules = {m.id: m for m in progress.modules}+ targets: list[LearningModule] = []+ for module_id in specs:+ target = known_modules.get(module_id)+ if target is None:+ known = ", ".join(f"{m.id!r} ({m.name})" for m in progress.modules)+ raise ValueError(+ f"No module {module_id!r} in this mastery goal. Revise one of: {known}."+ )+ targets.append(target)++ removals = {+ str(raw or "").strip() for spec in specs.values() for raw in (spec.get("remove") or [])+ }+ blocked_by = [+ f"{point.name!r} ({point.id})"+ for module in progress.modules+ for point in module.knowledge_points+ if point.id not in removals and any(ref in removals for ref in point.prerequisite_ids)+ ]+ if blocked_by:+ raise ValueError(+ "Those knowledge points are still required by: "+ + ", ".join(blocked_by)+ + ". Remove or change those prerequisites first."+ )++ taken = {kp.id for m in progress.modules for kp in m.knowledge_points}+ revised_by_module: dict[str, list[KnowledgePoint]] = {}+ resets_by_module: dict[str, list[str]] = {}+ rewrite_ids: dict[str, str] = {}+ for target in targets:+ revised, error, resets, rewrites = _revise_points(+ progress, target, specs[target.id], taken=taken+ )+ if error:+ # First rejection refuses the whole request: a coordinated+ # edit must not half-apply because its third module was bad.+ raise ValueError(error)+ revised_by_module[target.id] = revised+ resets_by_module[target.id] = resets+ rewrite_ids.update(rewrites)++ applied = [+ module.model_copy(deep=True, update={"knowledge_points": revised_by_module[module.id]})+ if module.id in revised_by_module+ else module.model_copy(deep=True)+ for module in sorted(progress.modules, key=lambda m: m.order)+ ]+ for module in applied:+ for point in module.knowledge_points:+ point.prerequisite_ids = [rewrite_ids.get(ref, ref) for ref in point.prerequisite_ids]+ return applied, targets, revised_by_module, resets_by_module++def _revise_specs(kwargs: dict[str, Any]) -> tuple[dict[str, dict[str, Any]], str | None]:"""Read one revise request into ``{module_id: spec}``, or say why not.diff --git a/deeptutor/learning/outline_revision.py b/deeptutor/learning/outline_revision.pynew file mode 100644index 000000000..ddfc615f5--- /dev/null+++ b/deeptutor/learning/outline_revision.py@@ -0,0 +1,54 @@+"""Exact outline preview differences, independent of model summaries."""++from __future__ import annotations++import hashlib+import json+from typing import Any++from deeptutor.learning.models import LearningProgress+++def state_digest(progress: LearningProgress) -> str:+ state = progress.model_dump(mode="json", exclude={"version", "updated_at"})+ return hashlib.sha256(+ json.dumps(state, ensure_ascii=False, sort_keys=True, allow_nan=False).encode("utf-8")+ ).hexdigest()+++def exact_diff(before: Any, after: Any, path: str = "") -> list[dict[str, Any]]:+ """JSON-pointer changes with exact old/new values, including additions/removals."""+ if isinstance(before, dict) and isinstance(after, dict):+ changes = []+ for key in sorted(before.keys() | after.keys()):+ pointer = path + "/" + str(key).replace("~", "~0").replace("/", "~1")+ if key in before and key in after:+ changes.extend(exact_diff(before[key], after[key], pointer))+ else:+ changes.append(+ {+ "path": pointer,+ "before_exists": key in before,+ "after_exists": key in after,+ "before": before.get(key),+ "after": after.get(key),+ }+ )+ return changes+ if isinstance(before, list) and isinstance(after, list) and len(before) == len(after):+ return [+ change+ for i, (a, b) in enumerate(zip(before, after))+ for change in exact_diff(a, b, f"{path}/{i}")+ ]+ if type(before) is type(after) and before == after:+ return []+ return [+ {+ "path": path,+ "before_exists": True,+ "after_exists": True,+ "before": before,+ "after": after,+ }+ ]diff --git a/deeptutor/learning/service.py b/deeptutor/learning/service.pyindex e5bd1d3f9..8fed67b89 100644--- a/deeptutor/learning/service.py+++ b/deeptutor/learning/service.py@@ -1063,134 +1063,173 @@ class LearningService:edits that already carry durable IDs. Position never establishes identity."""- def replace(tx):- if name.strip() and not tx.progress.name.strip():- tx.progress.name = name.strip()[:_MAX_PATH_NAME_LEN]- applied_modules = [module.model_copy(deep=True) for module in modules]- identity_map: dict[str, list[str] | str] = {- "mode": "append" if append else ("fresh" if fresh_identity else identity_mode),- "preserved": [],- "minted": [],- "dropped": [],- }- if append:+ progress, _ = self._store.mutate(+ book_id,+ lambda tx: self._replace_module_set(+ tx,+ modules,+ append=append,+ name=name,+ event_type=event_type,+ session_id=session_id,+ turn_id=turn_id,+ identity_mode=identity_mode,+ relation_refs=relation_refs,+ source_aliases=source_aliases,+ topic_sources=topic_sources,+ fresh_identity=fresh_identity,+ ),+ create=True,+ )+ return progress++ def _replace_module_set(+ self,+ tx,+ modules: list[LearningModule],+ *,+ append: bool = False,+ name: str = "",+ event_type: str = "path.modules_replaced",+ session_id: str = "",+ turn_id: str = "",+ identity_mode: str = "explicit",+ relation_refs: dict[str, RelationRefs] | None = None,+ source_aliases: dict[str, str] | None = None,+ topic_sources: list[TopicSource] | None = None,+ fresh_identity: bool = False,+ dry_run: bool = False,+ ) -> dict[str, Any]:+ """Shared identity, relation and question effects for preview and save."""+ book_id = tx.progress.book_id+ if name.strip() and not tx.progress.name.strip():+ tx.progress.name = name.strip()[:_MAX_PATH_NAME_LEN]+ applied_modules = [module.model_copy(deep=True) for module in modules]+ identity_map: dict[str, list[str] | str] = {+ "mode": "append" if append else ("fresh" if fresh_identity else identity_mode),+ "preserved": [],+ "minted": [],+ "dropped": [],+ }+ if append:+ reserved = _reserved_objective_ids(tx.progress)+ offset = len(tx.progress.modules)+ minted: list[str] = []+ for index, module in enumerate(applied_modules, start=offset):+ module.id = f"{book_id}_m{index}"+ module.order = index+ for kp_index, kp in enumerate(module.knowledge_points):+ kp.module_id = module.id+ candidate = f"{module.id}_kp{kp_index}"+ if candidate in reserved:+ kp.id = _new_objective_id(module.id, reserved)+ else:+ kp.id = candidate+ reserved.add(candidate)+ tx.progress.knowledge_types[kp.id] = kp.type+ minted.append(kp.id)+ identity_map["minted"] = minted+ existing_modules = tx.progress.modules+ self._resolve_final_relations(+ applied_modules,+ modules,+ relation_refs or {},+ source_aliases or {},+ tx.topic_sources() if topic_sources is None else topic_sources,+ existing_modules=existing_modules,+ )+ validate_objective_relations(+ [*existing_modules, *applied_modules],+ tx.topic_sources() if topic_sources is None else topic_sources,+ )+ tx.progress.modules.extend(applied_modules)+ if not tx.progress.current_module_id and applied_modules:+ tx.progress.current_module_id = applied_modules[0].id+ tx.progress.current_kp_index = 0+ else:+ current_kp_id = ""+ for current_module in tx.progress.modules:+ if current_module.id != tx.progress.current_module_id:+ continue+ if 0 <= tx.progress.current_kp_index < len(current_module.knowledge_points):+ current_kp_id = current_module.knowledge_points[tx.progress.current_kp_index].id+ break+ pending_kp_id = (+ tx.progress.pending_question.knowledge_point_id+ if tx.progress.pending_question is not None+ else ""+ )+ active_interaction = tx.active_interaction()+ active_kp_id = (+ active_interaction.question.knowledge_point_id+ if active_interaction is not None+ else ""+ )++ if fresh_identity:reserved = _reserved_objective_ids(tx.progress)- offset = len(tx.progress.modules)- minted: list[str] = []- for index, module in enumerate(applied_modules, start=offset):- module.id = f"{book_id}_m{index}"- module.order = index- for kp_index, kp in enumerate(module.knowledge_points):+ for module in applied_modules:+ for kp in module.knowledge_points:+ kp.id = _new_objective_id(module.id, reserved)kp.module_id = module.id- candidate = f"{module.id}_kp{kp_index}"- if candidate in reserved:- kp.id = _new_objective_id(module.id, reserved)- else:- kp.id = candidate- reserved.add(candidate)- tx.progress.knowledge_types[kp.id] = kp.type- minted.append(kp.id)- identity_map["minted"] = minted- existing_modules = tx.progress.modules- self._resolve_final_relations(- applied_modules,- modules,- relation_refs or {},- source_aliases or {},- tx.topic_sources() if topic_sources is None else topic_sources,- existing_modules=existing_modules,- )- validate_objective_relations(- [*existing_modules, *applied_modules],- tx.topic_sources() if topic_sources is None else topic_sources,+ identity_map["minted"] = [+ kp.id for module in applied_modules for kp in module.knowledge_points+ ]+ identity_map["dropped"] = sorted(+ {kp.id for module in tx.progress.modules for kp in module.knowledge_points})- tx.progress.modules.extend(applied_modules)- if not tx.progress.current_module_id and applied_modules:- tx.progress.current_module_id = applied_modules[0].id- tx.progress.current_kp_index = 0else:- current_kp_id = ""- for current_module in tx.progress.modules:- if current_module.id != tx.progress.current_module_id:- continue- if 0 <= tx.progress.current_kp_index < len(current_module.knowledge_points):- current_kp_id = current_module.knowledge_points[- tx.progress.current_kp_index- ].id- break- pending_kp_id = (- tx.progress.pending_question.knowledge_point_id- if tx.progress.pending_question is not None- else ""- )- active_interaction = tx.active_interaction()- active_kp_id = (- active_interaction.question.knowledge_point_id- if active_interaction is not None- else ""- )-- if fresh_identity:- reserved = _reserved_objective_ids(tx.progress)- for module in applied_modules:- for kp in module.knowledge_points:- kp.id = _new_objective_id(module.id, reserved)- kp.module_id = module.id- identity_map["minted"] = [- kp.id for module in applied_modules for kp in module.knowledge_points- ]- identity_map["dropped"] = sorted(- {kp.id for module in tx.progress.modules for kp in module.knowledge_points}- )- else:- identity_map = assign_objective_identities(- tx.progress,- applied_modules,- identity_mode=identity_mode,- )- sources = tx.topic_sources() if topic_sources is None else topic_sources- self._resolve_final_relations(+ identity_map = assign_objective_identities(+ tx.progress,applied_modules,- modules,- relation_refs or {},- source_aliases or {},- sources,+ identity_mode=identity_mode,)- validate_objective_relations(applied_modules, sources)- self.replace_modules(tx.progress, applied_modules)- objective_locations = {- kp.id: (module.id, kp_index)- for module in applied_modules- for kp_index, kp in enumerate(module.knowledge_points)- }+ sources = tx.topic_sources() if topic_sources is None else topic_sources+ self._resolve_final_relations(+ applied_modules,+ modules,+ relation_refs or {},+ source_aliases or {},+ sources,+ )+ validate_objective_relations(applied_modules, sources)+ self.replace_modules(tx.progress, applied_modules)+ objective_locations = {+ kp.id: (module.id, kp_index)+ for module in applied_modules+ for kp_index, kp in enumerate(module.knowledge_points)+ }- if current_kp_id in objective_locations:- (- tx.progress.current_module_id,- tx.progress.current_kp_index,- ) = objective_locations[current_kp_id]- elif applied_modules:- tx.progress.current_module_id = applied_modules[0].id- tx.progress.current_kp_index = 0- else:- tx.progress.current_module_id = ""- tx.progress.current_kp_index = 0+ if current_kp_id in objective_locations:+ (+ tx.progress.current_module_id,+ tx.progress.current_kp_index,+ ) = objective_locations[current_kp_id]+ elif applied_modules:+ tx.progress.current_module_id = applied_modules[0].id+ tx.progress.current_kp_index = 0+ else:+ tx.progress.current_module_id = ""+ tx.progress.current_kp_index = 0- if tx.progress.pending_question is not None:- if pending_kp_id not in objective_locations:- tx.progress.pending_question = None- else:- pending_module_id, _ = objective_locations[pending_kp_id]- tx.progress.pending_question.module_id = pending_module_id+ if tx.progress.pending_question is not None:+ if pending_kp_id not in objective_locations:+ tx.progress.pending_question = None+ else:+ pending_module_id, _ = objective_locations[pending_kp_id]+ tx.progress.pending_question.module_id = pending_module_id- if active_interaction is not None:- if active_kp_id not in objective_locations:+ if active_interaction is not None:+ if active_kp_id not in objective_locations:+ if not dry_run:tx.abandon_active_interactions()- else:- active_module_id, _ = objective_locations[active_kp_id]- if active_interaction.question.module_id != active_module_id:- active_interaction.question.module_id = active_module_id+ else:+ active_module_id, _ = objective_locations[active_kp_id]+ if active_interaction.question.module_id != active_module_id:+ active_interaction.question.module_id = active_module_id+ if not dry_run:tx.put_interaction(active_interaction)+ if not dry_run:tx.touch()tx.emit(event_type,@@ -1205,9 +1244,117 @@ class LearningService:session_id=session_id,turn_id=turn_id,)+ return {+ "identity_map": identity_map,+ "active_interaction_removed": bool(+ active_kp_id and active_kp_id not in objective_locations+ )+ if not append+ else False,+ }- progress, _ = self._store.mutate(book_id, replace, create=True)- return progress+ def preview_module_revision(+ self,+ book_id: str,+ modules: list[LearningModule],+ *,+ expected_revision: int,+ session_id: str,+ request_id: str = "",+ ) -> tuple[dict[str, Any], LearningProgress]:+ """Run the real replacement engine on a copy, then record the reviewed draft."""+ from deeptutor.learning.outline_revision import exact_diff, state_digest+ from deeptutor.learning.storage import LearningConflictError++ with self._store.transaction(book_id) as tx:+ if tx.base_revision != expected_revision:+ raise LearningConflictError(book_id, expected_revision, tx.base_revision)+ original = tx.progress+ tx.progress = original.model_copy(deep=True)+ try:+ effects = self._replace_module_set(tx, modules, dry_run=True)+ proposed = tx.progress.model_copy(deep=True)+ finally:+ tx.progress = original+ # Save-time bookkeeping is not a curriculum change or progress reset.+ exclude = {"version", "updated_at"}+ changes = exact_diff(+ original.model_dump(mode="json", exclude=exclude),+ proposed.model_dump(mode="json", exclude=exclude),+ )+ if not changes:+ raise ValueError("This plan changes nothing. Leave the current outline in place.")+ payload = {+ "base_revision": expected_revision,+ "request_id": request_id,+ "before_digest": state_digest(original),+ "after_digest": state_digest(proposed),+ "modules": [module.model_dump(mode="json") for module in proposed.modules],+ "changes": changes,+ "effects": effects,+ }+ preview_id = tx.record_module_preview(payload, session_id=session_id)+ return {+ "preview_id": preview_id,+ "base_revision": expected_revision,+ "changes": changes,+ "effects": effects,+ }, proposed++ def commit_module_revision(+ self,+ book_id: str,+ preview_id: int,+ *,+ session_id: str,+ turn_id: str = "",+ request_id: str = "",+ ) -> tuple[LearningProgress, dict[str, Any]]:+ """Apply only the persisted draft; stale state rolls back instead of overwriting."""+ from deeptutor.learning.outline_revision import state_digest+ from deeptutor.learning.storage import LearningConflictError++ with self._store.transaction(book_id) as tx:+ draft = tx.module_preview(preview_id, session_id=session_id)+ replayed = draft["committed_revision"] is not None+ if not replayed:+ if draft.get("request_id") and (+ not request_id or request_id == draft["request_id"]+ ):+ raise ValueError(+ "Inspect this preview in a later model round before committing it."+ )+ expected = int(draft["base_revision"])+ if expected != tx.base_revision:+ raise LearningConflictError(book_id, expected, tx.base_revision)+ if state_digest(tx.progress) != draft["before_digest"]:+ raise ValueError(+ "The outline state changed. Create and review a fresh preview."+ )+ self._replace_module_set(+ tx,+ [LearningModule.model_validate(m) for m in draft["modules"]],+ session_id=session_id,+ turn_id=turn_id,+ )+ if state_digest(tx.progress) != draft["after_digest"]:+ raise ValueError(+ "The preview no longer matches the engine result. Nothing was saved."+ )+ tx.emit(+ "path.modules_revision_committed",+ {"preview_id": preview_id},+ session_id=session_id,+ turn_id=turn_id,+ )+ receipt = {+ "preview_id": preview_id,+ "replayed": replayed,+ "applied_revision": draft["committed_revision"]+ if replayed+ else tx.base_revision + 1,+ }+ return tx.progress, receiptdef create_topic(self,diff --git a/deeptutor/learning/storage.py b/deeptutor/learning/storage.pyindex f7f000f79..50fadb8b1 100644--- a/deeptutor/learning/storage.py+++ b/deeptutor/learning/storage.py@@ -151,6 +151,48 @@ class LearningTransaction:def events(self) -> list[tuple[str, dict[str, Any], str, str]]:return list(self._events)+ def record_module_preview(self, payload: dict[str, Any], *, session_id: str) -> int:+ """Persist a draft without modifying progress or publishing a new revision."""+ cursor = self._conn.execute(+ """INSERT INTO mastery_events+ (path_id, revision, event_type, payload_json, session_id, created_at)+ VALUES (?, ?, 'path.modules_previewed', ?, ?, ?)""",+ (+ self.progress.book_id,+ self.base_revision,+ json.dumps(payload, ensure_ascii=False, allow_nan=False),+ session_id,+ time.time(),+ ),+ )+ return int(cursor.lastrowid)++ def module_preview(self, preview_id: int, *, session_id: str) -> dict[str, Any]:+ if type(preview_id) is not int or preview_id < 1:+ raise ValueError("Use the integer preview_id returned by a successful preview.")+ row = self._conn.execute(+ """SELECT payload_json, created_at FROM mastery_events+ WHERE id = ? AND path_id = ? AND session_id = ?+ AND event_type = 'path.modules_previewed'""",+ (preview_id, self.progress.book_id, session_id),+ ).fetchone()+ if row is None:+ raise ValueError("Preview is unavailable in this path/session. Create a fresh preview.")+ applied = self._conn.execute(+ """SELECT revision FROM mastery_events WHERE path_id = ?+ AND event_type = 'path.modules_revision_committed'+ AND json_extract(payload_json, '$.preview_id') = ? LIMIT 1""",+ (self.progress.book_id, preview_id),+ ).fetchone()+ if applied is None and time.time() - float(row["created_at"]) > 3600:+ raise ValueError(+ "Preview expired. Create and review a fresh preview before committing."+ )+ return {+ **json.loads(row["payload_json"]),+ "committed_revision": int(applied["revision"]) if applied else None,+ }+@staticmethoddef _interaction_from_row(row: sqlite3.Row | None) -> MasteryInteraction | None:if row is None:diff --git a/tests/capabilities/test_mastery_reviewed_revision.py b/tests/capabilities/test_mastery_reviewed_revision.pynew file mode 100644index 000000000..52cc31fab--- /dev/null+++ b/tests/capabilities/test_mastery_reviewed_revision.py@@ -0,0 +1,442 @@+"""Reviewed outline edits: real SQLite isolation, atomicity, and exact payloads."""++from concurrent.futures import ThreadPoolExecutor+from copy import deepcopy+import json+import sqlite3+from types import SimpleNamespace++import pytest++from deeptutor.capabilities.mastery.tools import (+ MasteryReviseTool,+ _plan_module_revision,+ _revise_specs,+)+from deeptutor.learning.models import (+ KnowledgePoint,+ KnowledgeType,+ LearningModule,+ MasteryInteraction,+ PendingQuestion,+ TopicMetadata,+ TopicSource,+ TopicSourceKind,+)+from deeptutor.learning.outline_revision import exact_diff+from deeptutor.learning.service import LearningService+from deeptutor.learning.storage import LearningConflictError, LearningStore+++def system(tmp_path):+ store = LearningStore(root=tmp_path)+ service = LearningService(store)+ modules = [+ LearningModule(+ id=f"m{i}",+ name=f"Module {i}",+ order=i,+ objective=f"Purpose {i}",+ knowledge_points=[+ KnowledgePoint(+ id=f"p{i}",+ name=f"Objective {i}",+ type=KnowledgeType.CONCEPT,+ module_id=f"m{i}",+ prerequisite_ids=["p0"] if i == 1 else [],+ required_visual_tasks=["relationship"] if i == 0 else [],+ )+ ],+ )+ for i in range(3)+ ]+ service.replace_modules_for_path("path", modules)++ def prepare(tx):+ tx.put_topic(+ TopicMetadata(path_id="path"),+ [+ TopicSource(+ id="source",+ kind=TopicSourceKind.BOOK,+ label="Synthetic source",+ )+ ],+ )+ tx.progress.modules[0].knowledge_points[0].topic_source_ids = ["source"]+ tx.progress.mastery_levels = {"p0": 0.3, "p2": 1.0}+ tx.progress.qualitative_mastery = {"p2": True}+ tx.progress.feynman_explanations = {"p2": "The comparison finally helped."}+ pending = PendingQuestion(+ question_id="question",+ knowledge_point_id="p0",+ module_id="m0",+ prompt="Explain the relationship",+ expected_answer="Because of the boundary",+ )+ tx.progress.pending_question = pending+ tx.put_interaction(+ MasteryInteraction(+ interaction_id="question",+ path_id="path",+ question=pending,+ session_id="session",+ )+ )++ store.mutate("path", prepare)+ return store, service+++def revisions():+ return [+ {+ "module_id": f"m{i}",+ "rewrite": [+ {+ "knowledge_point_id": f"p{i}",+ "name": f"Revised objective {i}",+ }+ ],+ }+ for i in range(2)+ ]+++def plan_revisions(progress, edits):+ specs, error = _revise_specs({"modules": edits})+ if error:+ raise ValueError(error)+ return _plan_module_revision(progress, specs)[0]+++def preview(system, edits=None):+ store, service = system+ progress = store.load("path")+ return service.preview_module_revision(+ "path",+ plan_revisions(progress, edits or revisions()),+ expected_revision=progress.version,+ session_id="session",+ )+++def state(progress):+ return progress.model_dump(mode="json", exclude={"version", "updated_at"})+++def apply_diff(before, changes):+ result = deepcopy(before)+ for change in changes:+ parts = [x.replace("~1", "/").replace("~0", "~") for x in change["path"].split("/")[1:]]+ target = result+ for part in parts[:-1]:+ target = target[int(part)] if isinstance(target, list) else target[part]+ key = int(parts[-1]) if isinstance(target, list) else parts[-1]+ if change["before_exists"]:+ assert target[key] == change["before"]+ if change["after_exists"]:+ target[key] = deepcopy(change["after"])+ else:+ del target[key]+ return result+++def test_preview_is_pure_and_commit_is_exact_and_retry_safe(system):+ store, service = system+ before = store.load("path")+ interaction = store.get_active_interaction("path").model_dump(mode="json")+ result, proposed = preview(system)+ assert store.load("path").model_dump() == before.model_dump()+ assert store.get_active_interaction("path").model_dump(mode="json") == interaction+ assert apply_diff(state(before), result["changes"]) == state(proposed)+ assert proposed.modules[1].knowledge_points[0].prerequisite_ids == [+ proposed.modules[0].knowledge_points[0].id+ ]+ assert proposed.modules[0].knowledge_points[0].required_visual_tasks == ["relationship"]+ assert proposed.modules[0].knowledge_points[0].topic_source_ids == ["source"]+ assert proposed.mastery_levels["p2"] == 1+ assert proposed.feynman_explanations["p2"] == "The comparison finally helped."+ assert "p0" not in proposed.mastery_levels+ assert proposed.pending_question is None+ assert result["effects"]["active_interaction_removed"] is True+ committed, receipt = service.commit_module_revision(+ "path",+ result["preview_id"],+ session_id="session",+ )+ assert state(committed) == state(proposed)+ assert committed.version == before.version + 1+ assert not receipt["replayed"]+ assert store.get_active_interaction("path") is None+ # A fresh service (including a process restart) can safely retry the receipt.+ retry, receipt2 = LearningService(LearningStore(root=store._root)).commit_module_revision(+ "path",+ result["preview_id"],+ session_id="session",+ )+ assert retry.model_dump() == committed.model_dump()+ assert receipt2["replayed"]+ assert receipt2["applied_revision"] == committed.version+++def test_noop_preview_does_not_reset_or_publish_progress(system):+ store, service = system+ before = store.load("path")+ with pytest.raises(ValueError, match="changes nothing"):+ service.preview_module_revision(+ "path", before.modules, expected_revision=before.version, session_id="session"+ )+ assert store.load("path").model_dump() == before.model_dump()+++def test_unrelated_question_and_mastered_evidence_survive_batch(system):+ store, service = system+ before = store.get_active_interaction("path").model_dump()+ result, proposed = preview(system, [{"module_id": "m1", "add": [{"name": "Extra objective"}]}])+ assert proposed.pending_question.knowledge_point_id == "p0"+ committed, _ = service.commit_module_revision(+ "path", result["preview_id"], session_id="session"+ )+ assert store.get_active_interaction("path").model_dump() == before+ assert committed.qualitative_mastery["p2"] is True+++def test_retry_after_later_progress_returns_current_state_not_old_snapshot(system):+ store, service = system+ result, _ = preview(system)+ service.commit_module_revision("path", result["preview_id"], session_id="session")+ now = store.load("path")+ current = service.replace_modules_for_path("path", now.modules, name="Later name")+ replay, receipt = service.commit_module_revision(+ "path", result["preview_id"], session_id="session"+ )+ assert receipt["replayed"] is True+ assert receipt["applied_revision"] < replay.version+ assert replay.model_dump() == current.model_dump()+++def test_stale_preview_and_preview_load_race_cannot_overwrite(system):+ store, service = system+ result, _ = preview(system)+ old = store.load("path")+ current = service.replace_modules_for_path("path", old.modules, name="Changed name")+ with pytest.raises(LearningConflictError):+ service.commit_module_revision("path", result["preview_id"], session_id="session")+ with pytest.raises(LearningConflictError):+ service.preview_module_revision(+ "path", old.modules, expected_revision=old.version, session_id="session"+ )+ assert store.load("path").model_dump() == current.model_dump()+++def test_preview_is_scoped_to_path_session_and_workspace(system, tmp_path):+ store, service = system+ result, _ = preview(system)+ modules = store.load("path").modules+ modules[0].knowledge_points[0].topic_source_ids = []+ service.replace_modules_for_path("other", modules)+ for path_id, session in [("other", "session"), ("path", "different")]:+ with pytest.raises(ValueError, match="unavailable"):+ service.commit_module_revision(path_id, result["preview_id"], session_id=session)+ isolated = LearningService(LearningStore(root=tmp_path / "other-workspace"))+ isolated.replace_modules_for_path("path", modules)+ with pytest.raises(ValueError, match="unavailable"):+ isolated.commit_module_revision("path", result["preview_id"], session_id="session")+++def test_expired_or_tampered_preview_cannot_commit(system):+ store, service = system+ result, _ = preview(system)+ before = store.load("path").model_dump()+ with sqlite3.connect(store.db_path) as db:+ db.execute("UPDATE mastery_events SET created_at=0 WHERE id=?", (result["preview_id"],))+ with pytest.raises(ValueError, match="expired"):+ service.commit_module_revision("path", result["preview_id"], session_id="session")+ result, _ = preview(system)+ with sqlite3.connect(store.db_path) as db:+ raw = db.execute(+ "SELECT payload_json FROM mastery_events WHERE id=?", (result["preview_id"],)+ ).fetchone()[0]+ payload = json.loads(raw)+ payload["after_digest"] = "incorrect"+ db.execute(+ "UPDATE mastery_events SET payload_json=? WHERE id=?",+ (json.dumps(payload), result["preview_id"]),+ )+ with pytest.raises(ValueError, match="matches"):+ service.commit_module_revision("path", result["preview_id"], session_id="session")+ assert store.load("path").model_dump() == before+ assert store.get_active_interaction("path") is not None # SQL side effects rolled back too.+++def test_concurrent_drafts_have_one_winner_not_a_partial_merge(system):+ store, _ = system+ first, _ = preview(system)+ second, _ = preview(system, [{"module_id": "m1", "add": [{"name": "New objective"}]}])++ def commit(preview_id):+ try:+ return LearningService(LearningStore(root=store._root)).commit_module_revision(+ "path",+ preview_id,+ session_id="session",+ )[1]+ except LearningConflictError:+ return "conflict"++ with ThreadPoolExecutor(max_workers=2) as executor:+ results = list(executor.map(commit, [first["preview_id"], second["preview_id"]]))+ assert results.count("conflict") == 1+ assert sum(isinstance(x, dict) for x in results) == 1+++ "edit",+ [+ [{"module_id": "m2", "rewrite": [{"knowledge_point_id": "p2", "name": "New content"}]}],+ [{"module_id": "m0", "remove": ["p0"], "add": [{"name": "New content"}]}],+ [{"module_id": "m0", "add": [{"name": "New content", "prerequisite_ids": ["unknown"]}]}],+ [+ {+ "module_id": "m0",+ "rewrite": [+ {"knowledge_point_id": "p0", "name": "New content", "prerequisite_ids": ["p1"]}+ ],+ }+ ],+ ],+)+def test_invalid_batch_is_all_or_nothing(system, edit):+ store, _ = system+ before = store.load("path").model_dump()+ with pytest.raises(ValueError):+ preview(system, edit)+ assert store.load("path").model_dump() == before+ assert store.get_active_interaction("path") is not None+++def test_exact_diff_preserves_types_null_removals_and_pointer_escaping():+ before = {"a/b~c": {"old": None, "keep": True}, "list": [1, 2]}+ after = {"a/b~c": {"new": None, "keep": 1}, "list": [1]}+ changes = exact_diff(before, after)+ assert any(c["path"] == "/a~1b~0c/keep" for c in changes)+ assert apply_diff(before, changes) == after+ assert exact_diff({"nested": [True]}, {"nested": [1]}) == [+ {+ "path": "/nested/0",+ "before_exists": True,+ "after_exists": True,+ "before": True,+ "after": 1,+ }+ ]+++async def test_runtime_preview_requires_a_later_invocation_and_preserves_legacy_schema(+ system, monkeypatch+):+ import jsonschema++ from deeptutor.agents.loop.agent_loop import AgentLoop+ from deeptutor.capabilities.mastery import tools+ from deeptutor.capabilities.mastery.loop import MasteryLoopCapability+ from deeptutor.capabilities.mastery.pipeline import MasteryLoopPipeline+ from deeptutor.core.context import UnifiedContext+ from deeptutor.runtime.stream_bus import StreamBus++ monkeypatch.setattr(tools, "_new_service", lambda: system[1])+ context = UnifiedContext(+ session_id="session",+ metadata={+ "mastery_mode": True,+ "mastery_path_id": "path",+ "mastery_session_mode": "outline",+ },+ )+ pipeline = MasteryLoopPipeline(language="en")++ async def chunks():+ yield SimpleNamespace(+ choices=[+ SimpleNamespace(+ delta=SimpleNamespace(content="Reviewed.", tool_calls=None),+ finish_reason="stop",+ )+ ],+ usage=None,+ )++ async def create(**kwargs):+ return chunks()++ engine = AgentLoop(+ pipeline=pipeline,+ context=context,+ stream=StreamBus(),+ client=SimpleNamespace(chat=SimpleNamespace(completions=SimpleNamespace(create=create))),+ enabled_tools=[],+ tool_schemas=None,+ )++ async def invoke():+ await engine._call_llm(+ messages=[{"role": "user", "content": "Review the outline."}],+ label="review",+ call_kind="agent_loop_round",+ trace_role="answer",+ max_tokens=100,+ )++ capability = MasteryLoopCapability()+ tool = MasteryReviseTool()+ schema = tool.get_definition().to_openai_schema()["function"]["parameters"]+ edits = {"action": "preview", "modules": revisions()}+ jsonschema.validate(edits, schema)+ await invoke()+ args = capability.augment_kwargs(+ tool.name,+ {**edits, "_revision_request_id": "untrusted-model-value"},+ context,+ )+ invocation = args["_revision_request_id"]+ assert invocation and invocation != "untrusted-model-value"+ result = await tool.execute(**args)+ assert result.success, result.content+ assert "mastery_revision_preview" in result.metadata+ assert "mastery_revise" not in result.metadata+ commit = {"action": "commit", "preview_id": json.loads(result.content)["preview_id"]}+ jsonschema.validate(commit, schema)+ blocked = await tool.execute(**capability.augment_kwargs(tool.name, commit, context))+ assert not blocked.success and "later model round" in blocked.content+ await invoke()+ args = capability.augment_kwargs(tool.name, commit, context)+ assert args["_revision_request_id"] != invocation+ result = await tool.execute(**args)+ assert result.success, result.content+ # Existing callers omit action and still have their original schema.+ jsonschema.validate({"modules": revisions()}, schema)+++async def test_reviewed_tool_scope_and_commit_cannot_replace_reviewed_payload(system, monkeypatch):+ from deeptutor.capabilities.mastery import tools++ monkeypatch.setattr(tools, "_new_service", lambda: system[1])+ tool = MasteryReviseTool()+ bound = {"_mastery_path_id": "path", "_session_id": "session"}+ result = await tool.execute(+ action="preview", modules=revisions(), **bound, _mastery_session_mode="study"+ )+ assert not result.success+ result = await tool.execute(+ action="preview", modules=revisions(), **bound, _mastery_session_mode="outline"+ )+ assert result.success, result.content+ preview_id = json.loads(result.content)["preview_id"]+ result = await tool.execute(+ action="commit", preview_id=preview_id, modules=revisions(), **bound+ )+ assert not result.success and "only preview_id" in result.content