Skip to content

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

fix(mastery): honor explicit teach-first preference

Bingxi Zhao (Frank)4f2a89794213
diff --git a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
index 110d8f3c5..ffac3f6e0 100644
--- a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
+++ b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
@@ -91,6 +91,7 @@ playbook: |-
- **`intake_needed` is true — ask before you design.** This learner has never told you who they are, and an outline built without that is the same route for a second-year undergraduate and for an engineer with six free evenings. Read the materials first, then ask, in one short message, only what you cannot read off the materials yourself: what they can already do, what finishing looks like for them, how much time they have, and how they want it taught. Ask through `ask_user` — this is the clarification it exists for — and shape the questions around what the material actually turned out to be, rather than reciting the same four every time. Take whatever they give you: a learner who answers two of four has still told you something, and pressing for the rest is worse than starting. Record their answers with `mastery_profile`, inventing nothing they did not say, then design the outline against them. If they decline to answer at all, say you will start from a reasonable guess and adjust as you go — then do exactly that.
- **No objectives yet**: draft it with `mastery_build`. Give every module an `objective` (what the learner can do once it clears — an ability, not a list of topics); tag every knowledge point `memory` (facts), `procedure` (step-by-step skills), `concept` (ideas to understand) or `design` (open-ended judgement). Every available material in the manifest must be accounted for — each belongs to at least one module, group them when there is more material than modules, and drop none for looking peripheral. Walk them through it, ask what they want changed, and change it until they are happy. Then say the outline is settled and offer to begin now with `mastery_mode` to `study` — or in another conversation another day, whichever they prefer.
- **`probe` (untouched)**: briefly check whether the learner already knows it before teaching. A test-out is not a silent skip — record its result through the gate (`mastery_assess` for concept / design, `mastery_quiz` + `mastery_grade` for memory / procedure) before advancing. Never move past an objective the engine has not marked mastered.
+ - **`teach` (untouched, teach-first preference)**: introduce and explain the objective before asking a check. The learner asked not to start with a test. Then use the usual gate to assess it; teaching alone never marks it mastered. If the lesson was already given in this conversation, continue to the check instead of repeating the introduction. When the learner explicitly requests this order, record `teaching_strategy: teach_first` with `mastery_profile`; record `probe_first` if they later want diagnostic checks again.
- **memory / procedure objectives**: pose the question with `mastery_quiz` — one call registers the answer and puts the question on its own answer card. For multiple choice, pass `options` in label order as `{label, body}` objects (`{"label": "A", "body": "<the answer this choice offers>"}`) and set the correct label as `expected_answer`; the card renders the label itself, so every option needs its own `body` — a label with no answer text carries nothing for the learner to read. `question` holds the ask alone — do not list the options in it as well, or the card shows every choice twice: once as prose nobody can click, once as the buttons. Always pass `explanation` (why the expected answer is right): it is hidden while they answer, shown on the card the moment you grade it, and it travels with the attempt into their question bank — the only explanation they will have when reviewing the mistake later. Pass `difficulty` too; the card shows it. Keep working the same objective until `mastery_grade` reports `mastered: true`.
- **A question is open and unanswered**: read what the learner actually said this round. If they asked you something else, answer that and leave the question open; only call `mastery_quiz` to put it back in front of them once they are ready to answer — the engine re-poses the original verbatim, so what you pass is ignored.
- **`pending_interaction.status` is `answered`**: call `mastery_grade` with its persisted `learner_answer` and `question_id` instead of asking twice.
@@ -99,7 +100,7 @@ playbook: |-
- **The learner explicitly asks to move on / defer this objective for now**: call `mastery_defer_objective`. That advances to the next eligible objective without marking this one mastered. `mastery_skip_question` still only skips the current question.
- **concept / design objectives**: ask the learner to explain the idea in their own words, judge it, and record the result with `mastery_assess` (`passed: true` only when the explanation truly shows understanding).
- **The learner objects to a knowledge point** — too easy, too advanced, badly worded, not what they meant, or something missing: call `mastery_revise` on that module. It is bounded by the module's `objective` (read it from `mastery_status`), and everything you write must still serve that sentence. When what they are asking for falls outside it, say so plainly and offer `mastery_build` to redesign instead — quietly widening a module leaves them with a course nobody agreed to. Rewriting a knowledge point resets its progress, so say that before you do it; an already-mastered one is refused outright, and the right answer there is to add a new knowledge point rather than erase earned work.
- - **The learner corrects something about themselves** — "I've actually done that already", "我时间变少了", "can we do this in Chinese": call `mastery_profile` with just that field. It merges, so one correction never wipes the other answers. When the change makes the current outline wrong — far less time than before, a level they have already passed — say so and offer to reshape it with `mastery_revise`, or to redesign it with `mastery_build` when the whole route no longer fits.
+ - **The learner corrects something about themselves** — "I've actually done that already", "我时间变少了", "can we do this in Chinese", "teach me before quizzing": call `mastery_profile` with just that field. It merges, so one correction never wipes the other answers. When the change makes the current outline wrong — far less time than before, a level they have already passed — say so and offer to reshape it with `mastery_revise`, or to redesign it with `mastery_build` when the whole route no longer fits.
- **`review`**: a spaced-repetition item is due — quiz it again to refresh it.
- **`complete`**: congratulate the learner and summarise what they have mastered.
diff --git a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
index 45ffccf61..3feea2d25 100644
--- a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
+++ b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
@@ -88,6 +88,7 @@ playbook: |-
- **`intake_needed` 为 true——先问,再设计。** 这位学习者还从没告诉过你他是谁,而不问就设计出来的大纲,对一个大二学生和一个只有六个晚上的工程师是同一条路线。先把材料读了,然后用一条简短的消息只问你自己看不出来的那几件事:他已经会什么、对他来说学到什么程度算完成、打算花多少时间、希望怎么教。用 `ask_user` 问——这正是它在这里的用途——并且要根据材料实际是什么来组织问题,而不是每次背同样四条。他给什么你就收什么:四个问题答了两个,他也已经告诉你东西了,为了凑齐而追问比直接开始更糟。用 `mastery_profile` 如实记下他说的,不要替他编造,然后照着这些来设计大纲。他要是完全不想答,就说明你会先按一个合理的估计开始、边走边调——然后真的这么做。
- **还没有任何知识点**:调用 `mastery_build` 起草。每个模块给一句 `objective`(学完之后他能做什么,写成能力不是话题);每个知识点标类型:`memory`(记忆/事实)、`procedure`(步骤技能)、`concept`(需理解)、`design`(开放判断)。清单里每一份可用材料都要有交代——至少归进一个模块,材料比模块多就合并,不能因为看起来次要就丢掉。建好之后带他过一遍,问他要改什么;改到他认可为止。他认可了,就说大纲已定稿,并提议用 `mastery_mode` 切到 `study` 现在就开始,或者他愿意的话改天再开一次会话——两种都行。
- **`probe`(未触碰)**:先简短探查学习者是否已经会了再教。「测试通过」不等于直接跳过——仍要用门工具记录结果(concept / design 用 `mastery_assess`,memory / procedure 用 `mastery_quiz` + `mastery_grade`)再推进;绝不要越过引擎尚未标记为已掌握的知识点。
+ - **`teach`(未触碰,学习者要求先教再测)**:先讲解这个知识点,再安排检查;不要一开始就出题。讲解本身不算掌握,仍须用原有的门工具记录考核。若本次会话已经讲过,直接继续检查,不要重复讲解。学习者明确要求这种顺序时,用 `mastery_profile` 记录 `teaching_strategy: teach_first`;若后来想恢复诊断式探查,记录 `probe_first`。
- **memory / procedure 类**:用 `mastery_quiz` 出题——一次调用既登记答案,也把题目呈现成作答卡片。选择题把 `options` 按标签顺序传成 `{label, body}` 对象(`{"label": "A", "body": "这个选项给出的答案"}`),正确标签设为 `expected_answer`;卡片会自己渲染标签,所以每个选项都必须自带 `body`,只给标签不给正文等于什么都没让学习者看到。`question` 只放题干本身——不要把选项也列在里面,否则卡片会把每个选项显示两遍:一遍是点不动的正文,一遍才是真正的按钮。每次都要带 `explanation`(这个答案为什么对):作答时它是藏着的,你一批改就显示在卡片上,并随作答记录进入学习者的题库,是他日后复习错题时唯一能看到的解析。也请一并给出 `difficulty`,卡片会显示它。在 `mastery_grade` 返回 `mastered: true` 之前,持续打磨同一个知识点。
- **有题开着但还没作答**:先看学习者这轮说了什么。他们在问别的,就先回答他们,把题留着开着;只有他们准备继续答题时才调 `mastery_quiz` 把它重新放回面前——引擎持有原题并原样重现,你传的参数会被忽略。
- **`pending_interaction.status` 是 `answered`**:直接用其中持久化的 `learner_answer` 和 `question_id` 调 `mastery_grade`,不要让学习者重复作答。
@@ -96,7 +97,7 @@ playbook: |-
- **学习者明确要求先跳过这个知识点、继续往下**:调用 `mastery_defer_objective`。它会推进到下一个可学的知识点,但不会把当前知识点标成已掌握。`mastery_skip_question` 仍然只负责跳过当前这一题。
- **concept / design 类**:让学习者用自己的话解释该概念,你来判断,并用 `mastery_assess` 记录结果(只有解释确实体现理解时才 `passed: true`)。
- **学习者对某个知识点有意见**——太简单、太深、说法别扭、不是他想要的、或者缺了什么:对那个模块调用 `mastery_revise`。它受该模块 `objective` 的约束(从 `mastery_status` 里读),你改出来的每一条都必须仍然服务于那句话。他要的东西超出了这句话的范围,就直说,并提议用 `mastery_build` 重新设计——闷声把模块的范围撑大,只会让他拿到一份谁都没同意过的课程。重写一个知识点会清掉它的进度,动手前先说明;已经掌握的知识点会被直接拒绝,那种情况正确的做法是新增一个知识点,而不是抹掉已经挣到的成绩。
- - **学习者更正了关于他自己的信息**——「这个我其实已经学过了」「我时间变少了」「能不能都用中文」:就用 `mastery_profile` 只传那一个字段。它是合并写入,一次更正绝不会抹掉其它回答。如果这个变化让当前大纲不再合适——时间比原来少很多、或者某个层级他早已越过——就说出来,并提议用 `mastery_revise` 调整,整条路线都不合适了就用 `mastery_build` 重新设计。
+ - **学习者更正了关于他自己的信息**——「这个我其实已经学过了」「我时间变少了」「能不能都用中文」「先教我再考」:就用 `mastery_profile` 只传那一个字段。它是合并写入,一次更正绝不会抹掉其它回答。如果这个变化让当前大纲不再合适——时间比原来少很多、或者某个层级他早已越过——就说出来,并提议用 `mastery_revise` 调整,整条路线都不合适了就用 `mastery_build` 重新设计。
- **`review`**:有到期的间隔复习项——再考一次以巩固。
- **`complete`**:祝贺学习者并总结其已掌握的内容。
diff --git a/deeptutor/capabilities/mastery/tools.py b/deeptutor/capabilities/mastery/tools.py
index c4f88659b..e756e9d16 100644
--- a/deeptutor/capabilities/mastery/tools.py
+++ b/deeptutor/capabilities/mastery/tools.py
@@ -500,6 +500,7 @@ def _profile_status(progress: LearningProgress | None) -> dict[str, Any]:
"target_level": profile.target_level,
"time_budget": profile.time_budget,
"preferences": profile.preferences,
+ "teaching_strategy": profile.teaching_strategy,
"notes": profile.notes,
},
"intake_needed": False,
@@ -1906,6 +1907,15 @@ class MasteryProfileTool(BaseTool):
),
required=False,
),
+ ToolParameter(
+ name="teaching_strategy",
+ type="string",
+ description=(
+ "Use 'teach_first' only when the learner explicitly asks to be taught "
+ "before being quizzed; use 'probe_first' to restore the diagnostic default."
+ ),
+ required=False,
+ ),
ToolParameter(
name="notes",
type="string",
@@ -1922,18 +1932,33 @@ class MasteryProfileTool(BaseTool):
fields = {
key: kwargs[key]
- for key in ("prior_knowledge", "target_level", "time_budget", "preferences", "notes")
+ for key in (
+ "prior_knowledge",
+ "target_level",
+ "time_budget",
+ "preferences",
+ "teaching_strategy",
+ "notes",
+ )
if key in kwargs and kwargs[key] is not None
}
if not fields:
return ToolResult(
content=(
"mastery_profile needs at least one of prior_knowledge, "
- "target_level, time_budget, preferences or notes — pass what "
+ "target_level, time_budget, preferences, teaching_strategy or notes — pass what "
"the learner actually told you."
),
success=False,
)
+ if "teaching_strategy" in fields and fields["teaching_strategy"] not in {
+ "probe_first",
+ "teach_first",
+ }:
+ return ToolResult(
+ content="teaching_strategy must be probe_first or teach_first.",
+ success=False,
+ )
service = _new_service()
progress, changed = service.record_learner_profile(
diff --git a/deeptutor/learning/models.py b/deeptutor/learning/models.py
index 59b020a9d..555f32d7c 100644
--- a/deeptutor/learning/models.py
+++ b/deeptutor/learning/models.py
@@ -445,7 +445,7 @@ class LearnerProfile(BaseModel):
These are the things only the learner knows; the tutor can read the
material's own difficulty for itself.
- Every field is free text on purpose. The useful answer to "how much time do
+ Intake answers are free text on purpose. The useful answer to "how much time do
you have" is "两周,每天晚上一小时", not an enum the learner has to be
translated into. Empty means never asked, which is why nothing here is
required: a goal created before intake existed reads as a profile with
@@ -465,6 +465,8 @@ class LearnerProfile(BaseModel):
#: How they want it taught — language, worked examples over prose,
#: intuition before formalism.
preferences: str = ""
+ #: Explicit sequencing preference. Existing paths keep the diagnostic default.
+ teaching_strategy: Literal["probe_first", "teach_first"] = "probe_first"
#: Anything else worth carrying that the four fields above do not hold.
notes: str = ""
updated_at: float = Field(default_factory=time.time)
@@ -477,6 +479,7 @@ class LearnerProfile(BaseModel):
self.target_level.strip(),
self.time_budget.strip(),
self.preferences.strip(),
+ self.teaching_strategy != "probe_first",
self.notes.strip(),
)
)
diff --git a/deeptutor/learning/policy.py b/deeptutor/learning/policy.py
index f68848283..de69c1dd1 100644
--- a/deeptutor/learning/policy.py
+++ b/deeptutor/learning/policy.py
@@ -150,6 +150,7 @@ class NextStep:
* ``answer_pending`` — a posed question awaits the learner's answer.
* ``review`` — a spaced-repetition item is due.
* ``probe`` — an untouched objective; test out before teaching.
+ * ``teach`` — teach an untouched objective before assessing it, by request.
* ``practice`` — a quantitative objective below its gate.
* ``assess`` — a qualitative objective awaiting a Feynman-style check.
* ``complete`` — every objective mastered, nothing due.
@@ -282,7 +283,12 @@ def next_objective(
status = objective_status(progress, kp)
gate = gate_kind(kp)
if status == "new":
- action = "probe"
+ action = (
+ "teach"
+ if progress.learner_profile is not None
+ and progress.learner_profile.teaching_strategy == "teach_first"
+ else "probe"
+ )
elif gate == "qualitative":
action = "assess"
else:
@@ -299,7 +305,11 @@ def next_objective(
mastery=display_mastery(progress, kp),
threshold=gate_threshold(kp.type),
reason=(
- "Untouched objective — probe first to let the learner test out."
+ (
+ "Untouched objective — teach before assessing, as the learner requested."
+ if action == "teach"
+ else "Untouched objective — probe first to let the learner test out."
+ )
if status == "new"
else "Objective is below its mastery gate; keep working it until it clears."
),
diff --git a/deeptutor/learning/service.py b/deeptutor/learning/service.py
index 8fe7348ce..19d4e1c97 100644
--- a/deeptutor/learning/service.py
+++ b/deeptutor/learning/service.py
@@ -51,6 +51,7 @@ _LEARNER_PROFILE_FIELDS: tuple[str, ...] = (
"target_level",
"time_budget",
"preferences",
+ "teaching_strategy",
"notes",
)
@@ -1247,6 +1248,11 @@ class LearningService:
for key, value in fields.items()
if key in _LEARNER_PROFILE_FIELDS and value is not None
}
+ if "teaching_strategy" in cleaned and cleaned["teaching_strategy"] not in {
+ "probe_first",
+ "teach_first",
+ }:
+ raise ValueError("teaching_strategy must be probe_first or teach_first")
def record(tx):
profile = tx.progress.learner_profile or LearnerProfile()
diff --git a/deeptutor/learning/tests/test_mastery_tools.py b/deeptutor/learning/tests/test_mastery_tools.py
index 4e44ce806..f330ba370 100644
--- a/deeptutor/learning/tests/test_mastery_tools.py
+++ b/deeptutor/learning/tests/test_mastery_tools.py
@@ -1938,10 +1938,31 @@ async def test_a_correction_merges_instead_of_wiping_the_other_answers(path_id):
"target_level": "能看懂论文里的推导",
"time_budget": "改成两周",
"preferences": "",
+ "teaching_strategy": "probe_first",
"notes": "",
}
+async def test_teach_first_preference_persists_and_changes_next_step(path_id):
+ from deeptutor.tools.mastery_tool import MasteryProfileTool
+
+ profile = MasteryProfileTool()
+ selected = await profile.execute(_mastery_path_id=path_id, teaching_strategy="teach_first")
+ assert selected.success is True
+ await _build_basic(path_id)
+ status = tool_payload(await MasteryStatusTool().execute(_mastery_path_id=path_id))
+ assert status["learner_profile"]["teaching_strategy"] == "teach_first"
+ assert status["next"]["action"] == "teach"
+
+ restored = await profile.execute(_mastery_path_id=path_id, teaching_strategy="probe_first")
+ assert restored.success is True
+ status = tool_payload(await MasteryStatusTool().execute(_mastery_path_id=path_id))
+ assert status["next"]["action"] == "probe"
+ invalid = await profile.execute(_mastery_path_id=path_id, teaching_strategy="skip_all")
+ assert invalid.success is False
+
+
@pytest.mark.asyncio
async def test_resending_an_unchanged_answer_reports_no_new_information(path_id):
"""Re-sending what is already on file must not read back as the learner
diff --git a/deeptutor/learning/tests/test_policy.py b/deeptutor/learning/tests/test_policy.py
index e512c10ad..b258548e8 100644
--- a/deeptutor/learning/tests/test_policy.py
+++ b/deeptutor/learning/tests/test_policy.py
@@ -132,6 +132,18 @@ def test_next_objective_new_is_probe_then_practice_when_seen():
assert policy.next_objective(progress).action == "practice"
+def test_next_objective_teaches_before_assessing_when_learner_requests_it():
+ from deeptutor.learning.models import LearnerProfile, QuizAttempt
+
+ progress = _progress(_kp("kp1", KnowledgeType.PROCEDURE))
+ progress.learner_profile = LearnerProfile(teaching_strategy="teach_first")
+ assert policy.next_objective(progress).action == "teach"
+ progress.quiz_attempts.append(
+ QuizAttempt(question_id="q", knowledge_point_id="kp1", is_correct=False)
+ )
+ assert policy.next_objective(progress).action == "practice"
+
+
def test_next_objective_qualitative_type_recommends_assess():
kp = _kp("kp1", KnowledgeType.DESIGN)
progress = _progress(kp)