DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
feat(mastery): support independently graded question groups
yepyhunc3301c005585
diff --git a/deeptutor/capabilities/mastery/loop.py b/deeptutor/capabilities/mastery/loop.pyindex cfc870c0f..755de52e8 100644--- a/deeptutor/capabilities/mastery/loop.py+++ b/deeptutor/capabilities/mastery/loop.py@@ -50,6 +50,18 @@ _PLAIN_QUIZ_PROMPT_RE = re.compile(r"\b(?:which|choose|select|answer)\b|选择|选哪个|请选择|请回答|答案",re.IGNORECASE,)+# Defense in depth for explicit numbered assessments. Merely asking questions+# while explaining is valid; require both answer/assessment intent and multiple+# numbered question stems. This fallback does not replace registered groups.+_MULTIPART_INTENT_RE = re.compile(+ r"\b(?:answer these|practice questions|will grade (?:both|your|the) answers)\b|"+ r"\b(?:válaszolj|gyakorló kérdés|ellenőrző kérdés)\w*\b|"+ r"请回答|回答下面|练习题|检查题",+ re.IGNORECASE,+)+_NUMBERED_QUESTION_RE = re.compile(+ r"^\s*(?:\*\*)?\d{1,2}[.)、](?:\*\*)?\s+[^\n]*[??]", re.MULTILINE+)# A reply that announces a question without posing one. Matched against the# tail of the reply only, where an announcement lands, so ordinary discussion# of "this question" while reviewing an attempt does not trip it.@@ -147,6 +159,13 @@ def _looks_like_plain_choice_quiz(text: str) -> bool:return len(labels) >= 3 and any(_PLAIN_QUIZ_PROMPT_RE.search(line) for line in prompt_lines)+def _looks_like_multipart_assessment(text: str) -> bool:+ prose = _QUOTED_CARD_TEXT_RE.sub(" ", text)+ return (+ bool(_MULTIPART_INTENT_RE.search(prose)) and len(_NUMBERED_QUESTION_RE.findall(prose)) >= 2+ )++def _turn_has_graded(context: UnifiedContext) -> bool:"""Whether a ruling was made this turn, by the model or by the runtime.@@ -277,6 +296,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_quiz":+ # A replacement needs a quote from the actual current learner+ # request, not a model-supplied claim about their intention.+ updated["_learner_message"] = context.user_message 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``@@ -360,6 +383,17 @@ class MasteryLoopCapability:"you did not mean to quiz them yet, say what you meant to say ""without announcing a question.")+ if not state.get("card_posted") and _looks_like_multipart_assessment(final_text):+ return (+ "That reply presented a new numbered assessment as unregistered prose. "+ "For memory/procedure practice, call mastery_quiz with a questions group "+ "so each answer has its own stored contract and result. If an older question "+ "is pending, preserve it unless the learner explicitly requested replacement; "+ "then use its current question ID and a literal replacement_request quote. "+ "Do not concatenate expected answers or claim that a prose list is a card. "+ "If this is teaching rather than assessment, explain directly without "+ "instructing the learner to answer an unregistered practice set."+ )if _turn_has_graded(context) or not _looks_like_plain_choice_quiz(final_text):return Noneif state.get("quiz_awaiting_grade"):@@ -517,6 +551,23 @@ class MasteryLoopCapability:if not isinstance(grade, dict) or not grade:return ""result = grade.get("result") if isinstance(grade.get("result"), dict) else {}+ results = result.get("results")+ if isinstance(results, list) and results:+ parts = [+ f"{item.get('question_id', '')}: "+ f"{'ungraded' if item.get('is_correct') is None else ('correct' if item.get('is_correct') else 'incorrect')}; "+ f"objective {item.get('knowledge_point_id', '')}; "+ f"mastered={bool(item.get('mastered'))}"+ for item in results+ if isinstance(item, dict)+ ]+ return (+ "[Mastery] The question group was already graded by the engine. "+ "Do not grade it again or repeat its answer keys. Each result belongs "+ "only to its own objective; the parent group gives no extra credit. "+ "Address the specific gap, then use the fresh status for the next step.\n"+ + "\n".join(parts)+ )verdict = "correct" if grade.get("is_correct") else "incorrect"learner_answer = str(result.get("learner_answer") or "").strip()lines = [diff --git a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yamlindex 519021a8d..a7521f3fb 100644--- a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml+++ b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml@@ -86,6 +86,8 @@ session:# Teaching strategy. Kept separate from the loop protocol above: that one says# how a round runs, this one says what to do about the objective in front of you.playbook: |-+ **Registered grouped practice:** When the learner requests questions together, use `mastery_quiz.questions` for a bounded group of two to four separately answerable memory/procedure questions. Each item must name a real objective and carry its own supported question and private answer contract; do not concatenate expected answers or pose official numbered assessments in prose. A group is one active interaction with separate results, not extra mastery credit. If an unrelated older question is still pending, explain that briefly. Replace it only for an explicit current learner request, using `pending_action: replace`, the fresh `replace_question_id`, and `replacement_request` as a literal quote from that request. Otherwise retain it. Never infer abandonment from silence or a pacing preference. Do not call the single-question tool twice and promise two cards. Unsupported objective types still use their native qualitative assessment path.+ **Concise but explanatory:** Do not replace teaching with a list of names, priority labels or compressed definitions. At the learner's requested level, explain the necessary meaning and one useful connection or concrete example before assessing it. After feedback that an explanation was too terse, supply the missing link rather than another equally compressed formulation. Split useful teaching into connected steps when needed; there is no fixed word quota or compulsory question after each step.**Source-grounded visual study:** Honor explanation, practice and review as explicit learner choices; explain untaught prerequisites at the requested level before assessment. Use `mastery_note_explained` after an explanation; this records coverage without mastery credit. An outline is never evidence of teaching. A concise explanation-only turn may end without a quiz; explicit deferral uses `mastery_defer_objective` and does not claim mastery.When the goal includes figure understanding, declare the relevant objective's `required_visual_tasks` in the outline (`identification`, `relationship`, `table_graph`, `comparison`). Generic text scores do not satisfy these. Read `mastery_status.visual_requirements` and `learning_stages`; explain whether the next work addresses missing independent evidence, prior difficulty or due review.Retrieve and inspect the original pixels with `rag` before a visual question. Pass `visual` to `mastery_quiz`, using exact source references and a supported reference quote, plus verified equivalent terminology (including the learner's language). Ask about the actual numbered label, visible relationship, plotted/table values or supported comparison. Preserve the original and source location; do not replace it with a generated diagram or invent a masked/segmented target. A key based only on uncertain pixel interpretation stays `unverified` and ungraded.@@ -118,7 +120,7 @@ playbook: |-**Design each question once.** Settle the stem, the options and the correct label, then pose it. Do not keep revising a question you had already settled — if one distractor turns out to be arguable, replace that distractor, not the whole question. A question that discriminates adequately and is actually posed teaches more than a perfect one you are still rewriting, and the threshold is reached across many questions rather than by any single one.- **Anything you intend to grade goes through `mastery_quiz`** — never as 1./2./3. in the body, and never through `ask_user`, which here is only for genuine clarification (such as "which chapter would you like to start from").+ **Registered memory/procedure assessment goes through `mastery_quiz`** — use its `questions` group for separate answers, never 1./2./3. in the body and never `ask_user`, which here is only for genuine clarification. Concept/design explanations are assessed through `mastery_assess` as described above; do not misrepresent an unsupported qualitative group as a registered quiz.**Materials**: what the learner chose for this topic arrives as a `[Topic Materials]` manifest, and you can read any of it on demand with `read_source`. Teach from those rather than from memory. You cannot read rows marked `unavailable`: never describe or quote their contents; say plainly that the material is not readable and continue with what is. When the learner asks whether you can see their materials, answer from the manifest and name what you actually have — never a blanket "yes, I can see it".diff --git a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yamlindex 8ffcb6a95..d0e7397d6 100644--- a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml+++ b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml@@ -83,6 +83,8 @@ session:# 教学策略。与 loop 协议分开:上面说的是「一轮怎么走」,这里说的是「针对这个知识点做什么」。playbook: |-+ **已登记的组合练习**:学习者要求一起回答问题时,用 `mastery_quiz.questions` 建立二至四题的有界组合;每题独立作答,只用于 memory/procedure 知识点。每题必须指向真实知识点并保存自己的、有来源支持的题目与私密答案契约;不能把答案拼接后一起模糊判分,也不能把正式编号考核写在正文里。组合只有一个活跃交互,但结果分别归属各题,不额外授予掌握分。若仍有不相关的旧待答题,简短说明;只有学习者当前明确要求替换时,才用 `pending_action: replace`、最新 `replace_question_id` 和当前请求的逐字引用 `replacement_request` 替换,否则保留。沉默或节奏偏好不是放弃旧题的证据。不要连续调用单题工具后承诺两张卡片;不支持的知识点类型仍走原有定性考核流程。+ **简洁但讲清楚**:不要用名称列表、重要性标签或压缩定义代替教学。按学习者需要的深度,先讲必要的含义以及一个有用联系或具体例子,再考核。学习者说解释太简略时,补上缺失的联系,不要换成同样简略的说法。需要时把教学拆成连贯小步;没有固定字数配额,也不要求每一步之后都出题。**来源扎实的视觉学习:** 尊重学习者明确选择的讲解、练习或复习,按要求的层次先解释必要前置知识。讲解后调用 `mastery_note_explained`,只记录已讲解覆盖,不授予掌握分;生成提纲不等于教学。仅需简洁讲解时可以不出题;明确暂缓用 `mastery_defer_objective`,不能假称已掌握。目标包含原图理解时,在对应提纲目标声明 `required_visual_tasks`(identification、relationship、table_graph、comparison)。通用文字题高分不能替代这些任务。查看 `mastery_status.visual_requirements` 和 `learning_stages`,解释下一步来自缺少独立证据、此前困难还是到期复习。视觉题先通过 `rag` 读取并检查原始像素,再给 `mastery_quiz` 传 `visual`:精确来源、来源中的参考引文以及已核验的等价术语(包含学习者语言)。练习应判断真实编号标签、可见关系、图表数据或有证据支持的比较。保留原图及位置,不能用生成图替代,也不能虚构遮罩或分割目标。仅凭不确定图像理解得到的答案键标为 unverified,保留未评分。diff --git a/deeptutor/capabilities/mastery/tools.py b/deeptutor/capabilities/mastery/tools.pyindex d988ccaf0..7fec6fc57 100644--- a/deeptutor/capabilities/mastery/tools.py+++ b/deeptutor/capabilities/mastery/tools.py@@ -886,7 +886,7 @@ class MasteryQuizTool(BaseTool):"""Register an objective-type question; the engine holds the answer."""def get_definition(self) -> ToolDefinition:- return ToolDefinition(+ definition = ToolDefinition(name="mastery_quiz",description=("Pose a question for a MEMORY or PROCEDURE objective. This one "@@ -1005,6 +1005,52 @@ class MasteryQuizTool(BaseTool):),],)+ leaf_parameters = {p.name: p.to_schema() for p in definition.parameters}+ for parameter in definition.parameters:+ if parameter.name in {"knowledge_point_id", "question", "expected_answer"}:+ parameter.required = False+ definition.description += (+ " For several separately graded questions use questions (two to four single-question "+ "objects) in ONE call, not prose or repeated calls. One parent ends the turn. "+ "A pending item is retained unless the learner explicitly requests replacement."+ )+ definition.parameters.extend(+ [+ ToolParameter(+ name="questions",+ type="array",+ required=False,+ sensitive=True,+ description="Two to four independently answered single-question contracts. Do not concatenate answer keys.",+ items={+ "type": "object",+ "properties": leaf_parameters,+ "required": ["knowledge_point_id", "question", "expected_answer"],+ "additionalProperties": False,+ },+ ),+ ToolParameter(+ name="pending_action",+ type="string",+ required=False,+ enum=["retain", "replace"],+ description="Retain existing pending question by default; replace only on an explicit learner request.",+ ),+ ToolParameter(+ name="replace_question_id",+ type="string",+ required=False,+ description="Exact currently pending parent question_id when replacing; a stale id cannot retire a newer card.",+ ),+ ToolParameter(+ name="replacement_request",+ type="string",+ required=False,+ description="Literal quote from the current learner message requesting replacement, not a paraphrase.",+ ),+ ]+ )+ return definitionasync def execute(self, **kwargs: Any) -> ToolResult:refusal = _wrong_mode_result("mastery_quiz", kwargs)@@ -1013,88 +1059,86 @@ class MasteryQuizTool(BaseTool):path_id = _resolve_path_id(kwargs)if not path_id:return _no_path_result()- kp_id = str(kwargs.get("knowledge_point_id") or "").strip()- question = str(kwargs.get("question") or "").strip()- expected = str(kwargs.get("expected_answer") or "").strip()- if not kp_id or not question or not expected:- return ToolResult(- content="mastery_quiz needs knowledge_point_id, question, and expected_answer.",- success=False,- )- try:- q_type, options, expected = _normalize_quiz_contract(- kwargs.get("question_type"), kwargs.get("options"), expected- )- except ValueError as exc:- return ToolResult(content=str(exc), success=False)-- question, echoed_options = strip_echoed_options(- question, {option["label"]: option["body"] for option in options}- )-- if q_type == "choice":- options, expected = _shuffle_choice_options(options, expected, random.Random())-service = _new_service()progress = _load_path(service, path_id)if progress is None:return _no_built_path_result("mastery_quiz")- scope = _review_scope_refusal(kwargs, progress, kp_id)- if scope is not None:- return scope- kp, module_id, _ = find_knowledge_point(progress, kp_id)- if kp is None:- return ToolResult(- content=f"Unknown objective {kp_id!r}; call mastery_status for valid ids.",- success=False,- )- visual_context: dict[str, Any] = {}- accepted_answers: list[str] = []- if kwargs.get("visual") is not None:- from deeptutor.learning.visual_practice import prepare_visual-- if not isinstance(kwargs["visual"], dict):+ pending_action = kwargs.get("pending_action", "retain")+ if pending_action == "replace":+ request = kwargs.get("replacement_request")+ learner_message = kwargs.get("_learner_message")+ if (+ not isinstance(request, str)+ or not request.strip()+ or not isinstance(learner_message, str)+ or request not in learner_message+ ):return ToolResult(- content="visual must be an object with exact source references.", success=False- )- try:- visual_context, accepted_answers = await asyncio.to_thread(- prepare_visual,- kwargs["visual"],- expected_answer=expected,- options={option["label"]: option["body"] for option in options},- attached_kbs=kwargs.get("_attached_kb_names"),- inspected_image_hashes=kwargs.get("_inspected_image_hashes", []),- )- from deeptutor.learning.visual_practice import account_for_recent_assistance-- visual_context = account_for_recent_assistance(- visual_context, progress.quiz_attempts, kp_id+ content="Replacement needs a literal request from the current learner message.",+ success=False,)- except (OSError, ValueError, TypeError) as exc:+ raw_questions = kwargs.get("questions")+ if raw_questions is None:+ built = await self._build_question(kwargs, progress)+ if isinstance(built, ToolResult):+ return built+ pending, echoed_options, kp = built+ else:+ if not isinstance(raw_questions, list) or not 2 <= len(raw_questions) <= 4:return ToolResult(- content=f"Visual practice is unavailable: {exc}. Inspect/clarify the source; no assessment was created.",+ content="questions must contain two to four independent questions.",success=False,)- pending = PendingQuestion(- question_id=uuid.uuid4().hex,- knowledge_point_id=kp_id,- module_id=module_id,- prompt=question,- question_type=q_type,- expected_answer=expected,- options=options,- explanation=str(kwargs.get("explanation") or "").strip()[:2000],- difficulty=_normalize_difficulty(kwargs.get("difficulty")),- visual_context=visual_context,- accepted_answers=accepted_answers,- )+ fields = {+ "knowledge_point_id",+ "question",+ "expected_answer",+ "question_type",+ "options",+ "explanation",+ "difficulty",+ "visual",+ }+ leaves = []+ echoed_options = False+ for raw in raw_questions:+ if (+ not isinstance(raw, dict)+ or set(raw) - fields+ or not {"knowledge_point_id", "question", "expected_answer"} <= set(raw)+ ):+ return ToolResult(+ content="Group leaves must use the single-question contract, without nested groups.",+ success=False,+ )+ built = await self._build_question(+ {**{key: value for key, value in kwargs.items() if key.startswith("_")}, **raw},+ progress,+ )+ if isinstance(built, ToolResult):+ return built+ question, echoed, kp = built+ leaves.append(question)+ echoed_options = echoed_options or echoed+ try:+ pending = PendingQuestion(+ question_id=uuid.uuid4().hex,+ knowledge_point_id=leaves[0].knowledge_point_id,+ module_id=leaves[0].module_id,+ prompt=str(kwargs.get("question") or ""),+ question_type="group",+ questions=leaves,+ )+ except ValueError as exc:+ return ToolResult(content=str(exc), success=False)from deeptutor.learning.service import MasteryInteractionErrortry:progress, interaction, created = service.register_question(path_id,pending,+ pending_action=pending_action,+ replace_question_id=str(kwargs.get("replace_question_id") or ""),session_id=_resolve_session_id(kwargs),turn_id=_resolve_turn_id(kwargs),)@@ -1104,9 +1148,14 @@ class MasteryQuizTool(BaseTool):public_question = public_pending_question(pending)card = build_question_card(pending,- objective_name=kp.name,+ objective_name=kp.name if not pending.questions else "",attempt=attempt_number(progress, pending.knowledge_point_id),)+ if pending.questions:+ for leaf_card, leaf in zip(card["questions"], pending.questions, strict=True):+ objective, _, _ = find_knowledge_point(progress, leaf.knowledge_point_id)+ leaf_card["objective"]["name"] = objective.name if objective else ""+ leaf_card["attempt"] = attempt_number(progress, leaf.knowledge_point_id)# The card is now the learner's to answer, which is the same commit the# old pause hook made before parking the turn.await asyncio.to_thread(@@ -1161,7 +1210,7 @@ class MasteryQuizTool(BaseTool):"button. That list was removed from the stem. Pass the ask in ""'question' and the choices only in 'options'.")- if kp.type in QUALITATIVE_TYPES:+ if not pending.questions and kp.type in QUALITATIVE_TYPES:# The mirror of ``record_qualitative_for_path``, which refuses# outright when mastery_assess is aimed at a quantitative# objective. This direction stays allowed — a question is a fair@@ -1181,6 +1230,81 @@ class MasteryQuizTool(BaseTool):metadata={"mastery_quiz": payload, QUESTION_CARD_KEY: card},)+ async def _build_question(self, kwargs, progress):+ kp_id = str(kwargs.get("knowledge_point_id") or "").strip()+ question = str(kwargs.get("question") or "").strip()+ expected = str(kwargs.get("expected_answer") or "").strip()+ if not kp_id or not question or not expected:+ return ToolResult(+ content="mastery_quiz needs knowledge_point_id, question, and expected_answer.",+ success=False,+ )+ try:+ q_type, options, expected = _normalize_quiz_contract(+ kwargs.get("question_type"), kwargs.get("options"), expected+ )+ except ValueError as exc:+ return ToolResult(content=str(exc), success=False)++ question, echoed_options = strip_echoed_options(+ question, {option["label"]: option["body"] for option in options}+ )++ if q_type == "choice":+ options, expected = _shuffle_choice_options(options, expected, random.Random())++ scope = _review_scope_refusal(kwargs, progress, kp_id)+ if scope is not None:+ return scope+ kp, module_id, _ = find_knowledge_point(progress, kp_id)+ if kp is None:+ return ToolResult(+ content=f"Unknown objective {kp_id!r}; call mastery_status for valid ids.",+ success=False,+ )+ visual_context: dict[str, Any] = {}+ accepted_answers: list[str] = []+ if kwargs.get("visual") is not None:+ from deeptutor.learning.visual_practice import prepare_visual++ if not isinstance(kwargs["visual"], dict):+ return ToolResult(+ content="visual must be an object with exact source references.", success=False+ )+ try:+ visual_context, accepted_answers = await asyncio.to_thread(+ prepare_visual,+ kwargs["visual"],+ expected_answer=expected,+ options={option["label"]: option["body"] for option in options},+ attached_kbs=kwargs.get("_attached_kb_names"),+ inspected_image_hashes=kwargs.get("_inspected_image_hashes", []),+ )+ from deeptutor.learning.visual_practice import account_for_recent_assistance++ visual_context = account_for_recent_assistance(+ visual_context, progress.quiz_attempts, kp_id+ )+ except (OSError, ValueError, TypeError) as exc:+ return ToolResult(+ content=f"Visual practice is unavailable: {exc}. Inspect/clarify the source; no assessment was created.",+ success=False,+ )+ pending = PendingQuestion(+ question_id=uuid.uuid4().hex,+ knowledge_point_id=kp_id,+ module_id=module_id,+ prompt=question,+ question_type=q_type,+ expected_answer=expected,+ options=options,+ explanation=str(kwargs.get("explanation") or "").strip()[:2000],+ difficulty=_normalize_difficulty(kwargs.get("difficulty")),+ visual_context=visual_context,+ accepted_answers=accepted_answers,+ )+ return pending, echoed_options, kp+class MasteryGradeTool(BaseTool):"""Grade the learner's answer to the pending question (deterministic)."""@@ -1200,6 +1324,13 @@ class MasteryGradeTool(BaseTool):name="answer",type="string",description="The learner's answer, verbatim.",+ required=False,+ ),+ ToolParameter(+ name="answers",+ type="object",+ required=False,+ description="For a group only: exact child question_id to learner answer strings. Use committed replies verbatim; never one concatenated answer.",),ToolParameter(name="question_id",@@ -1252,6 +1383,8 @@ class MasteryGradeTool(BaseTool):pending = (interaction.question if interaction is not None else progress_before.pending_question)+ if pending is not None and pending.questions:+ return await self._grade_group(kwargs, service, scheduler, pending)choice_options: dict[str, str] = {}expected_answer = pending.expected_answer if pending is not None else ""answer_for_grading = answer@@ -1417,6 +1550,77 @@ class MasteryGradeTool(BaseTool):}return _json_result(payload, meta_key="mastery_grade")+ async def _grade_group(self, kwargs, service, scheduler, pending) -> ToolResult:+ from deeptutor.learning.service import MasteryInteractionError++ path_id = _resolve_path_id(kwargs)+ try:+ progress, interaction, replayed = service.grade_interaction(+ path_id,+ answer="",+ question_id=str(kwargs.get("question_id") or pending.question_id),+ answers=kwargs.get("answers"),+ scheduler=scheduler,+ session_id=_resolve_session_id(kwargs),+ turn_id=_resolve_turn_id(kwargs),+ )+ except MasteryInteractionError as exc:+ return ToolResult(content=str(exc), success=False)+ group_result = dict(interaction.result)+ group_result["results"] = [dict(result) for result in group_result["results"]]+ for leaf, result in zip(+ interaction.question.questions, group_result["results"], strict=True+ ):+ kp, _, _ = find_knowledge_point(progress, leaf.knowledge_point_id)+ evidence = next(+ (+ item+ for item in reversed(progress.learning_evidence)+ if item.question_id == leaf.question_id+ ),+ None,+ )+ # Repair auxiliary history on replays as well, using committed data.+ if result["is_correct"] is not None:+ await _sync_mastery_attempt_to_question_bank(+ path_id=path_id,+ session_id=interaction.session_id,+ turn_id=interaction.turn_id,+ pending=leaf,+ user_answer=interaction.answers[leaf.question_id],+ is_correct=result["is_correct"],+ choice_options=leaf.choice_map,+ correct_answer=leaf.expected_answer,+ material_title=progress.name,+ section_title=kp.name if kp else "",+ attempt_count=evidence.attempt_count if evidence else 1,+ hints_used=evidence.hints_used if evidence else 0,+ confidence=evidence.confidence if evidence else None,+ response_time=evidence.response_time if evidence else None,+ quality=evidence.quality if evidence else None,+ result=str(result.get("result") or ""),+ )+ result.update(+ {+ "mastery": round(display_mastery(progress, kp), 3) if kp else 0,+ "gate": gate_kind(kp) if kp else "",+ "mastered": bool(kp and is_mastered(progress, kp)),+ }+ )+ return _json_result(+ {+ "question_id": pending.question_id,+ "question_type": "group",+ "is_correct": group_result["is_correct"],+ "replayed": replayed,+ "path_revision": progress.version,+ "result": group_result,+ "next": next_objective(progress).to_dict(),+ "instruction": "Give concise, explanatory feedback per question. Mixed results remain separate; the parent grants no extra mastery. Keep qualitative assessment gates and adapt subsequent teaching to the learner's needs.",+ },+ meta_key="mastery_grade",+ )+class MasteryAssessTool(BaseTool):"""Record the qualitative (CONCEPT / DESIGN) gate from a Feynman check."""diff --git a/deeptutor/core/turn_request.py b/deeptutor/core/turn_request.pyindex af1f95582..a9cc807f5 100644--- a/deeptutor/core/turn_request.py+++ b/deeptutor/core/turn_request.py@@ -5,7 +5,7 @@ from __future__ import annotationsfrom typing import Any, Literalimport warnings-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator+from pydantic import BaseModel, ConfigDict, Field, StrictStr, field_validator, model_validatorfrom deeptutor.core.response_languages import validate_reply_language_override@@ -91,6 +91,18 @@ class MasteryCardAnswer(BaseModel):question_id: str = Field(min_length=1)text: str = Field(min_length=1)+ answers: dict[str, StrictStr] | None = Field(default=None, min_length=2, max_length=4)++ @field_validator("answers")+ @classmethod+ def validate_group_answers(cls, value: dict[str, str] | None) -> dict[str, str] | None:+ if value is not None:+ for question_id, answer in value.items():+ if not question_id.strip() or len(question_id) > 200:+ raise ValueError("group answers require bounded nonempty question IDs")+ if not answer.strip() or len(answer) > 8000:+ raise ValueError("group answers require bounded nonempty answer text")+ return valueclass MasteryCardSkip(BaseModel):diff --git a/deeptutor/learning/models.py b/deeptutor/learning/models.pyindex 7a1b71961..0167a5677 100644--- a/deeptutor/learning/models.py+++ b/deeptutor/learning/models.py@@ -4,7 +4,7 @@ from enum import Enumimport timefrom typing import Any, Literal-from pydantic import BaseModel, ConfigDict, Field, field_validator+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator_KNOWLEDGE_TYPE_LEGACY: dict[str, str] = {"记忆型": "memory",@@ -275,6 +275,38 @@ class PendingQuestion(BaseModel):created_at: float = Field(default_factory=time.time)visual_context: dict[str, Any] = Field(default_factory=dict)accepted_answers: list[str] = Field(default_factory=list)+ # One active interaction can present multiple independent questions. The+ # parent owns lifecycle only; answer keys and credit remain on its leaves.+ questions: list[PendingQuestion] = Field(default_factory=list)++ @model_validator(mode="after")+ def _validate_group(self) -> PendingQuestion:+ if self.question_type != "group":+ if self.questions:+ raise ValueError("Only a group may contain questions")+ return self+ if not 2 <= len(self.questions) <= 4:+ raise ValueError("A question group needs two to four questions")+ ids = [q.question_id for q in self.questions]+ if len(set(ids)) != len(ids) or self.question_id in ids or not all(ids):+ raise ValueError("Group question ids must be distinct and nonempty")+ question_keys = {(q.knowledge_point_id, q.prompt.strip()) for q in self.questions}+ if len(question_keys) != len(self.questions):+ raise ValueError(+ "A group needs distinct questions, not copies of the same objective prompt"+ )+ if any(+ q.question_type not in {"choice", "short", "open"}+ or q.questions+ or not q.expected_answer.strip()+ or not q.prompt.strip()+ or not q.knowledge_point_id.strip()+ for q in self.questions+ ):+ raise ValueError("Group leaves need independent, non-nested answer contracts")+ if self.expected_answer or self.options or self.visual_context:+ raise ValueError("A group parent cannot carry an answer key or visual task")+ return self@field_validator("options", mode="before")@classmethod@@ -327,6 +359,7 @@ class MasteryInteraction(BaseModel):session_id: str = ""turn_id: str = ""user_answer: str = ""+ answers: dict[str, str] = Field(default_factory=dict)result: dict[str, Any] = Field(default_factory=dict)created_at: float = Field(default_factory=time.time)updated_at: float = Field(default_factory=time.time)diff --git a/deeptutor/learning/pending.py b/deeptutor/learning/pending.pyindex 2179adf69..362ba5b33 100644--- a/deeptutor/learning/pending.py+++ b/deeptutor/learning/pending.py@@ -232,14 +232,18 @@ class PublicPendingQuestion:prompt: strquestion_type: stroptions: tuple[PublicPendingOption, ...] = ()+ questions: tuple[PublicPendingQuestion, ...] = ()def to_dict(self) -> dict[str, Any]:- return {+ result = {"question_id": self.question_id,"prompt": self.prompt,"question_type": self.question_type,"options": [option.to_dict() for option in self.options],}+ if self.questions:+ result["questions"] = [question.to_dict() for question in self.questions]+ return resultdef public_pending_question(pending: PendingQuestion) -> PublicPendingQuestion:@@ -256,6 +260,7 @@ def public_pending_question(pending: PendingQuestion) -> PublicPendingQuestion:question_id=pending.question_id,prompt=decode_escaped_unicode_for_display(pending.prompt),question_type=pending.question_type,+ questions=tuple(public_pending_question(q) for q in pending.questions),options=tuple(PublicPendingOption(id=option.id,diff --git a/deeptutor/learning/question_card.py b/deeptutor/learning/question_card.pyindex 7afc0ad2c..1544cab36 100644--- a/deeptutor/learning/question_card.py+++ b/deeptutor/learning/question_card.py@@ -85,6 +85,8 @@ def build_question_card(}if pending.visual_context:payload["visual"] = public_visual(pending.visual_context)+ if pending.questions:+ payload["questions"] = [build_question_card(q) for q in pending.questions]return payloaddiff --git a/deeptutor/learning/service.py b/deeptutor/learning/service.pyindex e5bd1d3f9..5ffd57eda 100644--- a/deeptutor/learning/service.py+++ b/deeptutor/learning/service.py@@ -656,6 +656,8 @@ class LearningService:book_id: str,pending: PendingQuestion,*,+ pending_action: str = "retain",+ replace_question_id: str = "",session_id: str = "",turn_id: str = "",) -> tuple[LearningProgress, MasteryInteraction, bool]:@@ -665,6 +667,9 @@ class LearningService:existing interaction instead of overwriting its expected answer."""+ if pending_action not in {"retain", "replace"}:+ raise MasteryInteractionError("pending_action must be retain or replace")+def register(tx):active = tx.active_interaction()if active is None:@@ -686,21 +691,45 @@ class LearningService:active = persistedelse:tx.put_interaction(active)- if active is not None:+ if active is not None and pending_action == "retain":+ if bool(pending.questions) != bool(active.question.questions):+ raise MasteryInteractionError(+ "An incompatible question is already pending; retain it or explicitly "+ "replace its question_id before creating a group"+ )+ if pending.questions and self._group_contract(pending) != self._group_contract(+ active.question+ ):+ raise MasteryInteractionError(+ "A different group is already pending; explicitly replace its question_id"+ )return active, False+ if pending_action == "replace" and (+ active is None or active.interaction_id != replace_question_id+ ):+ raise StaleInteractionError(+ replace_question_id, active.interaction_id if active else ""+ )- known_kp = next(- (- kp- for module in tx.progress.modules- for kp in module.knowledge_points- if kp.id == pending.knowledge_point_id- ),- None,- )- if known_kp is None:- raise MasteryInteractionError(- f"Unknown objective {pending.knowledge_point_id!r}; refresh mastery_status"+ leaves = pending.questions or [pending]+ known_ids = {kp.id for module in tx.progress.modules for kp in module.knowledge_points}+ for question in leaves:+ if question.knowledge_point_id not in known_ids:+ raise MasteryInteractionError(+ f"Unknown objective {question.knowledge_point_id!r}; refresh mastery_status"+ )+ if active is not None:+ active.status = InteractionStatus.ABANDONED+ tx.put_interaction(active)+ tx.emit(+ "interaction.abandoned",+ {+ "interaction_id": active.interaction_id,+ "reason": "explicit_replacement",+ "replacement_id": pending.question_id,+ },+ session_id=session_id,+ turn_id=turn_id,)interaction = MasteryInteraction(@@ -712,7 +741,8 @@ class LearningService:turn_id=turn_id,)tx.progress.pending_question = pending- tx.progress.deferred_objectives.pop(pending.knowledge_point_id, None)+ for question in leaves:+ tx.progress.deferred_objectives.pop(question.knowledge_point_id, None)tx.put_interaction(interaction)from deeptutor.learning.pending import public_pending_question@@ -778,6 +808,7 @@ class LearningService:book_id: str,answer: str,*,+ answers: dict[str, str] | None = None,interaction_id: str = "",session_id: str = "",turn_id: str = "",@@ -799,6 +830,17 @@ class LearningService:return Noneif interaction_id and interaction.interaction_id != interaction_id:raise StaleInteractionError(interaction_id, interaction.interaction_id)+ if interaction.question.questions:+ submitted = self._validate_group_answers(interaction.question, answers)+ if interaction.status in {InteractionStatus.ANSWERED, InteractionStatus.GRADED}:+ if interaction.answers != submitted:+ raise MasteryInteractionError(+ "This group already has a different committed answer"+ )+ return interaction+ if interaction.status == InteractionStatus.ABANDONED:+ raise NoPendingInteractionError("The question was abandoned")+ interaction.answers = submittedif interaction.status in {InteractionStatus.REGISTERED,InteractionStatus.AWAITING_INPUT,@@ -849,6 +891,7 @@ class LearningService:*,answer: str,question_id: str = "",+ answers: dict[str, str] | None = None,answer_for_grading: str | None = None,expected_answer: str | None = None,resolved_choice_options: dict[str, str] | None = None,@@ -882,99 +925,38 @@ class LearningService:if question_id and interaction.interaction_id != question_id:raise StaleInteractionError(question_id, interaction.interaction_id)if interaction.status == InteractionStatus.GRADED:+ if interaction.question.questions and answers is not None:+ submitted = self._validate_group_answers(interaction.question, answers)+ if submitted != interaction.answers:+ raise MasteryInteractionError(+ "This group already has a different committed answer"+ )return interaction, Trueif interaction.status == InteractionStatus.ABANDONED:raise NoPendingInteractionError("The question was abandoned")- pending = interaction.question- raw_answer = str(answer or "")- if interaction.status == InteractionStatus.ANSWERED:- stored = str(interaction.user_answer or "")- if pending.question_type == "choice":- from deeptutor.learning.pending import (- has_option_bodies,- is_readable_choice_answer,- resolve_choice_submission,- )-- option_map = pending.choice_map- if is_readable_choice_answer(stored, option_map):- raw_answer = stored- elif is_readable_choice_answer(raw_answer, option_map):- # Prior commit was unreadable clarifying text (#1004) —- # accept the fresh readable answer and rewrite storage.- interaction.user_answer = raw_answer- else:- raw_answer = stored- if has_option_bodies(option_map):- graded_answer = (- resolve_choice_submission(raw_answer, option_map) or raw_answer- )- else:- # Legacy questions may need option bodies recovered by- # the trusted tool adapter from the original turn.- graded_answer = (- raw_answer if answer_for_grading is None else answer_for_grading- )- else:- raw_answer = stored- graded_answer = raw_answer- else:- graded_answer = raw_answer if answer_for_grading is None else answer_for_grading- authoritative_answer = (- pending.expected_answer if expected_answer is None else expected_answer- )- if pending.question_type == "choice" and resolved_choice_options:- # Bodies recovered for a legacy question (see the tool- # adapter): store them in the structured form so nothing has- # to recover them again.- pending.options = [- PendingOption(label=label, body=body)- for label, body in resolved_choice_options.items()- ]- pending.expected_answer = authoritative_answer- interaction.question = pending- visual_result = ""- visual_diagnosis = ""- if pending.visual_context:- from deeptutor.learning.visual_practice import (- account_for_recent_assistance,- evaluate_visual,- )-- pending.visual_context = account_for_recent_assistance(- pending.visual_context, tx.progress.quiz_attempts, pending.knowledge_point_id- )- visual_result, visual_diagnosis = evaluate_visual(pending, raw_answer)- if (- tx.progress.explained_objectives.get(pending.knowledge_point_id, {}).get(- "timestamp", 0- )- > pending.created_at- ):- pending.visual_context["hints_used"] = max(- 1, pending.visual_context.get("hints_used", 0)- )- pending.visual_context["teaching_after_question"] = True- if visual_result == "correct":- graded_answer = authoritative_answer- is_correct = (- None- if visual_result == "ungraded"- else self._apply_grade(- tx.progress,- question_id=pending.question_id,- knowledge_point_id=pending.knowledge_point_id,- module_id=pending.module_id,- user_answer=graded_answer,- expected_answer=authoritative_answer,- question_type=pending.question_type,+ if interaction.question.questions:+ return self._grade_group(+ tx,+ interaction,+ answers=answers,scheduler=scheduler,session_id=session_id,turn_id=turn_id,- visual_context=pending.visual_context,- )+ ), False++ raw_answer, is_correct, visual_result, visual_diagnosis = self._evaluate_question(+ tx,+ interaction,+ answer=answer,+ answer_for_grading=answer_for_grading,+ expected_answer=expected_answer,+ resolved_choice_options=resolved_choice_options,+ scheduler=scheduler,+ session_id=session_id,+ turn_id=turn_id,)+ pending = interaction.questionif (tx.progress.pending_question is not Noneand tx.progress.pending_question.question_id == pending.question_id@@ -1034,6 +1016,269 @@ class LearningService:interaction, replayed = resultreturn progress, interaction, replayed+ @staticmethod+ def _group_contract(pending: PendingQuestion) -> list[tuple]:+ # Choice shuffling changes labels, not the answer contract. Ignore new+ # generated ids when a duplicate tool call re-presents the same group.+ return [+ (+ q.knowledge_point_id,+ q.prompt,+ q.question_type,+ tuple(sorted(q.choice_map.values())),+ q.choice_map.get(q.expected_answer, q.expected_answer),+ q.explanation,+ q.difficulty,+ q.visual_context,+ )+ for q in pending.questions+ ]++ @staticmethod+ def _validate_group_answers(pending: PendingQuestion, answers: Any) -> dict[str, str]:+ ids = {question.question_id for question in pending.questions}+ if (+ not isinstance(answers, dict)+ or set(answers) != ids+ or any(+ not isinstance(value, str) or not value.strip() or len(value) > 10000+ for value in answers.values()+ )+ ):+ raise MasteryInteractionError(+ "Answer every group question once using its exact question_id"+ )+ from deeptutor.learning.pending import resolve_choice_submission++ for question in pending.questions:+ if question.question_type == "choice" and not resolve_choice_submission(+ answers[question.question_id], question.choice_map+ ):+ raise MasteryInteractionError(+ "Choose one unambiguous option for each choice question"+ )+ return {key: value.strip() for key, value in answers.items()}++ @staticmethod+ def _group_result(question_id: str, results: list[dict]) -> dict:+ values = [result["is_correct"] for result in results]+ return {+ "question_id": question_id,+ "question_type": "group",+ "results": results,+ "is_correct": None if None in values else all(values),+ "result": "ungraded"+ if all(value is None for value in values)+ else "mixed"+ if len(set(values)) > 1+ else "correct"+ if all(values)+ else "incorrect",+ }++ def _grade_group(+ self,+ tx,+ interaction: MasteryInteraction,+ *,+ answers,+ scheduler=None,+ session_id="",+ turn_id="",+ ) -> MasteryInteraction:+ """One transaction, native grading per leaf; a parent earns no credit."""+ pending = interaction.question+ submitted = self._validate_group_answers(+ pending, interaction.answers if answers is None else answers+ )+ if interaction.status == InteractionStatus.ANSWERED and submitted != interaction.answers:+ raise MasteryInteractionError(+ "Grade the group's committed answers, not a substituted answer"+ )+ known_ids = {kp.id for module in tx.progress.modules for kp in module.knowledge_points}+ if any(q.knowledge_point_id not in known_ids for q in pending.questions):+ raise MasteryInteractionError("An objective changed; refresh the question group")+ from deeptutor.learning.question_card import build_grade_result++ results = []+ for question in pending.questions:+ leaf = MasteryInteraction(+ interaction_id=question.question_id,+ path_id=interaction.path_id,+ question=question,+ status=InteractionStatus.ANSWERED,+ user_answer=submitted[question.question_id],+ )+ raw, correct, visual_result, diagnosis = self._evaluate_question(+ tx,+ leaf,+ answer=submitted[question.question_id],+ scheduler=scheduler,+ session_id=session_id,+ turn_id=turn_id,+ )+ result = build_grade_result(+ question_id=question.question_id,+ is_correct=bool(correct),+ learner_answer=raw,+ correct_label=question.expected_answer if correct is not None else "",+ choice_options=question.choice_map,+ explanation=question.explanation if correct is not None else diagnosis,+ result=visual_result,+ independent=not bool(question.visual_context.get("hints_used"))+ if question.visual_context+ else None,+ )+ result["is_correct"] = correct+ result["knowledge_point_id"] = question.knowledge_point_id+ if diagnosis:+ result["diagnosis"] = diagnosis+ results.append(result)+ leaf.session_id = session_id or interaction.session_id+ leaf.turn_id = turn_id or interaction.turn_id+ leaf.status = InteractionStatus.GRADED+ leaf.result = {**result, "group_question_id": pending.question_id}+ tx.put_interaction(leaf)+ tx.emit(+ "practice.ungraded" if correct is None else "attempt.recorded",+ {+ "interaction_id": interaction.interaction_id,+ "question_id": question.question_id,+ "knowledge_point_id": question.knowledge_point_id,+ "is_correct": correct,+ },+ session_id=session_id,+ turn_id=turn_id,+ )+ if correct is not None:+ evidence = tx.progress.learning_evidence[-1]+ tx.emit(+ "evidence.recorded",+ {+ "knowledge_point_id": evidence.knowledge_point_id,+ "assessment_type": evidence.assessment_type,+ "result": evidence.result,+ "quality": evidence.quality,+ },+ session_id=session_id,+ turn_id=turn_id,+ )+ interaction.status = InteractionStatus.GRADED+ interaction.answers = submitted+ interaction.session_id = session_id or interaction.session_id+ interaction.turn_id = turn_id or interaction.turn_id+ interaction.result = self._group_result(pending.question_id, results)+ tx.progress.pending_question = None+ tx.put_interaction(interaction)+ tx.emit(+ "interaction.graded",+ dict(interaction.result),+ session_id=interaction.session_id,+ turn_id=interaction.turn_id,+ )+ return interaction++ def _evaluate_question(+ self,+ tx,+ interaction: MasteryInteraction,+ *,+ answer: str,+ answer_for_grading: str | None = None,+ expected_answer: str | None = None,+ resolved_choice_options: dict[str, str] | None = None,+ scheduler: SpacedRepetitionScheduler | None = None,+ session_id: str = "",+ turn_id: str = "",+ ) -> tuple[str, bool | None, str, str]:+ """Shared leaf grader: never creates a parent attempt or commits separately."""+ pending = interaction.question+ raw_answer = str(answer or "")+ if interaction.status == InteractionStatus.ANSWERED:+ stored = str(interaction.user_answer or "")+ if pending.question_type == "choice":+ from deeptutor.learning.pending import (+ has_option_bodies,+ is_readable_choice_answer,+ resolve_choice_submission,+ )++ option_map = pending.choice_map+ if is_readable_choice_answer(stored, option_map):+ raw_answer = stored+ elif is_readable_choice_answer(raw_answer, option_map):+ # Prior commit was unreadable clarifying text (#1004) —+ # accept the fresh readable answer and rewrite storage.+ interaction.user_answer = raw_answer+ else:+ raw_answer = stored+ if has_option_bodies(option_map):+ graded_answer = resolve_choice_submission(raw_answer, option_map) or raw_answer+ else:+ # Legacy questions may need option bodies recovered by+ # the trusted tool adapter from the original turn.+ graded_answer = raw_answer if answer_for_grading is None else answer_for_grading+ else:+ raw_answer = stored+ graded_answer = raw_answer+ else:+ graded_answer = raw_answer if answer_for_grading is None else answer_for_grading+ authoritative_answer = (+ pending.expected_answer if expected_answer is None else expected_answer+ )+ if pending.question_type == "choice" and resolved_choice_options:+ # Bodies recovered for a legacy question (see the tool+ # adapter): store them in the structured form so nothing has+ # to recover them again.+ pending.options = [+ PendingOption(label=label, body=body)+ for label, body in resolved_choice_options.items()+ ]+ pending.expected_answer = authoritative_answer+ interaction.question = pending+ visual_result = ""+ visual_diagnosis = ""+ if pending.visual_context:+ from deeptutor.learning.visual_practice import (+ account_for_recent_assistance,+ evaluate_visual,+ )++ pending.visual_context = account_for_recent_assistance(+ pending.visual_context, tx.progress.quiz_attempts, pending.knowledge_point_id+ )+ visual_result, visual_diagnosis = evaluate_visual(pending, raw_answer)+ if (+ tx.progress.explained_objectives.get(pending.knowledge_point_id, {}).get(+ "timestamp", 0+ )+ > pending.created_at+ ):+ pending.visual_context["hints_used"] = max(+ 1, pending.visual_context.get("hints_used", 0)+ )+ pending.visual_context["teaching_after_question"] = True+ if visual_result == "correct":+ graded_answer = authoritative_answer+ is_correct = (+ None+ if visual_result == "ungraded"+ else self._apply_grade(+ tx.progress,+ question_id=pending.question_id,+ knowledge_point_id=pending.knowledge_point_id,+ module_id=pending.module_id,+ user_answer=graded_answer,+ expected_answer=authoritative_answer,+ question_type=pending.question_type,+ scheduler=scheduler,+ session_id=session_id,+ turn_id=turn_id,+ visual_context=pending.visual_context,+ )+ )+ return raw_answer, is_correct, visual_result, visual_diagnosis+def replace_modules_for_path(self,book_id: str,@@ -1177,19 +1422,41 @@ class LearningService:tx.progress.current_kp_index = 0if tx.progress.pending_question is not None:- if pending_kp_id not in objective_locations:+ pending_leaves = tx.progress.pending_question.questions or [+ tx.progress.pending_question+ ]+ if pending_kp_id not in objective_locations or any(+ q.knowledge_point_id not in objective_locations for q in pending_leaves+ ):tx.progress.pending_question = Noneelse:pending_module_id, _ = objective_locations[pending_kp_id]tx.progress.pending_question.module_id = pending_module_id+ for question in pending_leaves:+ question.module_id = objective_locations[question.knowledge_point_id][0]if active_interaction is not None:- if active_kp_id not in objective_locations:+ active_leaves = active_interaction.question.questions or [+ active_interaction.question+ ]+ if active_kp_id not in objective_locations or any(+ q.knowledge_point_id not in objective_locations for q in active_leaves+ ):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+ active_changed = (+ active_interaction.question.module_id != active_module_id+ or any(+ question.module_id+ != objective_locations[question.knowledge_point_id][0]+ for question in active_leaves+ )+ )+ active_interaction.question.module_id = active_module_id+ for question in active_leaves:+ question.module_id = objective_locations[question.knowledge_point_id][0]+ if active_changed:tx.put_interaction(active_interaction)tx.touch()tx.emit(@@ -1538,6 +1805,10 @@ class LearningService:if attempt.question_id == resolved_id]question = interaction.question if interaction is not None else pending+ if question is not None and question.questions:+ raise MasteryInteractionError(+ "A group has no aggregate answer key; review or challenge an individual child question_id"+ )kp_id = (question.knowledge_point_id if question is not None else "") or (attempts[0].knowledge_point_id if attempts else "")@@ -1662,6 +1933,8 @@ class LearningService:)self._recompute_objective_state(tx.progress, kp_id, scheduler)+ if interaction is not None and interaction.result.get("group_question_id"):+ self._refresh_group_result(tx, interaction)tx.touch()tx.emit("assessment.voided" if action_name == "void" else "assessment.corrected",@@ -1700,6 +1973,44 @@ class LearningService:progress, details = self._store.mutate(book_id, repair)return progress, details+ def _refresh_group_result(self, tx, leaf: MasteryInteraction) -> None:+ """Keep the parent presentation consistent after a native leaf repair."""+ parent = tx.get_interaction(leaf.result["group_question_id"])+ if parent is None:+ return+ from deeptutor.learning.question_card import build_grade_result++ results = []+ questions = []+ for question in parent.question.questions:+ stored = tx.get_interaction(question.question_id)+ if stored is None:+ return+ questions.append(stored.question)+ key = stored.question.expected_answer+ correct = None if stored.result.get("voided") else stored.result.get("is_correct")+ result = build_grade_result(+ question_id=question.question_id,+ is_correct=bool(correct),+ learner_answer=stored.user_answer,+ correct_label=key if correct is not None else "",+ choice_options=stored.question.choice_map,+ explanation=stored.question.explanation+ if correct is not None+ else str(stored.result.get("reason") or ""),+ result="ungraded" if correct is None else "",+ independent=stored.result.get("independent")+ if stored.question.visual_context+ else None,+ )+ result.update(+ {"is_correct": correct, "knowledge_point_id": question.knowledge_point_id}+ )+ results.append(result)+ parent.result = self._group_result(parent.interaction_id, results)+ parent.question.questions = questions+ tx.put_interaction(parent)+def defer_objective(self,book_id: str,@@ -1730,11 +2041,16 @@ class LearningService:)abandoned = Falsepending = tx.progress.pending_question- if pending is not None and pending.knowledge_point_id == target_id:+ if pending is not None and any(+ q.knowledge_point_id == target_id for q in pending.questions or [pending]+ ):tx.progress.pending_question = Noneabandoned = Trueactive = tx.active_interaction()- if active is not None and active.question.knowledge_point_id == target_id:+ if active is not None and any(+ q.knowledge_point_id == target_id+ for q in active.question.questions or [active.question]+ ):tx.abandon_active_interactions()abandoned = Truetx.progress.deferred_objectives[target_id] = DeferredObjective(diff --git a/deeptutor/learning/storage.py b/deeptutor/learning/storage.pyindex f7f000f79..e534d8537 100644--- a/deeptutor/learning/storage.py+++ b/deeptutor/learning/storage.py@@ -155,14 +155,17 @@ class LearningTransaction:def _interaction_from_row(row: sqlite3.Row | None) -> MasteryInteraction | None:if row is None:return None+ question = json.loads(row["question_json"])+ grouped = question.get("question_type") == "group"return MasteryInteraction(interaction_id=row["interaction_id"],path_id=row["path_id"],- question=json.loads(row["question_json"]),+ question=question,status=InteractionStatus(row["status"]),session_id=row["session_id"] or "",turn_id=row["turn_id"] or "",- user_answer=row["user_answer"] or "",+ user_answer="" if grouped else row["user_answer"] or "",+ answers=json.loads(row["user_answer"] or "{}") if grouped else {},result=json.loads(row["result_json"] or "{}"),created_at=float(row["created_at"]),updated_at=float(row["updated_at"]),@@ -229,7 +232,9 @@ class LearningTransaction:json.dumps(interaction.question.model_dump(mode="json"), ensure_ascii=False),interaction.session_id,interaction.turn_id,- interaction.user_answer,+ json.dumps(interaction.answers, ensure_ascii=False)+ if interaction.question.questions+ else interaction.user_answer,json.dumps(interaction.result, ensure_ascii=False),interaction.created_at,now,diff --git a/deeptutor/services/session/turns/learning_adapter.py b/deeptutor/services/session/turns/learning_adapter.pyindex b21f0a6dc..2934f3c14 100644--- a/deeptutor/services/session/turns/learning_adapter.py+++ b/deeptutor/services/session/turns/learning_adapter.py@@ -79,6 +79,7 @@ class LearningTurnAdapter:turn_id: str,question_id: str,answer: str,+ answers: dict[str, str] | None = None,) -> None:"""Record an answer submitted from a card that outlived its turn.@@ -102,6 +103,7 @@ class LearningTurnAdapter:interaction_id=question_id,session_id=session_id,turn_id=turn_id,+ **({"answers": answers} if answers is not None else {}),)try:@@ -141,7 +143,8 @@ class LearningTurnAdapter:"""question_id = str((answer or {}).get("question_id") or "").strip()text = str((answer or {}).get("text") or "")- if not path_id or not question_id or not text:+ answers = (answer or {}).get("answers")+ if not path_id or not question_id or (not text and answers is None):return None# Grading is one deterministic engine operation and this tool is its# only entry point; calling it here keeps that logic in one place@@ -154,7 +157,7 @@ class LearningTurnAdapter:_session_id=execution.session_id,_turn_id=execution.turn_id,question_id=question_id,- answer=text,+ **({"answers": answers} if answers is not None else {"answer": text}),)except Exception:logger.warning(@@ -163,9 +166,13 @@ class LearningTurnAdapter:question_id,exc_info=True,)+ if answers is not None:+ await self._publish_mastery_group_rejection(execution, question_id)return Nonepayload = (result.metadata or {}).get("mastery_grade")if not result.success or not isinstance(payload, dict):+ if answers is not None:+ await self._publish_mastery_group_rejection(execution, question_id)return None# One complete trace group, the same shape the dispatcher emits for a# tool the model called: a lone result with no terminal status renders@@ -209,6 +216,47 @@ class LearningTurnAdapter:)return payload+ async def _publish_mastery_group_rejection(+ self, execution: _TurnExecution, question_id: str+ ) -> None:+ """Reopen an optimistically submitted card without fabricating a verdict."""+ call_id = f"mastery-grade-{execution.turn_id}-{question_id}"+ trace = build_trace_metadata(+ call_id=call_id,+ phase="grading",+ label="Mastery Grade",+ call_kind="tool_call",+ trace_id=call_id,+ tool="mastery_grade",+ )+ message = "These answers could not be submitted. Please review or retry."+ await self._publish_live_event(+ execution,+ StreamEvent(+ type=StreamEventType.TOOL_RESULT,+ source="mastery",+ stage="grading",+ content=message,+ metadata={+ **trace,+ "trace_kind": "tool_result",+ "tool_metadata": {+ "mastery_answer_rejected": {"question_id": question_id, "message": message}+ },+ },+ ),+ )+ await self._publish_live_event(+ execution,+ StreamEvent(+ type=StreamEventType.PROGRESS,+ source="mastery",+ stage="grading",+ content="",+ metadata={**trace, "trace_kind": "call_status", "call_state": "error"},+ ),+ )+async def _skip_card_question(self,execution: _TurnExecution,diff --git a/deeptutor/services/session/turns/request_preparer.py b/deeptutor/services/session/turns/request_preparer.pyindex 064758e72..167c947cc 100644--- a/deeptutor/services/session/turns/request_preparer.py+++ b/deeptutor/services/session/turns/request_preparer.py@@ -113,6 +113,7 @@ class TurnRequestPreparer:turn_id: str,question_id: str,answer: str,+ answers: dict[str, str] | None = None,) -> None: ...async def _acquire_mastery_path_lease(@@ -829,6 +830,11 @@ class TurnRequestPreparer:turn_id=turn["id"],question_id=str(card_answer.get("question_id") or ""),answer=str(card_answer.get("text") or ""),+ **(+ {"answers": card_answer["answers"]}+ if card_answer.get("answers") is not None+ else {}+ ),)except Exception as exc:async with self._lock:diff --git a/tests/capabilities/test_mastery_question_groups.py b/tests/capabilities/test_mastery_question_groups.pynew file mode 100644index 000000000..8ae3b8cff--- /dev/null+++ b/tests/capabilities/test_mastery_question_groups.py@@ -0,0 +1,369 @@+"""One durable parent, independently graded leaves, no answer-key projection."""++import json++from pydantic import ValidationError+import pytest++from deeptutor.learning.models import (+ InteractionStatus,+ KnowledgePoint,+ KnowledgeType,+ LearningModule,+ LearningProgress,+ PendingQuestion,+)+from deeptutor.learning.pending import public_pending_question+from deeptutor.learning.question_card import build_question_card+from deeptutor.learning.service import LearningService, MasteryInteractionError+from deeptutor.learning.storage import LearningStore+++def leaf(question_id="q1", kp_id="kp1", expected="alpha"):+ return PendingQuestion(+ question_id=question_id,+ knowledge_point_id=kp_id,+ module_id="m",+ prompt="Name this.",+ expected_answer=expected,+ explanation="PRIVATE explanation",+ )+++def group():+ return PendingQuestion(+ question_id="g",+ knowledge_point_id="kp1",+ module_id="m",+ prompt="Two questions",+ question_type="group",+ questions=[leaf(), leaf("q2", "kp2", "beta")],+ )+++def service(tmp_path):+ svc = LearningService(LearningStore(tmp_path))+ svc.save(+ LearningProgress(+ book_id="p",+ modules=[+ LearningModule(+ id="m",+ name="Module",+ order=0,+ knowledge_points=[+ KnowledgePoint(id=kp, name=kp, type=KnowledgeType.MEMORY, module_id="m")+ for kp in ["kp1", "kp2"]+ ],+ )+ ],+ )+ )+ return svc+++def test_group_public_projection_and_reload(service):+ _, interaction, created = service.register_question("p", group())+ assert created+ reloaded = service._store.get_interaction("p", interaction.interaction_id)+ assert [q.question_id for q in reloaded.question.questions] == ["q1", "q2"]+ public = public_pending_question(reloaded.question).to_dict()+ card = build_question_card(reloaded.question)+ assert len(public["questions"]) == len(card["questions"]) == 2+ serialized = json.dumps([public, card])+ assert "expected_answer" not in serialized and "PRIVATE" not in serialized+++def test_independent_mixed_results_and_duplicate_credit(service):+ service.register_question("p", group())+ progress, interaction, replayed = service.grade_interaction(+ "p", answer="", question_id="g", answers={"q1": "alpha", "q2": "wrong"}+ )+ assert not replayed+ assert [r["is_correct"] for r in interaction.result["results"]] == [True, False]+ assert len(progress.quiz_attempts) == len(progress.learning_evidence) == 2+ assert {a.question_id for a in progress.quiz_attempts} == {"q1", "q2"}+ assert progress.mastery_levels["kp1"] > progress.mastery_levels["kp2"]+ assert progress.pending_question is None+ replay, _, replayed = service.grade_interaction(+ "p", answer="", question_id="g", answers={"q1": "alpha", "q2": "wrong"}+ )+ assert replayed and len(replay.quiz_attempts) == 2+++ "answers",+ [{"q1": "alpha"}, {"q1": "alpha", "q2": ""}, {"q1": "alpha", "q2": "beta", "other": "x"}],+)+def test_incomplete_or_unknown_answers_do_not_mutate(service, answers):+ service.register_question("p", group())+ before = service._store.load("p").model_dump()+ with pytest.raises(MasteryInteractionError):+ service.grade_interaction("p", answer="", question_id="g", answers=answers)+ assert service._store.load("p").model_dump() == before+++def test_explicit_replacement_retains_abandoned_history(service):+ service.register_question("p", leaf("old"))+ with pytest.raises(MasteryInteractionError):+ service.register_question("p", group())+ _, _, created = service.register_question(+ "p", group(), pending_action="replace", replace_question_id="old"+ )+ assert created+ assert service._store.get_interaction("p", "old").status == InteractionStatus.ABANDONED+ assert not service._store.load("p").quiz_attempts+++def test_invalid_group_leaf_objective_rolls_back_replacement(service):+ service.register_question("p", leaf("old"))+ bad = group()+ bad.questions[1].knowledge_point_id = "unknown"+ with pytest.raises(MasteryInteractionError):+ service.register_question("p", bad, pending_action="replace", replace_question_id="old")+ assert service._store.get_active_interaction("p").interaction_id == "old"+++ "questions", [[leaf()], [leaf(), leaf()], [leaf(str(i)) for i in range(5)]]+)+def test_invalid_group_shape_rejected(questions):+ with pytest.raises(ValidationError):+ PendingQuestion(+ question_id="g", knowledge_point_id="kp1", question_type="group", questions=questions+ )+++def test_native_single_compatibility(service):+ service.register_question("p", leaf())+ _, active, created = service.register_question("p", leaf("new"))+ assert not created and active.interaction_id == "q1"+ progress, interaction, _ = service.grade_interaction("p", answer="alpha", question_id="q1")+ assert interaction.result["is_correct"] is True+ assert len(progress.quiz_attempts) == 1+++def test_group_rejects_duplicated_question_for_same_objective():+ with pytest.raises(ValidationError, match="distinct questions"):+ PendingQuestion(+ question_id="g",+ knowledge_point_id="kp1",+ question_type="group",+ questions=[leaf(), leaf("different-id")],+ )+++async def test_quiz_tool_group_and_grade_tool_use_independent_contract(service, monkeypatch):+ from deeptutor.capabilities.mastery import tools++ monkeypatch.setattr(tools, "_new_service", lambda: service)+ synced = []++ async def sync(**kwargs):+ synced.append(kwargs["pending"].question_id)++ monkeypatch.setattr(tools, "_sync_mastery_attempt_to_question_bank", sync)+ result = await tools.MasteryQuizTool().execute(+ _mastery_path_id="p",+ questions=[+ {"knowledge_point_id": "kp1", "question": "First?", "expected_answer": "alpha"},+ {"knowledge_point_id": "kp2", "question": "Second?", "expected_answer": "beta"},+ ],+ )+ assert result.success+ card = result.metadata["mastery_question"]+ assert len(card["questions"]) == 2+ leaves = service._store.get_active_interaction("p").question.questions+ graded = await tools.MasteryGradeTool().execute(+ _mastery_path_id="p",+ question_id=card["question_id"],+ answers={q.question_id: q.expected_answer for q in leaves},+ )+ assert graded.success+ payload = graded.metadata["mastery_grade"]+ assert len(payload["result"]["results"]) == 2+ assert set(synced) == {q.question_id for q in leaves}+++async def test_replacement_requires_literal_current_learner_request(service, monkeypatch):+ from deeptutor.capabilities.mastery import tools++ monkeypatch.setattr(tools, "_new_service", lambda: service)+ service.register_question("p", leaf("old"))+ kwargs = dict(+ _mastery_path_id="p",+ pending_action="replace",+ replace_question_id="old",+ replacement_request="Replace my question",+ _learner_message="Please explain",+ questions=[+ {"knowledge_point_id": "kp1", "question": "First?", "expected_answer": "alpha"},+ {"knowledge_point_id": "kp2", "question": "Second?", "expected_answer": "beta"},+ ],+ )+ result = await tools.MasteryQuizTool().execute(**kwargs)+ assert not result.success+ assert service._store.get_active_interaction("p").interaction_id == "old"+ kwargs["_learner_message"] = "Replace my question with two questions please"+ assert (await tools.MasteryQuizTool().execute(**kwargs)).success+++def test_committed_group_answers_are_authoritative_after_reload(service):+ service.register_question("p", group())+ service.record_question_answer(+ "p", "display only", interaction_id="g", answers={"q1": "alpha", "q2": "wrong"}+ )+ reloaded = LearningService(LearningStore(service._store._root))+ stored = reloaded._store.get_active_interaction("p")+ assert stored.answers == {"q1": "alpha", "q2": "wrong"}+ with pytest.raises(MasteryInteractionError):+ reloaded.grade_interaction(+ "p", answer="", question_id="g", answers={"q1": "alpha", "q2": "beta"}+ )+ _, interaction, _ = reloaded.grade_interaction("p", answer="", question_id="g")+ assert [r["is_correct"] for r in interaction.result["results"]] == [True, False]+++def test_leaf_history_repair_does_not_change_sibling_credit(service):+ service.register_question("p", group())+ service.grade_interaction(+ "p", answer="", question_id="g", answers={"q1": "alpha", "q2": "wrong"}+ )+ assert service._store.get_interaction("p", "q2").question.expected_answer == "beta"+ progress, _ = service.repair_question(+ "p", "q2", action="correct", expected_answer="wrong", reason="Verified key correction"+ )+ assert len(progress.quiz_attempts) == 2+ assert all(attempt.is_correct for attempt in progress.quiz_attempts)+ assert all(r["is_correct"] for r in service._store.get_interaction("p", "g").result["results"])+ assert service._store.get_interaction("p", "g").question.questions[1].expected_answer == "wrong"+ progress, _ = service.repair_question("p", "q2", action="void", reason="Uncertain key")+ assert progress.quiz_attempts[0].is_correct and not progress.quiz_attempts[0].voided+ assert progress.quiz_attempts[1].voided+ parent = service._store.get_interaction("p", "g")+ assert parent.result["results"][1]["is_correct"] is None+ assert parent.result["is_correct"] is None+++def test_parent_repair_cannot_grant_aggregate_credit(service):+ service.register_question("p", group())+ with pytest.raises(MasteryInteractionError):+ service.repair_question(+ "p",+ "g",+ action="correct",+ expected_answer="anything",+ reason="Cannot apply aggregate key",+ )+ assert not service._store.load("p").quiz_attempts+++def test_removing_second_objective_abandons_whole_group(service):+ service.register_question("p", group())+ progress = service._store.load("p")+ progress.modules[0].knowledge_points = progress.modules[0].knowledge_points[:1]+ service.replace_modules_for_path("p", progress.modules)+ assert service._store.load("p").pending_question is None+ assert service._store.get_interaction("p", "g").status == InteractionStatus.ABANDONED+++def test_unrelated_outline_change_keeps_pending_group_snapshot(service):+ service.register_question("p", group())+ before = service._store.get_active_interaction("p").model_dump()+ progress = service._store.load("p")+ progress.modules[0].name = "Updated section title"+ service.replace_modules_for_path("p", progress.modules)+ assert service._store.get_active_interaction("p").model_dump() == before+++def test_defer_second_objective_retires_group_without_mastery_credit(service):+ service.register_question("p", group())+ progress, _ = service.defer_objective("p", "kp2", note="Return later")+ assert progress.pending_question is None and not progress.quiz_attempts+ assert service._store.get_interaction("p", "g").status == InteractionStatus.ABANDONED+++def test_different_group_cannot_silently_reuse_existing(service):+ service.register_question("p", group())+ different = group()+ different.questions[1].prompt = "An unrelated question?"+ with pytest.raises(MasteryInteractionError):+ service.register_question("p", different)+++def test_stale_replace_id_and_stale_submission_cannot_change_new_pending(service):+ service.register_question("p", leaf("old"))+ with pytest.raises(MasteryInteractionError):+ service.register_question(+ "p", group(), pending_action="replace", replace_question_id="stale"+ )+ service.register_question("p", group(), pending_action="replace", replace_question_id="old")+ with pytest.raises(MasteryInteractionError):+ service.grade_interaction("p", answer="alpha", question_id="old")+ assert service._store.get_active_interaction("p").interaction_id == "g"+++def test_unreadable_choice_does_not_mark_any_group_answer_wrong(service):+ pending = group()+ pending.questions[1] = PendingQuestion(+ question_id="q2",+ knowledge_point_id="kp2",+ prompt="Choose?",+ question_type="choice",+ expected_answer="A",+ options=[{"label": "A", "body": "right"}, {"label": "B", "body": "wrong"}],+ )+ service.register_question("p", pending)+ with pytest.raises(MasteryInteractionError):+ service.grade_interaction(+ "p", answer="", question_id="g", answers={"q1": "alpha", "q2": "A or B"}+ )+ assert not service._store.load("p").quiz_attempts+++def test_uncertain_visual_leaf_remains_ungraded_without_key_leak(service, monkeypatch):+ from deeptutor.learning import visual_practice++ pending = group()+ pending.questions[1].visual_context = {"task": "identification"}+ monkeypatch.setattr(+ visual_practice, "account_for_recent_assistance", lambda context, *_: context+ )+ monkeypatch.setattr(+ visual_practice, "evaluate_visual", lambda *_: ("ungraded", "Verify original image")+ )+ service.register_question("p", pending)+ progress, interaction, _ = service.grade_interaction(+ "p", answer="", question_id="g", answers={"q1": "alpha", "q2": "beta"}+ )+ assert len(progress.quiz_attempts) == 1+ result = interaction.result["results"][1]+ assert result["is_correct"] is None and result["result"] == "ungraded"+ assert result["correct_label"] == "" and "PRIVATE" not in json.dumps(result)+ assert interaction.result["is_correct"] is None+++def test_group_definition_keeps_nested_answer_keys_sensitive():+ from deeptutor.capabilities.mastery.tools import MasteryQuizTool++ definition = MasteryQuizTool().get_definition()+ group_param = next(p for p in definition.parameters if p.name == "questions")+ assert group_param.sensitive+ assert group_param.items["properties"]["expected_answer"]["type"] == "string"+++async def test_grade_tool_cannot_redirect_stale_id_to_active_group(service, monkeypatch):+ from deeptutor.capabilities.mastery import tools++ monkeypatch.setattr(tools, "_new_service", lambda: service)+ service.register_question("p", group())+ result = await tools.MasteryGradeTool().execute(+ _mastery_path_id="p", question_id="stale", answers={"q1": "alpha", "q2": "beta"}+ )+ assert not result.success+ assert not service._store.load("p").quiz_attempts+ assert service._store.get_active_interaction("p").interaction_id == "g"diff --git a/tests/services/session/test_mastery_group_runtime.py b/tests/services/session/test_mastery_group_runtime.pynew file mode 100644index 000000000..61e3786c4--- /dev/null+++ b/tests/services/session/test_mastery_group_runtime.py@@ -0,0 +1,181 @@+"""Group answers stay independently identified across the runtime boundary."""++from types import SimpleNamespace++from pydantic import ValidationError+import pytest++from deeptutor.capabilities.mastery.loop import MasteryLoopCapability+from deeptutor.core.context import UnifiedContext+from deeptutor.core.turn_request import MasteryCardAnswer+from deeptutor.services.session.turns.learning_adapter import LearningTurnAdapter+++def test_card_contract_keeps_independent_group_answers():+ card = MasteryCardAnswer(+ question_id="group", text="1: A; 2: B", answers={"first": "A", "second": "B"}+ )+ assert card.model_dump()["answers"] == {"first": "A", "second": "B"}+ assert MasteryCardAnswer(question_id="single", text="A").answers is None+++ "answers", [{}, {"first": "A"}, {"first": "", "second": "B"}, {"first": 1, "second": "B"}]+)+def test_group_transport_rejects_incomplete_or_untyped_values(answers):+ with pytest.raises(ValidationError):+ MasteryCardAnswer(question_id="group", text="display", answers=answers)+++async def test_runtime_forwards_group_map_not_display_summary(monkeypatch):+ calls = []+ published = []++ async def grade(self, **kwargs):+ calls.append(kwargs)+ return SimpleNamespace(+ success=True,+ content="{}",+ metadata={+ "mastery_grade": {+ "question_id": "group",+ "result": {"results": []},+ "is_correct": False,+ }+ },+ )++ async def publish(execution, event):+ published.append(event)+ return {}++ monkeypatch.setattr("deeptutor.capabilities.mastery.tools.MasteryGradeTool.execute", grade)+ adapter = LearningTurnAdapter()+ adapter._publish_live_event = publish+ result = await adapter._grade_submitted_card_answer(+ SimpleNamespace(session_id="session", turn_id="turn"),+ path_id="path",+ answer={+ "question_id": "group",+ "text": "display only",+ "answers": {"first": "A", "second": "B"},+ },+ )+ assert result["question_id"] == "group"+ assert calls[0]["answers"] == {"first": "A", "second": "B"}+ assert calls[0].get("answer", "") != "display only"+ assert len(published) == 2+++async def test_commit_keeps_group_map_in_the_native_answer_record(monkeypatch):+ calls = []++ def record(self, path_id, answer, **kwargs):+ calls.append((path_id, answer, kwargs))++ monkeypatch.setattr("deeptutor.learning.service.LearningService.record_question_answer", record)+ await LearningTurnAdapter()._commit_mastery_card_answer(+ path_id="path",+ session_id="session",+ turn_id="turn",+ question_id="group",+ answer="display only",+ answers={"first": "A", "second": "B"},+ )+ assert calls[0][2]["answers"] == {"first": "A", "second": "B"}+++ "reply",+ [+ "Answer these two practice questions; I will grade both answers.\n1. Which change increases the rate?\n2. Explain why it increases?",+ "Válaszolj erre a két gyakorló kérdésre.\n1. Melyik változás növeli a sebességet?\n2. Miért növeli?",+ ],+)+def test_explicit_numbered_assessment_cannot_finish_as_unregistered_prose(reply):+ instruction = MasteryLoopCapability().finish_instruction(+ UnifiedContext(metadata={"mastery_mode": True}), reply+ )+ assert instruction is not None+ assert "mastery_quiz" in instruction+++ "reply",+ [+ "Two useful ideas:\n1. Motion is random.\n2. The gradient changes net motion.",+ "Think about two examples:\n1. Where does it move?\n2. Which force matters?",+ "A korábbi kérdésről beszélünk, nem új feladatról.\n1. Miért fontos az irány?\n2. Mire utal a különbség?",+ ],+)+def test_connected_teaching_is_not_a_forced_assessment(reply):+ assert (+ MasteryLoopCapability().finish_instruction(+ UnifiedContext(metadata={"mastery_mode": True}), reply+ )+ is None+ )+++def test_group_seed_reads_real_nested_results_and_keeps_unknown_neutral():+ context = UnifiedContext(+ metadata={+ "mastery_mode": True,+ "mastery_card_grade": {+ "question_id": "group",+ "is_correct": None,+ "result": {+ "question_type": "group",+ "results": [+ {+ "question_id": "first",+ "knowledge_point_id": "point-a",+ "is_correct": True,+ },+ {+ "question_id": "second",+ "knowledge_point_id": "point-b",+ "is_correct": None,+ },+ ],+ },+ },+ }+ )+ seed = MasteryLoopCapability().pre_loop_seed(context)+ assert "first: correct" in seed+ assert "second: ungraded" in seed+ assert "second: incorrect" not in seed+++async def test_rejected_group_answer_emits_card_recovery_event(monkeypatch):+ published = []++ async def grade(self, **kwargs):+ return SimpleNamespace(success=False, content="invalid answers", metadata={})++ async def publish(execution, event):+ published.append(event)+ return {}++ monkeypatch.setattr("deeptutor.capabilities.mastery.tools.MasteryGradeTool.execute", grade)+ adapter = LearningTurnAdapter()+ adapter._publish_live_event = publish+ result = await adapter._grade_submitted_card_answer(+ SimpleNamespace(session_id="session", turn_id="turn"),+ path_id="path",+ answer={+ "question_id": "group",+ "text": "display",+ "answers": {"first": "A", "second": "B"},+ },+ )+ assert result is None+ assert len(published) == 2+ metadata = published[0].metadata+ assert metadata["tool_metadata"]["mastery_answer_rejected"]["question_id"] == "group"+ assert "turn" in metadata["call_id"]+ assert "mastery_grade" not in metadata["tool_metadata"]diff --git a/web/components/chat/home/MasteryQuestionCard.tsx b/web/components/chat/home/MasteryQuestionCard.tsxindex a100da28a..c96e2039f 100644--- a/web/components/chat/home/MasteryQuestionCard.tsx+++ b/web/components/chat/home/MasteryQuestionCard.tsx@@ -24,9 +24,10 @@ import { useTranslation } from "react-i18next";import InlineMarkdown from "@/components/common/InlineMarkdown";import { useCardSubmission } from "@/hooks/use-card-submission";import { REPLY_NOT_DELIVERED } from "@/lib/ask-user-state";-import type {- MasteryGradeResult,- MasteryQuestion,+import {+ MASTERY_ANSWER_REJECTED_MESSAGE,+ type MasteryGradeResult,+ type MasteryQuestion,} from "@/lib/mastery-question";/** Difficulty is a three-point scale; anything else is not shown. */@@ -92,16 +93,7 @@ function OptionRow({);}-export const MasteryQuestionCard = memo(function MasteryQuestionCard({- question,- grade,- answered,- skipped,- submittedAnswer,- onSubmit,- onSkip,- onChallenge,-}: {+interface MasteryQuestionCardProps {question: MasteryQuestion;/** The gate's ruling, once it has been made. */grade: MasteryGradeResult | null;@@ -111,6 +103,8 @@ export const MasteryQuestionCard = memo(function MasteryQuestionCard({skipped?: boolean;/** What they answered, when the transcript knows it. */submittedAnswer: string;+ /** Unique server rejection event; changes reopen an optimistically sent card. */+ rejectionKey?: string;onSubmit: (payload: {text?: string;answers?: Array<{ questionId: string; text: string }>;@@ -119,14 +113,25 @@ export const MasteryQuestionCard = memo(function MasteryQuestionCard({* cannot start a turn of its own, which hides the control entirely. */onSkip?: (questionId: string) => void | boolean | Promise<void | boolean>;onChallenge?: (questionId: string) => void | boolean | Promise<void | boolean>;-}) {+}++/** The same native controls, with submission owned by their group instead. */+interface GroupInput {+ locked: boolean;+ onChange: (questionId: string, answer: string, sourceAvailable: boolean) => void;+}++const SingleMasteryQuestionCard = memo(function SingleMasteryQuestionCard({+ question, grade, answered, skipped, submittedAnswer, onSubmit, onSkip,+ onChallenge, groupInput, rejectionKey,+}: MasteryQuestionCardProps & { groupInput?: GroupInput }) {const { t } = useTranslation();const [picked, setPicked] = useState<string>("");const [skipping, setSkipping] = useState(false);const [sourceUnavailable, setSourceUnavailable] = useState(false);const [freeText, setFreeText] = useState("");const [freeSelected, setFreeSelected] = useState(false);- const { sending, failed: sendFailed, submit } = useCardSubmission(onSubmit);+ const { sending, failed: sendFailed, submit } = useCardSubmission(onSubmit, rejectionKey);const textareaRef = useRef<HTMLTextAreaElement>(null);useEffect(() => {@@ -140,7 +145,12 @@ export const MasteryQuestionCard = memo(function MasteryQuestionCard({// question, so there is nothing left on it to send.const settled = answered || skipped === true;const ungraded = grade?.result === "ungraded";- const locked = settled || sending || skipping;+ const locked = settled || sending || skipping || groupInput?.locked === true;++ const onGroupChange = groupInput?.onChange;+ useEffect(() => {+ onGroupChange?.(question.questionId, answer, !sourceUnavailable);+ }, [onGroupChange, question.questionId, answer, sourceUnavailable]);const handleSkip = useCallback(() => {if (locked || !onSkip) return;@@ -240,6 +250,7 @@ export const MasteryQuestionCard = memo(function MasteryQuestionCard({{freeSelected || !hasChoices ? (<textarearef={textareaRef}+ aria-label={question.prompt}value={freeText}onChange={(event) => setFreeText(event.target.value)}placeholder={t("Write your answer…")}@@ -294,7 +305,7 @@ export const MasteryQuestionCard = memo(function MasteryQuestionCard({) : null}{/* Footer: only while the question is still the learner's move. */}- {!settled ? (+ {!groupInput && (!settled ? (<div className="mt-3 flex items-center justify-between gap-3"><spanclassName={@@ -307,7 +318,7 @@ export const MasteryQuestionCard = memo(function MasteryQuestionCard({{sending? t("Sending your answers…"): sendFailed- ? t(REPLY_NOT_DELIVERED)+ ? t(rejectionKey ? MASTERY_ANSWER_REJECTED_MESSAGE : REPLY_NOT_DELIVERED): hasChoices? t("Pick the option you think is right."): t("Write your answer to continue.")}@@ -344,9 +355,84 @@ export const MasteryQuestionCard = memo(function MasteryQuestionCard({<div className="mt-2.5 text-[11px] text-[var(--muted-foreground)]">{t("Answer submitted — your tutor is checking it.")}</div>- ) : null}+ ) : null)}</div>);});+function GroupedMasteryQuestionCard({+ question, grade, answered, skipped, onSubmit, onSkip, onChallenge, rejectionKey,+}: MasteryQuestionCardProps) {+ const { t } = useTranslation();+ const [answers, setAnswers] = useState<Record<string, { text: string; available: boolean }>>({});+ const [skipping, setSkipping] = useState(false);+ const [skipFailed, setSkipFailed] = useState(false);+ const { sending, failed, submit } = useCardSubmission(onSubmit, rejectionKey);+ const questions = question.questions ?? [];+ const settled = answered || Boolean(grade) || skipped === true;+ const locked = settled || sending || skipping;+ const ready = questions.length >= 2 && questions.every((part) =>+ Boolean(answers[part.questionId]?.text) && answers[part.questionId]?.available);++ const updateAnswer = useCallback((questionId: string, text: string, available: boolean) => {+ setAnswers((current) => current[questionId]?.text === text && current[questionId]?.available === available+ ? current : { ...current, [questionId]: { text, available } });+ }, []);++ const handleSubmit = () => {+ if (locked || !ready) return;+ const parts = questions.map((part) => ({ questionId: part.questionId, text: answers[part.questionId].text }));+ void submit({ text: parts.map((part, index) => `${index + 1}. ${part.text}`).join("\n"), answers: parts });+ };++ const handleSkip = async () => {+ if (locked || !onSkip) return;+ setSkipping(true);+ setSkipFailed(false);+ try {+ if (await onSkip(question.questionId) === false) {+ setSkipping(false);+ setSkipFailed(true);+ }+ } catch {+ setSkipping(false);+ setSkipFailed(true);+ }+ };++ return <section className="my-4" aria-label={question.prompt}>+ {question.prompt && <div className="font-serif font-semibold"><InlineMarkdown content={question.prompt} /></div>}+ {questions.map((part) => {+ const partGrade = grade?.results?.find((result) => result.questionId === part.questionId) ?? null;+ return <SingleMasteryQuestionCard key={part.questionId} question={part} grade={partGrade}+ answered={settled} skipped={skipped} submittedAnswer={partGrade?.learnerAnswer ?? ""}+ onSubmit={onSubmit} onChallenge={onChallenge} groupInput={{ locked, onChange: updateAnswer }} />;+ })}+ {!settled ? <div className="mt-3 flex items-center justify-between gap-3">+ <span className={failed || skipFailed ? "text-xs text-[var(--destructive)]" : "text-xs text-[var(--muted-foreground)]"}>+ {sending ? t("Sending your answers…") : failed || skipFailed+ ? t(failed && rejectionKey ? MASTERY_ANSWER_REJECTED_MESSAGE : REPLY_NOT_DELIVERED)+ : t("Write your answer to continue.")}+ </span>+ <div className="flex shrink-0 items-center gap-1">+ {onSkip && <button type="button" onClick={() => void handleSkip()} disabled={locked}+ className="rounded-md px-2 py-1.5 text-xs text-[var(--muted-foreground)] disabled:opacity-40">+ {skipping ? t("Skipping…") : t("Skip this one")}+ </button>}+ <button type="button" onClick={handleSubmit} disabled={locked || !ready}+ className="rounded-md bg-[var(--primary)] px-3 py-1.5 text-xs font-medium text-[var(--primary-foreground)] disabled:opacity-40">+ {t("Submit")}+ </button>+ </div>+ </div> : skipped ? <p className="text-xs text-[var(--muted-foreground)]">{t("Skipped — no attempt was recorded for this question.")}</p>+ : !grade ? <p className="text-xs text-[var(--muted-foreground)]">{t("Answer submitted — your tutor is checking it.")}</p> : null}+ </section>;+}++export const MasteryQuestionCard = memo(function MasteryQuestionCard(props: MasteryQuestionCardProps) {+ return props.question.questionType === "group"+ ? <GroupedMasteryQuestionCard key={props.question.questionId} {...props} />+ : <SingleMasteryQuestionCard {...props} />;+});+export default MasteryQuestionCard;diff --git a/web/components/space/learning/MasteryStudy.tsx b/web/components/space/learning/MasteryStudy.tsxindex ffdb96c57..ab6c199b0 100644--- a/web/components/space/learning/MasteryStudy.tsx+++ b/web/components/space/learning/MasteryStudy.tsx@@ -431,13 +431,17 @@ export function MasteryStudy({// backend, and returning ``false`` here reopens the card instead of showing// the learner that refusal.const answerMasteryQuestion = useCallback(- (answer: { questionId: string; text: string }) => {+ (answer: { questionId: string; text: string; answers?: Array<{ questionId: string; text: string }> }) => {const text = answer.text.trim();if (!text || state.isStreaming || sessionLoading || sessionError) {return false;}sendMessage(text, undefined, undefined, undefined, undefined, {- masteryAnswer: { question_id: answer.questionId, text },+ masteryAnswer: {+ question_id: answer.questionId,+ text,+ ...(answer.answers ? { answers: Object.fromEntries(answer.answers.map((item) => [item.questionId, item.text])) } : {}),+ },});shouldAutoScrollRef.current = true;return true;diff --git a/web/contracts/generated/api.ts b/web/contracts/generated/api.tsindex 1c2d25e92..37230c060 100644--- a/web/contracts/generated/api.ts+++ b/web/contracts/generated/api.ts@@ -13677,6 +13677,13 @@ export interface components {* recover the pairing from prose.*/readonly MasteryCardAnswer: {+ /**+ * Answers+ * @default null+ */+ readonly answers: {+ readonly [key: string]: string;+ } | null;/** Question Id */readonly question_id: string;/** Text */diff --git a/web/contracts/generated/turn-protocol.ts b/web/contracts/generated/turn-protocol.tsindex 08b0ccb61..bf22645dd 100644--- a/web/contracts/generated/turn-protocol.ts+++ b/web/contracts/generated/turn-protocol.ts@@ -42,6 +42,9 @@ export type KnowledgeBases = string[];export type Language = string | null;export type ModelId = string;export type ProfileId = string;+export type Answers = {+ [k: string]: string;+} | null;export type QuestionId = string;export type Text = string;export type MasteryPathId = string | null;@@ -113,7 +116,7 @@ export type Type6 = "cancel_turn";export type ProtocolVersion6 = "2.0";export type SessionId3 = string;export type Type7 = "regenerate";-export type Answers = UserAnswer[] | null;+export type Answers1 = UserAnswer[] | null;export type Questionid = string;export type Text1 = string;export type CommandId1 = string;@@ -370,6 +373,7 @@ export interface LLMSelection {* via the `definition` "MasteryCardAnswer".*/export interface MasteryCardAnswer {+ answers?: Answers;question_id: QuestionId;text: Text;}@@ -487,7 +491,7 @@ export interface Overrides {* via the `definition` "SubmitUserReplyCommand".*/export interface SubmitUserReplyCommand {- answers?: Answers;+ answers?: Answers1;command_id: CommandId1;protocol_version: ProtocolVersion7;text?: Text2;diff --git a/web/contracts/schema/openapi.json b/web/contracts/schema/openapi.jsonindex e371c204d..669364bf8 100644--- a/web/contracts/schema/openapi.json+++ b/web/contracts/schema/openapi.json@@ -5958,6 +5958,23 @@"additionalProperties": false,"description": "An answer submitted from a mastery question card.\n\nThe card outlives the turn that posed it — posing a question ends that\nturn — so the answer arrives as the next turn's message. This says which\nquestion the message is answering, letting the runtime commit it to the\nengine before the tutor's first token instead of asking the model to\nrecover the pairing from prose.","properties": {+ "answers": {+ "anyOf": [+ {+ "additionalProperties": {+ "type": "string"+ },+ "maxProperties": 4,+ "minProperties": 2,+ "type": "object"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "title": "Answers"+ },"question_id": {"minLength": 1,"title": "Question Id",diff --git a/web/contracts/schema/turn-protocol.json b/web/contracts/schema/turn-protocol.jsonindex 540b7abbf..d5f4c6b8c 100644--- a/web/contracts/schema/turn-protocol.json+++ b/web/contracts/schema/turn-protocol.json@@ -239,6 +239,23 @@"additionalProperties": false,"description": "An answer submitted from a mastery question card.\n\nThe card outlives the turn that posed it — posing a question ends that\nturn — so the answer arrives as the next turn's message. This says which\nquestion the message is answering, letting the runtime commit it to the\nengine before the tutor's first token instead of asking the model to\nrecover the pairing from prose.","properties": {+ "answers": {+ "anyOf": [+ {+ "additionalProperties": {+ "type": "string"+ },+ "maxProperties": 4,+ "minProperties": 2,+ "type": "object"+ },+ {+ "type": "null"+ }+ ],+ "default": null,+ "title": "Answers"+ },"question_id": {"minLength": 1,"title": "Question Id",diff --git a/web/features/chat/components/ChatWorkspace.tsx b/web/features/chat/components/ChatWorkspace.tsxindex 9cae05f61..9243e6c38 100644--- a/web/features/chat/components/ChatWorkspace.tsx+++ b/web/features/chat/components/ChatWorkspace.tsx@@ -2099,7 +2099,7 @@ export default function ChatWorkspace() {// and ``masteryAnswer`` tells the backend which question it settles so the// engine has the answer committed before the tutor reads anything.const answerMasteryQuestion = useCallback(- (answer: { questionId: string; text: string }) => {+ (answer: { questionId: string; text: string; answers?: Array<{ questionId: string; text: string }> }) => {const text = answer.text.trim();// One live turn per path: submitting into a running one is refused, and// ``false`` reopens the card rather than surfacing that refusal.@@ -2111,7 +2111,11 @@ export default function ChatWorkspace() {undefined,undefined,{- masteryAnswer: { question_id: answer.questionId, text },+ masteryAnswer: {+ question_id: answer.questionId,+ text,+ ...(answer.answers ? { answers: Object.fromEntries(answer.answers.map((item) => [item.questionId, item.text])) } : {}),+ },},);shouldAutoScrollRef.current = true;diff --git a/web/features/chat/messages/ChatMessageList.tsx b/web/features/chat/messages/ChatMessageList.tsxindex 88150b741..7effeb4dc 100644--- a/web/features/chat/messages/ChatMessageList.tsx+++ b/web/features/chat/messages/ChatMessageList.tsx@@ -83,10 +83,12 @@ import {} from "@/components/chat/home/AskUserOptions";import { MasteryQuestionCard } from "@/components/chat/home/MasteryQuestionCard";import {+ collectMasteryAnswerRejections,collectMasteryGrades,collectMasterySkips,extractMasteryQuestion,type MasteryGradeResult,+ type MasteryAnswerRejection,type MasteryQuestion,} from "@/lib/mastery-question";import { SetupCredentialCard } from "@/components/chat/home/SetupCredentialCard";@@ -648,6 +650,7 @@ export const AssistantMessage = memo(function AssistantMessage({onTraceToggle,masteryGrades,masterySkips,+ masteryAnswerRejections,}: {msg: {id?: number;@@ -666,6 +669,7 @@ export const AssistantMessage = memo(function AssistantMessage({/** Every question the learner dropped, by id — collected the same way and* for the same reason: the skip lands on a later turn than the card. */masterySkips?: Set<string>;+ masteryAnswerRejections?: Map<string, MasteryAnswerRejection>;outlineStatus?: "editing" | "researching" | "done" | "failed";sessionId?: string | null;language?: string;@@ -704,6 +708,7 @@ export const AssistantMessage = memo(function AssistantMessage({onAnswerMasteryQuestion?: (answer: {questionId: string;text: string;+ answers?: Array<{ questionId: string; text: string }>;}) => void | boolean | Promise<void | boolean>;/** Drop a question the learner does not want to answer. Same turn-starting* shape as answering it, because the engine holds one open question per@@ -812,11 +817,13 @@ export const AssistantMessage = memo(function AssistantMessage({answered={Boolean(grade)}skipped={masterySkips?.has(question.questionId) ?? false}submittedAnswer={grade?.learnerAnswer ?? ""}- onSubmit={({ text }) =>+ rejectionKey={!grade ? masteryAnswerRejections?.get(question.questionId)?.retryKey : undefined}+ onSubmit={({ text, answers }) =>onAnswerMasteryQuestion? onAnswerMasteryQuestion({questionId: question.questionId,text: String(text ?? ""),+ ...(question.questionType === "group" ? { answers } : {}),}): false}@@ -828,6 +835,7 @@ export const AssistantMessage = memo(function AssistantMessage({[masteryGrades,masterySkips,+ masteryAnswerRejections,onAnswerMasteryQuestion,onSkipMasteryQuestion,onChallengeMasteryQuestion,@@ -1979,6 +1987,7 @@ export const ChatMessageList = memo(function ChatMessageList({onAnswerMasteryQuestion?: (answer: {questionId: string;text: string;+ answers?: Array<{ questionId: string; text: string }>;}) => void | boolean | Promise<void | boolean>;/** Drop a question instead of answering it; also starts a turn. */onSkipMasteryQuestion?: (@@ -2086,6 +2095,10 @@ export const ChatMessageList = memo(function ChatMessageList({() => collectMasterySkips(visibleMessages),[visibleMessages],);+ const masteryAnswerRejections = useMemo(+ () => collectMasteryAnswerRejections(visibleMessages),+ [visibleMessages],+ );const outlineStatusByIndex = useMemo(() => {const map = new Map<@@ -2327,6 +2340,7 @@ export const ChatMessageList = memo(function ChatMessageList({onTraceToggle={handleTraceToggle}masteryGrades={masteryGrades}masterySkips={masterySkips}+ masteryAnswerRejections={masteryAnswerRejections}/></InlineFileCardProvider><GeneratedFileCardsdiff --git a/web/hooks/use-card-submission.ts b/web/hooks/use-card-submission.tsindex 5c2b818f1..8a6f870b3 100644--- a/web/hooks/use-card-submission.ts+++ b/web/hooks/use-card-submission.ts@@ -22,16 +22,18 @@ export type SubmitUserReply = (* Both question cards implement that same three-state dance, so it lives here* rather than twice.*/-export function useCardSubmission(onSubmit: SubmitUserReply) {+export function useCardSubmission(onSubmit: SubmitUserReply, rejectionKey?: string) {const [sending, setSending] = useState(false);const [failed, setFailed] = useState(false);const [failureMessage, setFailureMessage] = useState<string | null>(null);+ const [submittedAfterRejection, setSubmittedAfterRejection] = useState<string>();const submit = useCallback(async (payload: UserReplyPayload) => {setSending(true);setFailed(false);setFailureMessage(null);+ setSubmittedAfterRejection(rejectionKey);let accepted: void | boolean;try {accepted = await onSubmit(payload);@@ -47,8 +49,12 @@ export function useCardSubmission(onSubmit: SubmitUserReply) {setFailed(true);}},- [onSubmit],+ [onSubmit, rejectionKey],);- return { sending, failed, failureMessage, submit };+ // A delivered turn may still reject its answer contract on the server.+ // Compare durable event identities, not copy: identical retries must each+ // reopen the existing editors, without clearing the learner's answers.+ const rejected = Boolean(rejectionKey && rejectionKey !== submittedAfterRejection);+ return { sending: sending && !rejected, failed: failed || rejected, failureMessage, submit };}diff --git a/web/lib/mastery-question.ts b/web/lib/mastery-question.tsindex 48a2a53c4..0553f47f2 100644--- a/web/lib/mastery-question.ts+++ b/web/lib/mastery-question.ts@@ -23,6 +23,8 @@ import { toolResultPayload } from "@/lib/tool-event";/** Tool-metadata key the posed card travels under. */export const MASTERY_QUESTION_KEY = "mastery_question";+export const MASTERY_ANSWER_REJECTED_MESSAGE =+ "These answers could not be submitted. Please review or retry.";/*** The `kind` marker on the older `ask_user`-shaped card. Only history carries* it; nothing posed now needs a discriminator, because the key *is* the@@ -44,6 +46,8 @@ export interface MasteryQuestion {attempt: number;options: MasteryQuestionOption[];allowFreeText: boolean;+ /** A single durable interaction may own several independently graded items. */+ questions?: MasteryQuestion[];visual?: { task: string; answerCues: string; keyStatus: string; hintsUsed: number; pixelsInspected?: boolean; sources: { imageUrl: string; url: string; sourcePath: string; page: number | null }[] };}@@ -56,6 +60,12 @@ export interface MasteryGradeResult {explanation: string;result?: string;independent?: boolean;+ results?: MasteryGradeResult[];+}++export interface MasteryAnswerRejection {+ questionId: string;+ retryKey: string;}function asRecord(value: unknown): Record<string, unknown> | null {@@ -73,6 +83,20 @@ function parseQuestion(value: unknown): MasteryQuestion | null {if (!raw) return null;const questionId = text(raw.question_id).trim();if (!questionId) return null;+ let questions: MasteryQuestion[] | undefined;+ if (raw.question_type === "group") {+ if (!Array.isArray(raw.questions) || raw.questions.length < 2 || raw.questions.length > 4)+ return null;+ // Reject the whole envelope, not just a broken child: silently dropping an+ // item would make the displayed answer contract differ from the server's.+ if (raw.questions.some((entry) => asRecord(entry)?.question_type === "group"))+ return null;+ const parsed = raw.questions.map(parseQuestion);+ if (parsed.some((entry) => !entry)) return null;+ questions = parsed as MasteryQuestion[];+ const ids = questions.map((entry) => entry.questionId);+ if (ids.includes(questionId) || new Set(ids).size !== ids.length) return null;+ }const objective = asRecord(raw.objective);const options = Array.isArray(raw.options)? raw.options@@ -98,6 +122,7 @@ function parseQuestion(value: unknown): MasteryQuestion | null {attempt: Number.isFinite(attempt) && attempt > 0 ? Math.floor(attempt) : 1,options,allowFreeText: raw.allow_free_text !== false,+ ...(questions ? { questions } : {}),...(visual ? { visual: { task: text(visual.task), answerCues: text(visual.answer_cues), keyStatus: text(visual.key_status), hintsUsed: Number(visual.hints_used) || 0, pixelsInspected: visual.pixels_inspected === true, sources: visualSources } } : {}),};}@@ -107,6 +132,10 @@ function parseGrade(value: unknown): MasteryGradeResult | null {if (!raw) return null;const questionId = text(raw.question_id).trim();if (!questionId) return null;+ const results = raw.question_type === "group" && Array.isArray(raw.results)+ ? raw.results.filter((entry) => asRecord(entry)?.question_type !== "group")+ .map(parseGrade).filter((entry): entry is MasteryGradeResult => entry !== null)+ : undefined;return {questionId,isCorrect: raw.is_correct === true,@@ -116,6 +145,7 @@ function parseGrade(value: unknown): MasteryGradeResult | null {explanation: text(raw.explanation),...(text(raw.result) ? { result: text(raw.result) } : {}),...(typeof raw.independent === "boolean" ? { independent: raw.independent } : {}),+ ...(results ? { results } : {}),};}@@ -190,7 +220,10 @@ export function collectMasteryGrades(toolResultPayload(event.metadata, "mastery_grade"),);const grade = parseGrade(payload?.result);- if (grade) grades.set(grade.questionId, grade);+ if (grade) {+ grades.set(grade.questionId, grade);+ for (const child of grade.results ?? []) grades.set(child.questionId, child);+ }}}return grades;@@ -222,3 +255,24 @@ export function collectMasterySkips(}return skipped;}++/** Server rejection is not a grade; it only reopens a still-pending card. */+export function collectMasteryAnswerRejections(+ messages: Array<{ events?: StreamEvent[] }>,+): Map<string, MasteryAnswerRejection> {+ const rejected = new Map<string, MasteryAnswerRejection>();+ for (const message of messages) {+ for (const event of message.events ?? []) {+ if (event.type !== "tool_result") continue;+ const payload = asRecord(toolResultPayload(event.metadata, "mastery_answer_rejected"));+ const questionId = text(payload?.question_id).trim();+ if (!questionId) continue;+ const metadata = asRecord(event.metadata);+ rejected.set(questionId, {+ questionId,+ retryKey: text(metadata?.call_id) || `${event.turn_id}:${event.seq}`,+ });+ }+ }+ return rejected;+}diff --git a/web/locales/de/app.json b/web/locales/de/app.jsonindex d5fac6c89..2ae3560ac 100644--- a/web/locales/de/app.json+++ b/web/locales/de/app.json@@ -1,4 +1,5 @@{+ "These answers could not be submitted. Please review or retry.": "Diese Antworten konnten nicht übermittelt werden. Bitte prüfen und erneut versuchen.","Review rebuild": "Neuaufbau überprüfen","language.english": "Englisch","language.chinese": "Chinesisch",diff --git a/web/locales/en/app.json b/web/locales/en/app.jsonindex ccc6056b8..57e2c9e2e 100644--- a/web/locales/en/app.json+++ b/web/locales/en/app.json@@ -1,4 +1,5 @@{+ "These answers could not be submitted. Please review or retry.": "These answers could not be submitted. Please review or retry.","Review rebuild": "Review rebuild","language.english": "English","language.chinese": "中文",diff --git a/web/locales/fr/app.json b/web/locales/fr/app.jsonindex 29ff4e9f4..59e101628 100644--- a/web/locales/fr/app.json+++ b/web/locales/fr/app.json@@ -1,4 +1,5 @@{+ "These answers could not be submitted. Please review or retry.": "Ces réponses n’ont pas pu être envoyées. Veuillez les vérifier ou réessayer.","language.english": "English","language.chinese": "中文","language.french": "Français",diff --git a/web/locales/pl/app.json b/web/locales/pl/app.jsonindex 43806081a..46ff6ca7a 100644--- a/web/locales/pl/app.json+++ b/web/locales/pl/app.json@@ -1,4 +1,5 @@{+ "These answers could not be submitted. Please review or retry.": "Nie udało się przesłać tych odpowiedzi. Sprawdź je lub spróbuj ponownie.","Review rebuild": "Przegląd przebudowy","language.english": "Angielski","language.chinese": "中文",diff --git a/web/locales/uk/app.json b/web/locales/uk/app.jsonindex a75d39e50..1b5dbadcc 100644--- a/web/locales/uk/app.json+++ b/web/locales/uk/app.json@@ -1,4 +1,5 @@{+ "These answers could not be submitted. Please review or retry.": "Не вдалося надіслати ці відповіді. Перевірте їх або спробуйте ще раз.","language.english": "Англійська","language.chinese": "Китайська","language.french": "Français",diff --git a/web/locales/zh/app.json b/web/locales/zh/app.jsonindex ab2861866..d8d13206c 100644--- a/web/locales/zh/app.json+++ b/web/locales/zh/app.json@@ -1,4 +1,5 @@{+ "These answers could not be submitted. Please review or retry.": "这些答案未能提交。请检查后重试。","Review rebuild": "查看重建配置","language.english": "English","language.chinese": "中文",diff --git a/web/tests/mastery-question-group.spec.tsx b/web/tests/mastery-question-group.spec.tsxnew file mode 100644index 000000000..7e2221571--- /dev/null+++ b/web/tests/mastery-question-group.spec.tsx@@ -0,0 +1,234 @@+import { fireEvent, render, screen } from "@testing-library/react";+import userEvent from "@testing-library/user-event";+import { describe, expect, it, vi } from "vitest";++import { MasteryQuestionCard } from "@/components/chat/home/MasteryQuestionCard";+import { ChatMessageList } from "@/features/chat/messages";+import type { StreamEvent } from "@/features/chat/model/protocol";+import { initI18n } from "@/i18n/init";+import {+ collectMasteryGrades,+ extractMasteryQuestion,+} from "@/lib/mastery-question";++initI18n("en");++const leaf = (id: string) => ({+ question_id: id,+ prompt: id === "part-a" ? "Select the matching description." : "Explain the distinction.",+ question_type: id === "part-a" ? "choice" : "short",+ objective: { id: `objective-${id}`, name: `Objective ${id}` },+ difficulty: "easy",+ attempt: 1,+ options: id === "part-a" ? [{ label: "A", body: "Matching description" }] : [],+ allow_free_text: true,+});++const group = {+ question_id: "group-1",+ question_type: "group",+ prompt: "Answer both parts.",+ questions: [leaf("part-a"), leaf("part-b")],+};++const event = (payload: Record<string, unknown>): StreamEvent => ({+ type: "tool_result", source: "mastery", stage: "responding", content: "",+ metadata: { tool_metadata: payload }, session_id: "session-1",+ turn_id: "turn-1", seq: 1, timestamp: 0,+});++const question = () => extractMasteryQuestion([event({ mastery_question: group })])!;++describe("grouped mastery assessment", () => {+ it("normalizes two independent questions and drops private keys", () => {+ const normalized = question();+ expect(normalized).toMatchObject({+ questionId: "group-1", questionType: "group",+ questions: [{ questionId: "part-a" }, { questionId: "part-b" }],+ });+ const withPrivateKeys = extractMasteryQuestion([event({ mastery_question: {+ ...group, expected_answer: "private parent key",+ questions: group.questions.map((part) => ({ ...part, expected_answer: "private child key" })),+ } })]);+ expect(JSON.stringify(withPrivateKeys)).not.toContain("private");+ });++ it("rejects duplicate, nested, or incomplete group identities", () => {+ for (const questions of [[leaf("part-a")], [leaf("part-a"), leaf("part-a")],+ [leaf("part-a"), group]]) {+ expect(extractMasteryQuestion([event({ mastery_question: { ...group, questions } })])).toBeNull();+ }+ });++ it("requires both answers and sends one submission with stable child IDs", async () => {+ const user = userEvent.setup();+ const onSubmit = vi.fn(() => true);+ render(<MasteryQuestionCard question={question()} grade={null} answered={false}+ submittedAnswer="" onSubmit={onSubmit} />);+ const submit = screen.getByRole("button", { name: "Submit" });+ expect(submit).toBeDisabled();+ await user.click(screen.getByRole("button", { name: /Matching description/ }));+ expect(submit).toBeDisabled();+ await user.type(screen.getByRole("textbox"), "They have different roles");+ expect(submit).toBeEnabled();+ await user.click(submit);+ expect(onSubmit).toHaveBeenCalledExactlyOnceWith({+ text: "1. A\n2. They have different roles",+ answers: [+ { questionId: "part-a", text: "A" },+ { questionId: "part-b", text: "They have different roles" },+ ],+ });+ });++ it("retains both answers when delivery fails and allows a retry", async () => {+ const user = userEvent.setup();+ const onSubmit = vi.fn().mockResolvedValueOnce(false).mockResolvedValueOnce(true);+ render(<MasteryQuestionCard question={question()} grade={null} answered={false}+ submittedAnswer="" onSubmit={onSubmit} />);+ await user.click(screen.getByRole("button", { name: /Matching description/ }));+ await user.type(screen.getByRole("textbox"), "Retained answer");+ await user.click(screen.getByRole("button", { name: "Submit" }));+ expect(screen.getByRole("textbox")).toHaveValue("Retained answer");+ expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled();+ await user.click(screen.getByRole("button", { name: "Submit" }));+ expect(onSubmit).toHaveBeenCalledTimes(2);+ expect(onSubmit.mock.calls[1]).toEqual(onSubmit.mock.calls[0]);+ });++ it("reconstructs independent mixed verdicts on reload, without an editable parent", () => {+ const grades = collectMasteryGrades([{ events: [event({ mastery_grade: {+ result: { question_id: "group-1", question_type: "group", is_correct: false,+ results: [+ { question_id: "part-a", is_correct: true, learner_answer: "A", correct_label: "A", explanation: "First part understood." },+ { question_id: "part-b", is_correct: false, learner_answer: "Incorrect distinction", explanation: "Second part needs correction." },+ ] },+ } })] }]);+ expect(grades.get("part-a")?.isCorrect).toBe(true);+ expect(grades.get("part-b")?.isCorrect).toBe(false);+ const { unmount } = render(<MasteryQuestionCard question={question()} grade={grades.get("group-1")!}+ answered submittedAnswer="" onSubmit={() => true} />);+ expect(screen.getByText("Correct")).toBeInTheDocument();+ expect(screen.getByText("Not quite")).toBeInTheDocument();+ expect(screen.queryByRole("button", { name: "Submit" })).toBeNull();+ expect(screen.queryByRole("textbox")).toBeNull();+ unmount();+ render(<MasteryQuestionCard question={question()} grade={grades.get("group-1")!}+ answered submittedAnswer="" onSubmit={() => true} />);+ expect(screen.getByText("First part understood.")).toBeInTheDocument();+ expect(screen.getByText("Second part needs correction.")).toBeInTheDocument();+ });++ it("skips the parent once, not each child", async () => {+ const user = userEvent.setup();+ const onSkip = vi.fn(() => true);+ render(<MasteryQuestionCard question={question()} grade={null} answered={false}+ submittedAnswer="" onSubmit={() => true} onSkip={onSkip} />);+ expect(screen.getAllByRole("button", { name: "Skip this one" })).toHaveLength(1);+ await user.click(screen.getByRole("button", { name: "Skip this one" }));+ expect(onSkip).toHaveBeenCalledExactlyOnceWith("group-1");+ });++ it("keeps a failed source image from submitting the group", async () => {+ const user = userEvent.setup();+ const visualGroup = extractMasteryQuestion([event({ mastery_question: {+ ...group, questions: [group.questions[0], { ...group.questions[1], visual: {+ task: "identification", key_status: "verified", answer_cues: "none", sources: [+ { image_url: "/api/knowledge-bases/k/visual-assets/i", url: "/api/knowledge-bases/k/files/book.pdf", source_path: "book.pdf", page: 1 },+ ],+ } }],+ } })])!;+ render(<MasteryQuestionCard question={visualGroup} grade={null} answered={false}+ submittedAnswer="" onSubmit={() => true} />);+ await user.click(screen.getByRole("button", { name: /Matching description/ }));+ await user.type(screen.getByRole("textbox"), "Answer");+ expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled();+ fireEvent.error(screen.getByRole("img"));+ expect(screen.getByRole("button", { name: "Submit" })).toBeDisabled();+ });++ it("forwards both answer IDs through the actual message list callback", async () => {+ const user = userEvent.setup();+ const onAnswer = vi.fn(() => true);+ render(<ChatMessageList messages={[{ id: 1, role: "assistant", content: "",+ parentMessageId: null, capability: "mastery_path", events: [event({ mastery_question: group })] }]}+ isStreaming={false} onCopyAssistantMessage={async () => undefined}+ onRegenerateMessage={() => undefined} onAnswerMasteryQuestion={onAnswer} />);+ await user.click(screen.getByRole("button", { name: /Matching description/ }));+ await user.type(screen.getByRole("textbox"), "Callback answer");+ await user.click(screen.getByRole("button", { name: "Submit" }));+ expect(onAnswer).toHaveBeenCalledExactlyOnceWith({+ questionId: "group-1", text: "1. A\n2. Callback answer",+ answers: [{ questionId: "part-a", text: "A" }, { questionId: "part-b", text: "Callback answer" }],+ });+ });++ it("challenges each graded leaf, never the aggregate parent", async () => {+ const user = userEvent.setup();+ const onChallenge = vi.fn(() => true);+ render(<MasteryQuestionCard question={question()} grade={{+ questionId: "group-1", isCorrect: false, learnerAnswer: "", correctLabel: "", correctBody: "", explanation: "",+ results: [+ { questionId: "part-a", isCorrect: true, learnerAnswer: "A", correctLabel: "A", correctBody: "", explanation: "Confirmed." },+ { questionId: "part-b", isCorrect: false, learnerAnswer: "Tentative", correctLabel: "", correctBody: "", explanation: "Evidence uncertain.", result: "ungraded" },+ ],+ }} answered submittedAnswer="" onSubmit={() => true} onChallenge={onChallenge} />);+ expect(screen.getByText("Correct")).toBeInTheDocument();+ expect(screen.getByText("Ungraded — mastery unchanged")).toBeInTheDocument();+ expect(screen.queryByText("Not quite")).toBeNull();+ const buttons = screen.getAllByRole("button", { name: "Review or challenge this assessment" });+ expect(buttons).toHaveLength(2);+ await user.click(buttons[0]);+ await user.click(buttons[1]);+ expect(onChallenge.mock.calls).toEqual([["part-a"], ["part-b"]]);+ });++ it("reopens an optimistically sent group for each real backend rejection event", async () => {+ const user = userEvent.setup();+ const onAnswer = vi.fn(() => true);+ const posed = { id: 1, role: "assistant" as const, content: "", parentMessageId: null,+ capability: "mastery_path", events: [event({ mastery_question: group })] };+ const rejection = (turnId: string): StreamEvent => ({+ ...event({ mastery_answer_rejected: { question_id: "group-1",+ message: "These answers could not be submitted. Please review or retry." } }),+ turn_id: turnId, metadata: { call_id: `mastery-grade-${turnId}-group-1`,+ tool_metadata: { mastery_answer_rejected: { question_id: "group-1",+ message: "These answers could not be submitted. Please review or retry." } } },+ });+ const conversation = (events: StreamEvent[]) => <ChatMessageList messages={[posed,+ { id: 2, role: "assistant", content: "", parentMessageId: 1,+ capability: "mastery_path", events }]}+ isStreaming={false} onCopyAssistantMessage={async () => undefined}+ onRegenerateMessage={() => undefined} onAnswerMasteryQuestion={onAnswer} />;+ const { rerender } = render(conversation([]));+ await user.click(screen.getByRole("button", { name: /Matching description/ }));+ await user.type(screen.getByRole("textbox"), "Preserved despite rejection");+ await user.click(screen.getByRole("button", { name: "Submit" }));+ expect(screen.getByRole("button", { name: "Submit" })).toBeDisabled();++ rerender(conversation([rejection("retry-1")]));+ expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled();+ expect(screen.getByText("These answers could not be submitted. Please review or retry.")).toBeInTheDocument();+ expect(screen.getByRole("textbox")).toHaveValue("Preserved despite rejection");+ await user.click(screen.getByRole("button", { name: "Submit" }));+ expect(screen.getByRole("button", { name: "Submit" })).toBeDisabled();++ rerender(conversation([rejection("retry-1"), rejection("retry-2")]));+ expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled();+ await user.click(screen.getByRole("button", { name: "Submit" }));+ expect(onAnswer).toHaveBeenCalledTimes(3);+ expect(onAnswer.mock.calls[2]).toEqual(onAnswer.mock.calls[0]);++ const success = event({ mastery_grade: { result: {+ question_id: "group-1", question_type: "group", is_correct: true,+ results: [+ { question_id: "part-a", is_correct: true, learner_answer: "A", explanation: "First confirmed." },+ { question_id: "part-b", is_correct: true, learner_answer: "Preserved despite rejection", explanation: "Second confirmed." },+ ],+ } } });+ rerender(conversation([rejection("retry-1"), rejection("retry-2"), success]));+ expect(screen.queryByRole("button", { name: "Submit" })).toBeNull();+ expect(screen.getAllByText("Correct")).toHaveLength(2);+ expect(screen.queryByText("These answers could not be submitted. Please review or retry.")).toBeNull();+ });+});