DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
Merge PR #1477 mastery objective relations
Bingxi Zhao (Frank)ba7efc5dbf16
diff --cc deeptutor/api/routers/mastery_path.pyindex aa047c423,eadf23b08..ee7ff8435--- a/deeptutor/api/routers/mastery_path.py+++ b/deeptutor/api/routers/mastery_path.py@@@ -240,11 -266,46 +267,50 @@@ def _topic_sources(items: list[TopicSou]+ def _topic_source_aliases(+ items: list[TopicSourceRequest], sources: list[TopicSource]+ ) -> dict[str, str]:+ aliases: dict[str, str] = {}+ for item, source in zip(items, sources, strict=True):+ alias = item.client_ref.strip()+ if alias:+ if alias in aliases and aliases[alias] != source.id:+ raise ObjectiveRelationError(f"Source reference {alias!r} is ambiguous")+ aliases[alias] = source.id+ return aliases+++ def _module_payloads(modules: list[ModuleInput]) -> list[dict]:+ return [module.model_dump(mode="json") for module in modules]+++ def _relation_refs(+ inputs: list[ModuleInput], modules: list[LearningModule]+ ) -> dict[str, RelationRefs]:+ refs: dict[str, RelationRefs] = {}+ for input_module, module in zip(inputs, modules, strict=True):+ for input_point, point in zip(+ input_module.knowledge_points, module.knowledge_points, strict=True+ ):+ refs[point.id] = RelationRefs(+ client_ref=input_point.client_ref.strip(),+ prerequisite_refs=normalize_refs(+ [*input_point.prerequisite_refs, *input_point.prerequisite_ids],+ label="prerequisite",+ ),+ topic_source_refs=normalize_refs(+ [*input_point.topic_source_refs, *input_point.topic_source_ids],+ label="topic source",+ ),+ )+ return refs++-def _review_queue(progress) -> list[dict]:+def _review_queue(progress, *, now: float | None = None) -> list[dict]:+ from deeptutor.learning.scheduler import SpacedRepetitionScheduler, review_sort_key++ moment = time.time() if now is None else now+ scheduler = SpacedRepetitionScheduler()names = {kp.id: kp.name for module in progress.modules for kp in module.knowledge_points}return [{diff --cc deeptutor/capabilities/mastery/tools.pyindex 8e9b4e535,0dd1ab02e..c4f88659b--- a/deeptutor/capabilities/mastery/tools.py+++ b/deeptutor/capabilities/mastery/tools.py@@@ -1682,16 -1435,20 +1720,20 @@@ class MasteryBuildTool(BaseTool)if error:return ToolResult(content=error, success=False)- progress = service.replace_modules_for_path(- path_id,- new_modules,- append=mode == "append",- name=str(kwargs.get("path_name") or ""),- event_type="path.built",- session_id=_resolve_session_id(kwargs),- turn_id=_resolve_turn_id(kwargs),- identity_mode="semantic" if mode != "append" else "explicit",- )+ try:+ progress = service.replace_modules_for_path(+ path_id,+ new_modules,+ append=mode == "append",+ name=str(kwargs.get("path_name") or ""),+ event_type="path.built",+ session_id=_resolve_session_id(kwargs),+ turn_id=_resolve_turn_id(kwargs),+ relation_refs=relation_refs,- fresh_identity=mode != "append",++ identity_mode="semantic" if mode != "append" else "explicit",+ )+ except ObjectiveRelationError as exc:+ return ToolResult(content=str(exc), success=False)kp_count = sum(len(m.knowledge_points) for m in new_modules)return _json_result({@@@ -2034,14 -1824,21 +2109,22 @@@ class MasteryReviseTool(BaseTool)else module.model_copy(deep=True)for module in sorted(progress.modules, key=lambda m: m.order)]- progress = service.replace_modules_for_path(- path_id,- applied,- event_type="path.module_revised",- session_id=_resolve_session_id(kwargs),- turn_id=_resolve_turn_id(kwargs),- identity_mode="explicit",- )+ 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,+ applied,+ event_type="path.module_revised",+ session_id=_resolve_session_id(kwargs),+ turn_id=_resolve_turn_id(kwargs),++ identity_mode="explicit",+ )+ except ObjectiveRelationError as exc:+ return ToolResult(content=str(exc), success=False)return _json_result({"status": "revised",diff --cc deeptutor/learning/service.pyindex 2bc00704a,6077a49e8..09ccbd56c--- a/deeptutor/learning/service.py+++ b/deeptutor/learning/service.py@@@ -275,6 -89,85 +280,131 @@@ class LearningService"""Initialize the runnable module set (replace semantics)."""self.replace_modules(progress, modules)+ @staticmethod+ def _new_entity_id(prefix: str, reserved: set[str]) -> str:+ while True:+ candidate = f"{prefix}_{uuid.uuid4().hex[:12]}"+ if candidate not in reserved:+ reserved.add(candidate)+ return candidate+++ @staticmethod++ def _resolve_final_relations(++ applied: list[LearningModule],++ submitted: list[LearningModule],++ relation_refs: dict[str, RelationRefs],++ source_aliases: dict[str, str],++ sources: list[TopicSource],++ *,++ existing_modules: list[LearningModule] | None = None,++ ) -> None:++ """Resolve request references after durable objective IDs have been assigned."""++ aliases = {++ point.id: point.id++ for module in existing_modules or []++ for point in module.knowledge_points++ }++ final_refs: dict[str, RelationRefs] = {}++ for submitted_module, final_module in zip(submitted, applied, strict=True):++ for submitted_point, final_point in zip(++ submitted_module.knowledge_points, final_module.knowledge_points, strict=True++ ):++ # An append request may reuse a provisional ID that already belongs++ # to an existing objective. Its client_ref disambiguates the new one.++ if submitted_point.id not in aliases:++ aliases[submitted_point.id] = final_point.id++ aliases[final_point.id] = final_point.id++ specs = relation_refs.get(submitted_point.id)++ if specs is not None:++ final_refs[final_point.id] = specs++++ for final_id, specs in final_refs.items():++ alias = specs.client_ref.strip()++ if not alias:++ continue++ if alias in aliases and aliases[alias] != final_id:++ raise ObjectiveRelationError(f"Objective reference {alias!r} is ambiguous")++ aliases[alias] = final_id++++ resolve_relation_refs(++ applied,++ final_refs,++ prerequisite_aliases=aliases,++ source_aliases=source_aliases,++ sources=sources,++ )+++ @classmethod+ def _finalize_modules(+ cls,+ progress: LearningProgress,+ modules: list[LearningModule],+ *,+ append: bool,+ fresh_identity: bool,+ relation_refs: dict[str, RelationRefs],+ source_aliases: dict[str, str],+ sources: list[TopicSource],+ ) -> list[LearningModule]:+ applied = [module.model_copy(deep=True) for module in modules]+ existing_kp_ids = {+ point.id for module in progress.modules for point in module.knowledge_points+ }+ prerequisite_aliases = {key: key for key in existing_kp_ids}+ old_to_new: dict[str, str] = {}++ if append:+ offset = len(progress.modules)+ for index, module in enumerate(applied, start=offset):+ module.id = f"{progress.book_id}_m{index}"+ module.order = index+ for kp_index, point in enumerate(module.knowledge_points):+ old_id = point.id+ point.module_id = module.id+ point.id = f"{module.id}_kp{kp_index}"+ old_to_new[old_id] = point.id+ elif fresh_identity and existing_kp_ids:+ reserved_modules = set(module.id for module in progress.modules) | set(+ module.id for module in applied+ )+ reserved_points = set(existing_kp_ids) | set(+ point.id for module in applied for point in module.knowledge_points+ )+ for index, module in enumerate(applied):+ module.id = cls._new_entity_id(f"{progress.book_id}_m", reserved_modules)+ module.order = index+ for point in module.knowledge_points:+ old_id = point.id+ point.module_id = module.id+ point.id = cls._new_entity_id(f"{module.id}_kp", reserved_points)+ old_to_new[old_id] = point.id+ else:+ for module in applied:+ for point in module.knowledge_points:+ old_to_new[point.id] = point.id++ final_refs: dict[str, RelationRefs] = {}+ for module in applied:+ for point in module.knowledge_points:+ final_id = point.id+ for old_id, new_id in old_to_new.items():+ if new_id == final_id:+ specs = relation_refs.get(old_id)+ if specs is not None:+ final_refs[final_id] = specs+ if specs.client_ref:+ prerequisite_aliases[specs.client_ref] = final_id+ break++ resolve_relation_refs(+ applied,+ final_refs,+ prerequisite_aliases=prerequisite_aliases,+ source_aliases=source_aliases,+ sources=sources,+ )+ return applied+def replace_modules(self, progress: LearningProgress, modules: list[LearningModule]) -> None:"""Replace all modules and clean stale KP state."""new_kp_ids = {kp.id for m in modules for kp in m.knowledge_points}@@@ -937,7 -748,10 +1067,11 @@@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,) -> LearningProgress:"""Install a module set, optionally naming a path that has no name yet.@@@ -955,32 -765,22 +1089,45 @@@def replace(tx):if name.strip() and not tx.progress.name.strip():tx.progress.name = name.strip()[:_MAX_PATH_NAME_LEN]- sources = tx.topic_sources() if topic_sources is None else topic_sources- applied_modules = self._finalize_modules(- tx.progress,- modules,- append=append,- fresh_identity=fresh_identity,- relation_refs=relation_refs or {},- source_aliases=source_aliases or {},- sources=sources,- )+ applied_modules = [module.model_copy(deep=True) for module in modules]+ identity_map: dict[str, list[str] | str] = {- "mode": "append" if append else identity_mode,++ "mode": "append" if append else ("fresh" if fresh_identity else identity_mode),+ "preserved": [],+ "minted": [],+ "dropped": [],+ }if append:- validate_objective_relations([*tx.progress.modules, *applied_modules], sources)- tx.progress.modules.extend(applied_modules)- for module in applied_modules:- for kp in module.knowledge_points:+ 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)- tx.progress.modules.extend(applied_modules)+ 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].idtx.progress.current_kp_index = 0@@@ -1006,11 -806,7 +1153,33 @@@else "")- identity_map = assign_objective_identities(- tx.progress,++ 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(+ applied_modules,- identity_mode=identity_mode,++ 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)