Skip to content

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

fix(mastery): describe concept cards as practice with separate gates

yepyhuna15c14bbf973
diff --git a/deeptutor/capabilities/mastery/loop.py b/deeptutor/capabilities/mastery/loop.py
index f4b290faf..a16ce8946 100644
--- a/deeptutor/capabilities/mastery/loop.py
+++ b/deeptutor/capabilities/mastery/loop.py
@@ -395,8 +395,10 @@ class MasteryLoopCapability:
if not state.get("card_posted") and _looks_like_multipart_assessment(final_text):
return (
"That reply presented a 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 "
+ "For practice across all objective types, call mastery_quiz with a questions group "
+ "so each answer has its own stored contract and result. CONCEPT / DESIGN cards "
+ "do not open their qualitative gate; use mastery_assess for the learner's own "
+ "explanation when assessing that gate. If an older question "
"is pending and you want to show it again, call mastery_quiz with "
"pending_action='resume' and its exact parent resume_question_id, without "
"new questions or answer keys. Preserve it unless the learner explicitly requested replacement; "
diff --git a/deeptutor/capabilities/mastery/tools.py b/deeptutor/capabilities/mastery/tools.py
index bf5cce41b..8195d9727 100644
--- a/deeptutor/capabilities/mastery/tools.py
+++ b/deeptutor/capabilities/mastery/tools.py
@@ -906,16 +906,18 @@ class MasteryQuizTool(BaseTool):
definition = ToolDefinition(
name="mastery_quiz",
description=(
- "Pose a question for a MEMORY or PROCEDURE objective. This one "
- "call registers the expected answer with the engine (so grading "
- "is deterministic and you never re-state the answer later) AND "
+ "Pose practice cards for all objective types: MEMORY, PROCEDURE, "
+ "CONCEPT, or DESIGN, singly or as a questions group. This one "
+ "call registers the expected answer with the engine for exact or "
+ "semantic grading (you never re-state the answer later) AND "
"puts the question in front of the learner on its own answer "
"card — do not call ask_user for it. THE TURN ENDS HERE: unlike "
"ask_user, this does not wait for a reply inside your turn, so "
"call it last and plan nothing after it. Their answer arrives as "
"the next message and you grade it on the next turn with "
- "mastery_grade. For CONCEPT / DESIGN objectives use "
- "mastery_assess instead."
+ "mastery_grade. CONCEPT / DESIGN cards are practice only: their "
+ "qualitative gate still requires the learner's own explanation "
+ "assessed through mastery_assess; quiz correctness cannot open it."
),
parameters=[
ToolParameter(
@@ -1262,7 +1264,14 @@ class MasteryQuizTool(BaseTool):
"button. That list was removed from the stem. Pass the ask in "
"'question' and the choices only in 'options'."
)
- if not pending.questions and kp is not None and kp.type in QUALITATIVE_TYPES:
+ qualitative_practice = any(
+ point is not None and point.type in QUALITATIVE_TYPES
+ for point, _, _ in (
+ find_knowledge_point(progress, question.knowledge_point_id)
+ for question in pending.questions or [pending]
+ )
+ )
+ if qualitative_practice:
# 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
@@ -1271,9 +1280,9 @@ class MasteryQuizTool(BaseTool):
# gate never reads it, and a tutor that assumes otherwise poses
# questions forever at an objective they cannot open.
notice += (
- " This objective is gated qualitatively: grading this answer "
- "will not open it, however right the answer is. Use the "
- "question to probe, then have the learner explain the idea in "
+ " The CONCEPT / DESIGN objectives in this practice are gated qualitatively: "
+ "grading their answers will not open their qualitative gate, however right "
+ "the answers are. Use the cards to probe, then have the learner explain the idea in "
"their own words and record that with mastery_assess."
)
diff --git a/docs/verification/mastery-semantic-assessment.md b/docs/verification/mastery-semantic-assessment.md
index 62aa63ae1..e68d9e842 100644
--- a/docs/verification/mastery-semantic-assessment.md
+++ b/docs/verification/mastery-semantic-assessment.md
@@ -75,3 +75,14 @@ Loop: raw-message injection for those tools and `_grade_seed` only. Runtime:
cards, receipt/rejection projection, bank badges and six partial translations.
Profile, intake, memory, broad teaching guidance and delivery recovery edits
remain in their separate contributions.
+
+## Practice-card interface follow-up
+
+The quiz schema and grouped finish nudge now accurately allow practice cards for
+all objective types. Both single and grouped CONCEPT / DESIGN cards explicitly
+retain the separate qualitative gate. No credit policy was changed. A new
+three-case regression first failed on the obsolete descriptions/missing grouped
+notice, while already proving six correct concept/design attempts did not open
+either gate. After the wording fix: root concept-contract/tools suites 83 passed;
+native concept-contract/runtime/capability suites 101 passed; scoped Ruff and
+diff checks passed.
diff --git a/tests/capabilities/test_mastery_concept_card_contract.py b/tests/capabilities/test_mastery_concept_card_contract.py
new file mode 100644
index 000000000..83f2d1eb0
--- /dev/null
+++ b/tests/capabilities/test_mastery_concept_card_contract.py
@@ -0,0 +1,68 @@
+"""Practice cards are allowed for qualitative objectives without opening their gate."""
+
+import pytest
+
+from deeptutor.capabilities.mastery.loop import MasteryLoopCapability
+from deeptutor.capabilities.mastery.tools import MasteryQuizTool
+from deeptutor.core.context import UnifiedContext
+from deeptutor.learning.models import KnowledgeType
+from deeptutor.learning.policy import is_mastered
+
+pytest_plugins = ["tests.capabilities.test_mastery_question_groups"]
+
+
+def test_quiz_schema_allows_practice_cards_for_all_objective_types():
+ description = MasteryQuizTool().get_definition().description
+ assert "all objective types" in description
+ assert "qualitative gate" in description and "mastery_assess" in description
+ assert "use mastery_assess instead" not in description
+
+
+def test_group_finish_nudge_preserves_concept_practice_and_separate_gate():
+ instruction = MasteryLoopCapability().finish_instruction(
+ UnifiedContext(metadata={"mastery_mode": True}),
+ "Answer these two practice questions; I will grade both answers.\n"
+ "1. Which change increases the rate?\n2. Explain why it increases?",
+ )
+ assert "all objective types" in instruction
+ assert "qualitative gate" in instruction and "mastery_assess" in instruction
+
+
+async def test_grouped_concept_and_design_practice_cannot_open_qualitative_gate(service, monkeypatch):
+ from deeptutor.capabilities.mastery import tools
+
+ progress = service.store.load("p")
+ objectives = progress.modules[0].knowledge_points
+ objectives[0].type = KnowledgeType.CONCEPT
+ objectives[1].type = KnowledgeType.DESIGN
+ service.save(progress)
+ monkeypatch.setattr(tools, "_new_service", lambda: service)
+
+ async def sync(**kwargs):
+ pass
+
+ monkeypatch.setattr(tools, "_sync_mastery_attempt_to_question_bank", sync)
+ for _ in range(3):
+ posed = await tools.MasteryQuizTool().execute(
+ _mastery_path_id="p",
+ questions=[
+ {"knowledge_point_id": "kp1", "question": "Name the concept.", "expected_answer": "alpha"},
+ {"knowledge_point_id": "kp2", "question": "Name the design.", "expected_answer": "beta"},
+ ],
+ )
+ assert posed.success
+ active = service.store.get_active_interaction("p")
+ assert len(active.question.questions) == 2
+ graded = await tools.MasteryGradeTool().execute(
+ _mastery_path_id="p", question_id=active.interaction_id,
+ answers={leaf.question_id: leaf.expected_answer for leaf in active.question.questions},
+ )
+ assert graded.success
+ assert all(item["is_correct"] for item in graded.metadata["mastery_grade"]["result"]["results"])
+
+ final = service.store.load("p")
+ assert len(final.quiz_attempts) == 6
+ assert not any(is_mastered(final, point) for point in final.modules[0].knowledge_points)
+ assert all(event.assessment_type != "qualitative" for event in final.learning_evidence)
+ assert "qualitative gate" in posed.content and "mastery_assess" in posed.content