Update explainers/explainer_algebra.py

explainers/explainer_algebra.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import re
 from .explainer_types import ExplainerResult, ExplainerScaffold
 
@@ -49,7 +51,10 @@ def explain_algebra_question(text: str):
     result = ExplainerResult(
         understood=True,
         topic="algebra",
-        summary="This is an algebra problem. The main goal is to translate the wording into a clean symbolic relationship and isolate the requested quantity step by step."
+        summary=(
+            "This is an algebra problem. The main goal is to translate the wording into a clean "
+            "symbolic relationship and isolate the requested quantity step by step."
+        ),
     )
 
     scaffold = ExplainerScaffold(
@@ -57,135 +62,203 @@ def explain_algebra_question(text: str):
         ask="Identify the unknown, identify the governing relationship, and check whether the question wants the variable itself or an expression built from it.",
         target="Set up the simplest correct equation or relation before manipulating it.",
         answer_hidden=True,
+        solution_path_type=subtype,
+        reveal_threshold=3,
     )
 
     teaching_points = [
         "Most algebra errors happen before the solving starts: either the variable is misdefined, or the equation is set up incorrectly.",
         "A clean equation makes the solving steps much easier.",
-        "You should always check whether the question asks for x itself or for something derived from x."
+        "You should always check whether the question asks for x itself or for something derived from x.",
     ]
 
     if subtype == "linear_equation":
         scaffold.setup_actions = [
             "Identify the unknown and write the equation cleanly.",
             "Simplify each side if needed.",
-            "Undo operations in a logical order to isolate the variable."
+            "Undo operations in a logical order to isolate the variable.",
         ]
         scaffold.intermediate_steps = [
             "Combine like terms first when possible.",
             "Move variable terms and constant terms carefully.",
-            "Check whether the final result should be the variable or a substituted expression."
+            "Check whether the final result should be the variable or a substituted expression.",
         ]
         scaffold.first_move = "Rewrite the relationship as one clean equation if it is not already in that form."
         scaffold.next_hint = "Simplify both sides before isolating the variable."
         scaffold.variables_to_define = [
-            "Let the unknown quantity be x if the question has not already named it."
+            "Let the unknown quantity be x if the question has not already named it.",
         ]
         scaffold.equations_to_form = [
-            "Build one equation from the stated relationship."
+            "Build one equation from the stated relationship.",
         ]
         scaffold.common_traps = [
             "Moving terms across the equals sign incorrectly.",
             "Trying to isolate the variable before simplifying.",
-            "Finding x and forgetting the question asks for something like 2x or x + 3."
+            "Finding x and forgetting the question asks for something like 2x or x + 3.",
+        ]
+        scaffold.key_operations = [
+            "rewrite as equation",
+            "simplify both sides",
+            "use inverse operations",
+        ]
+        scaffold.hint_ladder = [
+            "Start by spotting the equation you need to work with.",
+            "Simplify both sides before you try to isolate the variable.",
+            "Undo the operation attached to the variable on both sides.",
+            "Keep simplifying until only the variable remains.",
         ]
 
     elif subtype == "system":
         scaffold.setup_actions = [
             "Identify the separate equations and unknowns.",
             "Decide whether substitution or elimination is the cleaner method.",
-            "Reduce the system to one variable before solving completely."
+            "Reduce the system to one variable before solving completely.",
         ]
         scaffold.intermediate_steps = [
             "Make one variable easy to substitute, or align coefficients for elimination.",
             "After finding one variable, substitute back carefully.",
-            "Check whether the question asks for one variable, both variables, or a combination of them."
+            "Check whether the question asks for one variable, both variables, or a combination of them.",
         ]
         scaffold.first_move = "Choose one variable to eliminate or substitute."
         scaffold.next_hint = "Turn the system into a single-variable equation before solving."
         scaffold.equations_to_form = [
-            "Use the two given equations together to reduce to one unknown."
+            "Use the two given equations together to reduce to one unknown.",
         ]
         scaffold.common_traps = [
             "Mixing substitution and elimination without a clear plan.",
             "Arithmetic mistakes when substituting back.",
-            "Stopping after finding one variable when the question asks for something else."
+            "Stopping after finding one variable when the question asks for something else.",
+        ]
+        scaffold.key_operations = [
+            "choose elimination or substitution",
+            "reduce to one variable",
+            "substitute back",
+        ]
+        scaffold.hint_ladder = [
+            "Pick the variable that looks easiest to remove.",
+            "Use substitution or elimination to make a one-variable equation.",
+            "Solve that reduced equation first.",
+            "Then substitute back into the other equation.",
         ]
 
     elif subtype == "inequality":
         scaffold.setup_actions = [
             "Translate the condition into an inequality.",
             "Manipulate it like an equation, but track the inequality direction carefully.",
-            "Reverse the sign only if multiplying or dividing by a negative number."
+            "Reverse the sign only if multiplying or dividing by a negative number.",
         ]
         scaffold.intermediate_steps = [
             "Simplify both sides first if possible.",
             "Isolate the variable systematically.",
-            "Interpret the final solution set in the form the question wants."
+            "Interpret the final solution set in the form the question wants.",
         ]
         scaffold.first_move = "Set up the inequality carefully from the wording."
         scaffold.next_hint = "Solve it step by step, watching for any operation that would reverse the sign."
         scaffold.common_traps = [
             "Forgetting to reverse the inequality when dividing or multiplying by a negative.",
             "Treating phrase-based conditions like at least or no more than incorrectly.",
-            "Reporting a single number when the solution is actually a range."
+            "Reporting a single number when the solution is actually a range.",
+        ]
+        scaffold.key_operations = [
+            "translate wording",
+            "simplify",
+            "track sign reversal",
+        ]
+        scaffold.hint_ladder = [
+            "Translate the words into an inequality first.",
+            "Simplify before isolating the variable.",
+            "Watch carefully for multiplication or division by a negative.",
+            "Express the result as the correct range or set.",
         ]
 
     elif subtype == "quadratic":
         scaffold.setup_actions = [
             "Rewrite the equation so one side is zero if needed.",
             "Look for factoring, structure, or another simplifying method.",
-            "Treat each factor or case carefully once the equation is structured properly."
+            "Treat each factor or case carefully once the equation is structured properly.",
         ]
         scaffold.intermediate_steps = [
             "Factor if the form allows it.",
             "Otherwise identify another clean solving route.",
-            "Check whether all resulting values are allowed in the original context."
+            "Check whether all resulting values are allowed in the original context.",
         ]
         scaffold.first_move = "Put the expression into a standard structured form before solving."
         scaffold.next_hint = "Then look for a factorable pattern or another clean route."
         scaffold.common_traps = [
             "Trying to factor before the expression is fully simplified.",
             "Dropping one valid case.",
-            "Giving roots when the question asks for a derived expression instead."
+            "Giving roots when the question asks for a derived expression instead.",
+        ]
+        scaffold.key_operations = [
+            "rewrite to zero",
+            "factor or restructure",
+            "check cases",
+        ]
+        scaffold.hint_ladder = [
+            "Rewrite the equation in a standard form first.",
+            "Look for a common factor or factorable pattern.",
+            "Use the structure to split into cases or solve the quadratic.",
+            "Check whether all resulting values fit the original problem.",
         ]
 
     elif subtype == "expression_evaluation":
         scaffold.setup_actions = [
             "Find the variable or relationship first.",
             "Only then substitute into the requested expression.",
-            "Simplify the final expression carefully."
+            "Simplify the final expression carefully.",
         ]
         scaffold.intermediate_steps = [
             "Do not stop when you find the variable unless that is exactly what the question asks.",
             "Preserve parentheses during substitution.",
-            "Check whether there is a shortcut using the given relationship directly."
+            "Check whether there is a shortcut using the given relationship directly.",
         ]
         scaffold.first_move = "Work out whether you need to solve for the variable first or can rewrite the target expression directly."
         scaffold.next_hint = "Once the relationship is clear, substitute only into the exact expression the question asks for."
         scaffold.common_traps = [
             "Stopping at x when the question asks for something built from x.",
             "Substituting incorrectly into expressions with multiple terms.",
-            "Ignoring an easier algebraic simplification path."
+            "Ignoring an easier algebraic simplification path.",
+        ]
+        scaffold.key_operations = [
+            "solve or rewrite relationship",
+            "substitute into target expression",
+            "simplify target",
+        ]
+        scaffold.hint_ladder = [
+            "Check whether the question wants x or something built from x.",
+            "Use the given relationship to find or rewrite the target expression.",
+            "Substitute only into the exact expression asked for.",
+            "Simplify the resulting expression carefully.",
         ]
 
     else:
         scaffold.setup_actions = [
             "Define the unknown clearly.",
             "Translate the wording into a symbolic relationship.",
-            "Manipulate the relationship only after the setup is clean."
+            "Manipulate the relationship only after the setup is clean.",
         ]
         scaffold.intermediate_steps = [
             "Simplify before isolating.",
             "Keep track of what the question actually asks for.",
-            "Check the final quantity against the prompt."
+            "Check the final quantity against the prompt.",
         ]
         scaffold.first_move = "Start by translating the words into one clean symbolic statement."
         scaffold.next_hint = "Then simplify the structure before solving."
         scaffold.common_traps = [
             "Poor variable definition.",
             "Messy setup before solving.",
-            "Answering the wrong final quantity."
+            "Answering the wrong final quantity.",
+        ]
+        scaffold.key_operations = [
+            "define unknown",
+            "translate relationship",
+            "simplify and isolate",
+        ]
+        scaffold.hint_ladder = [
+            "Define the unknown clearly.",
+            "Translate the words into one symbolic relationship.",
+            "Simplify before solving.",
+            "Then isolate the target quantity.",
         ]
 
     result.teaching_points = teaching_points
@@ -193,7 +266,9 @@ def explain_algebra_question(text: str):
     result.meta = {
         "intent": "explain_question",
         "bridge_ready": True,
-        "hint_style": "step_ready",
+        "hint_style": "progressive",
         "subtype": subtype,
+        "solution_path_type": scaffold.solution_path_type,
+        "key_operations": list(scaffold.key_operations),
     }
     return result