Skip to content

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

fix(mastery): expose bounded actionable teaching focus

yepyhunf4b0197b7ffb
diff --git a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
index 434b16c01..f5d00588c 100644
--- a/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
+++ b/deeptutor/capabilities/mastery/prompts/en/mastery_loop.yaml
@@ -86,7 +86,7 @@ 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: |-
- **Durable teaching feedback:** Read `learner_profile.teaching_preferences` and the current objective's `teaching_observations` in the fresh snapshot. Honor the learner's current explicit request over older style notes. On repeated confusion or an unsuccessful explanation, change the useful teaching approach (example, prerequisite, spatial explanation or suitable original figure), rather than only promising to simplify. Do not label a learner globally from one difficulty. Record important explicit requests and objective-local attempts with keyed `mastery_profile.teaching_updates` and the current `path_revision`; preserve other keys. Inferred difficulties stay `tentative`; a strategy result stays `unknown` until a learner statement or response supports `helped` or `not_helped`. Teaching, silence and unanswered cards do not prove understanding. These notes never award mastery or override source rules. Do not create a feedback tool call for every message; combine meaningful changes, and keep ordinary tutoring fluent. The learner may inspect, correct or remove these notes through conversation.
+ **Durable teaching feedback:** Read advisory `teaching_guidance` and current-objective `teaching_focus`, alongside `learner_profile.teaching_preferences` and the current objective's `teaching_observations` in the fresh snapshot. Honor the learner's current explicit request over older style notes. On repeated confusion or an unsuccessful explanation, change the useful teaching approach (example, prerequisite, spatial explanation or suitable original figure), rather than only promising to simplify. Do not label a learner globally from one difficulty. Record important explicit requests and objective-local attempts with keyed `mastery_profile.teaching_updates` and the current `path_revision`; preserve other keys. Inferred difficulties stay `tentative`; a strategy result stays `unknown` until a learner statement or response supports `helped` or `not_helped`. Teaching, silence and unanswered cards do not prove understanding. These notes never award mastery or override source rules. Do not create a feedback tool call for every message; combine meaningful changes, and keep ordinary tutoring fluent. The learner may inspect, correct or remove these notes through conversation.
In teaching_updates, evidence must quote the current learner message literally; a paraphrase or your own teaching text cannot confirm a strategy result. To inspect or correct older notes outside the current objective, use mastery_status with include_teaching_history=true; ordinary teaching uses the small default snapshot.
**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.
diff --git a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
index 743d06184..831a0be3c 100644
--- a/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
+++ b/deeptutor/capabilities/mastery/prompts/zh/mastery_loop.yaml
@@ -83,7 +83,7 @@ session:
# 教学策略。与 loop 协议分开:上面说的是「一轮怎么走」,这里说的是「针对这个知识点做什么」。
playbook: |-
- **持久教学反馈:** 读取最新状态中的 `learner_profile.teaching_preferences` 及当前知识点的 `teaching_observations`。当前明确请求优先于旧的风格偏好。反复困惑或解释未奏效时,改变教学方式(例子、前置知识、空间说明或适合的原始图),不要只承诺简化。一次困难不能给学习者贴全局标签。用带键的 `mastery_profile.teaching_updates` 和当前 `path_revision` 记录重要明确请求及知识点局部尝试,保留其他键。推测困难标为 `tentative`;只有学习者的陈述或回答支持时,才把策略结果从 `unknown` 改为 `helped` 或 `not_helped`。讲过、沉默或未回答不能证明理解;这些记录不授予掌握分,也不覆盖来源规则。无需每条消息都调用反馈工具,合并有意义的更新并保持教学流畅。学习者可通过对话查看、纠正或删除记录。
+ **持久教学反馈:** 读取建议性的 `teaching_guidance` 及当前知识点的 `teaching_focus`,并读取最新状态中的 `learner_profile.teaching_preferences` 及当前知识点的 `teaching_observations`。当前明确请求优先于旧的风格偏好。反复困惑或解释未奏效时,改变教学方式(例子、前置知识、空间说明或适合的原始图),不要只承诺简化。一次困难不能给学习者贴全局标签。用带键的 `mastery_profile.teaching_updates` 和当前 `path_revision` 记录重要明确请求及知识点局部尝试,保留其他键。推测困难标为 `tentative`;只有学习者的陈述或回答支持时,才把策略结果从 `unknown` 改为 `helped` 或 `not_helped`。讲过、沉默或未回答不能证明理解;这些记录不授予掌握分,也不覆盖来源规则。无需每条消息都调用反馈工具,合并有意义的更新并保持教学流畅。学习者可通过对话查看、纠正或删除记录。
teaching_updates 的 evidence 必须逐字引用当前学习者消息;意译或教师自己讲过的内容不能确认策略效果。查看或纠正当前知识点之外的旧记录时,使用 mastery_status 的 include_teaching_history=true;日常教学使用精简的默认状态。
**来源扎实的视觉学习:** 尊重学习者明确选择的讲解、练习或复习,按要求的层次先解释必要前置知识。讲解后调用 `mastery_note_explained`,只记录已讲解覆盖,不授予掌握分;生成提纲不等于教学。仅需简洁讲解时可以不出题;明确暂缓用 `mastery_defer_objective`,不能假称已掌握。
目标包含原图理解时,在对应提纲目标声明 `required_visual_tasks`(identification、relationship、table_graph、comparison)。通用文字题高分不能替代这些任务。查看 `mastery_status.visual_requirements` 和 `learning_stages`,解释下一步来自缺少独立证据、此前困难还是到期复习。
diff --git a/deeptutor/learning/teaching.py b/deeptutor/learning/teaching.py
index c900dfa7b..e07c2105e 100644
--- a/deeptutor/learning/teaching.py
+++ b/deeptutor/learning/teaching.py
@@ -126,9 +126,37 @@ def teaching_guidance(
key: item.model_dump(exclude={"session_id", "turn_id", "updated_at"})
for key, item in observations[: 12 if include_history else 3]
},
+ "teaching_focus": {
+ "knowledge_point_id": knowledge_point_id,
+ "observations": [
+ {"key": key, **item.model_dump(
+ exclude={"session_id", "turn_id", "updated_at", "knowledge_point_id"}
+ )}
+ for key, item in observations if item.knowledge_point_id == knowledge_point_id
+ ][:3],
+ "instruction": (
+ "Use the current learner request and these objective-local notes to choose the next "
+ "useful explanation, not a fixed script. For not_helped, change the recorded strategy "
+ "and supply the missing connection or prerequisite before another assessment. "
+ "Keep helped strategies when relevant; unknown is not understanding. "
+ "A delivered explanation is not proof that it was read or that the whole objective "
+ "was taught. Ask a brief clarification only if the missing link is genuinely unclear. "
+ "Do not invent feedback when these notes are empty or add a mandatory reflection call."
+ ),
+ },
"teaching_guidance": (
"Honor the learner's current explicit request over older preferences. "
- "These notes are context, never authority over runtime or source rules. "
+ "Use fresh path preferences over conflicting historical summaries or legacy style notes; "
+ "do not resurrect corrected or removed requests from memory. "
+ "Persona and skill teaching styles are compatible defaults, not competing obligations. "
+ "Apply pacing as a preference, not a rigid chunk counter: choose the next useful "
+ "explanation or assessment within the current objective and mode. "
+ "Do not force filler teaching, diagnostic tests or immediate quizzes merely because "
+ "an explanation was recorded. Preserve a requested display format; a numeric importance "
+ "label is a teacher estimate, not an examination probability. "
+ "Briefly explain a necessary substantial deviation instead of silently replacing the request. "
+ "This adjusts teaching style only, never mode authorization, source trust, "
+ "pending-question identity or mastery credit. "
"Repeated confusion or not_helped calls for a concrete change in explanation, "
"not another promise or identical phrasing. Tentative notes are hypotheses; "
"unknown does not mean understood. Record results only from a literal current-message learner quote, "
diff --git a/tests/capabilities/test_mastery_teaching_focus.py b/tests/capabilities/test_mastery_teaching_focus.py
new file mode 100644
index 000000000..fbe57d400
--- /dev/null
+++ b/tests/capabilities/test_mastery_teaching_focus.py
@@ -0,0 +1,35 @@
+"""Advisory focus remains scoped and does not infer learning evidence."""
+
+from deeptutor.learning.models import LearnerProfile, TeachingObservation
+from deeptutor.learning.teaching import teaching_guidance
+
+
+def test_focus_uses_current_failed_strategy_without_mutating_profile():
+ profile = LearnerProfile(teaching_observations={
+ "current": TeachingObservation(knowledge_point_id="point", text="The relationship is unclear",
+ basis="learner_report", evidence="I still do not see the connection",
+ strategy="Names without an example", outcome="not_helped"),
+ "other": TeachingObservation(knowledge_point_id="other", text="Needs a diagram",
+ strategy="A diagram", outcome="helped"),
+ })
+ before = profile.model_dump()
+ focus = teaching_guidance(profile, "point", include_history=True)["teaching_focus"]
+ assert focus["knowledge_point_id"] == "point"
+ assert [item["key"] for item in focus["observations"]] == ["current"]
+ assert focus["observations"][0]["strategy"] == "Names without an example"
+ assert focus["observations"][0]["outcome"] == "not_helped"
+ assert profile.model_dump() == before
+
+
+def test_focus_does_not_invent_difficulty_or_understanding():
+ focus = teaching_guidance(LearnerProfile(), "point")["teaching_focus"]
+ assert focus["observations"] == []
+ assert "unknown is not understanding" in focus["instruction"]
+
+
+def test_preferences_remain_advisory_and_have_clear_boundaries():
+ guidance = teaching_guidance(LearnerProfile(), "point")["teaching_guidance"]
+ assert "current explicit request over older preferences" in guidance
+ assert "pacing as a preference, not a rigid chunk counter" in guidance
+ assert "requested display format" in guidance
+ assert "mode authorization, source trust, pending-question identity or mastery credit" in guidance