Update explainers/explainer_percent.py

explainers/explainer_percent.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 import re
 from .explainer_types import ExplainerResult, ExplainerScaffold
 
@@ -47,14 +45,14 @@ def explain_algebra_question(text: str):
         return None
 
     subtype = _infer_algebra_subtype(text)
+    low = (text or "").lower()
 
     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.",
+        asks_for="the value of the variable or the requested expression built from it",
+        plain_english="Algebra questions usually become easier once you write one clean equation and then reverse the operations in order.",
     )
 
     scaffold = ExplainerScaffold(
@@ -63,10 +61,31 @@ def explain_algebra_question(text: str):
         target="Set up the simplest correct equation or relation before manipulating it.",
         answer_hidden=True,
         solution_path_type=subtype,
-        reveal_threshold=3,
     )
 
-    teaching_points = [
+    result.givens = [
+        "A symbolic relationship or equation is implied by the wording.",
+    ]
+    if "=" in low:
+        result.givens.append("An equals sign or equation structure is present.")
+
+    result.relationships = [
+        "Both sides of an equation must stay balanced.",
+        "Each algebra step should simplify or isolate the target quantity.",
+    ]
+    result.needed_concepts = [
+        "equation balancing",
+        "inverse operations",
+        "checking what the question actually asks for",
+    ]
+    result.trap_notes = [
+        "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.",
+    ]
+    result.strategy_hint = "Rewrite the relationship as one clean equation before doing any manipulation."
+
+    result.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.",
@@ -91,21 +110,15 @@ def explain_algebra_question(text: str):
         scaffold.equations_to_form = [
             "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.",
-        ]
         scaffold.key_operations = [
-            "rewrite as equation",
-            "simplify both sides",
-            "use inverse operations",
+            "Simplify",
+            "undo addition/subtraction",
+            "undo multiplication/division",
         ]
         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.",
+            "What operation is attached to the variable?",
+            "What inverse operation would undo it?",
+            "Apply that same operation to both sides.",
         ]
 
     elif subtype == "system":
@@ -124,21 +137,15 @@ def explain_algebra_question(text: str):
         scaffold.equations_to_form = [
             "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.",
-        ]
         scaffold.key_operations = [
-            "choose elimination or substitution",
-            "reduce to one variable",
-            "substitute back",
+            "substitute",
+            "eliminate",
+            "back-substitute",
         ]
         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.",
+            "Which variable looks easier to isolate?",
+            "Can you align coefficients for elimination?",
+            "After finding one variable, plug it back into the other equation.",
         ]
 
     elif subtype == "inequality":
@@ -154,21 +161,15 @@ def explain_algebra_question(text: str):
         ]
         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.",
-        ]
         scaffold.key_operations = [
-            "translate wording",
+            "translate wording to an inequality",
             "simplify",
-            "track sign reversal",
+            "watch for sign reversal with negatives",
         ]
         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.",
+            "What phrase tells you the direction of the inequality?",
+            "Can you simplify both sides first?",
+            "Did you divide or multiply by a negative at any point?",
         ]
 
     elif subtype == "quadratic":
@@ -184,21 +185,15 @@ def explain_algebra_question(text: str):
         ]
         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.",
-        ]
         scaffold.key_operations = [
-            "rewrite to zero",
-            "factor or restructure",
-            "check cases",
+            "standardize the expression",
+            "factor or use structure",
+            "check all roots back in context",
         ]
         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.",
+            "Can you move everything to one side first?",
+            "Does the expression factor neatly?",
+            "Do all candidate solutions actually fit the original question?",
         ]
 
     elif subtype == "expression_evaluation":
@@ -214,21 +209,15 @@ def explain_algebra_question(text: str):
         ]
         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.",
-        ]
         scaffold.key_operations = [
-            "solve or rewrite relationship",
-            "substitute into target expression",
-            "simplify target",
+            "solve or rewrite the relationship",
+            "substitute carefully",
+            "simplify the requested expression",
         ]
         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.",
+            "What expression does the question actually want?",
+            "Do you already have enough information to rewrite that expression?",
+            "Only substitute after the target expression is clear.",
         ]
 
     else:
@@ -244,31 +233,22 @@ def explain_algebra_question(text: str):
         ]
         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.",
-        ]
         scaffold.key_operations = [
-            "define unknown",
-            "translate relationship",
-            "simplify and isolate",
+            "translate",
+            "simplify",
+            "isolate",
         ]
         scaffold.hint_ladder = [
-            "Define the unknown clearly.",
-            "Translate the words into one symbolic relationship.",
-            "Simplify before solving.",
-            "Then isolate the target quantity.",
+            "What is the unknown?",
+            "What relationship connects the quantities?",
+            "What is the cleanest first algebra step?",
         ]
 
-    result.teaching_points = teaching_points
     result.scaffold = scaffold
     result.meta = {
         "intent": "explain_question",
         "bridge_ready": True,
-        "hint_style": "progressive",
+        "hint_style": "step_ready",
         "subtype": subtype,
-        "solution_path_type": scaffold.solution_path_type,
-        "key_operations": list(scaffold.key_operations),
     }
     return result