Skip to content

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

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.py
index 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.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 --git a/deeptutor/capabilities/mastery/loop.py b/deeptutor/capabilities/mastery/loop.py
index 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.yaml
index 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.yaml
index 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.py
index 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.py
new file mode 100644
index 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.py
index 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 = 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)
- 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, receipt
def create_topic(
self,
diff --git a/deeptutor/learning/storage.py b/deeptutor/learning/storage.py
index 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,
+ }
+
@staticmethod
def _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.py
new file mode 100644
index 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