Update explainers/explainer_percent.py

explainers/explainer_percent.py

@@ -1,229 +1,264 @@
+from __future__ import annotations
+
 import re
 from .explainer_types import ExplainerResult, ExplainerScaffold
 
 
-_PERCENT_PATTERNS = [
-    r"\bpercent\b",
-    r"\bpercentage\b",
-    r"\bwhat percent\b",
-    r"\bpercent of\b",
-    r"\bpercent greater than\b",
-    r"\bpercent less than\b",
-    r"\bincrease(?:d)? by \d+ ?%\b",
-    r"\bdecrease(?:d)? by \d+ ?%\b",
-    r"\bdiscount\b",
-    r"\bmarkup\b",
-    r"\binterest\b",
-    r"\btax\b",
-    r"\btip\b",
-    r"\bprofit margin\b",
-    r"\bcommission\b",
-    r"\bpart of\b",
-    r"\bof a number\b",
+_ALGEBRA_PATTERNS = [
+    r"=",
+    r"\bsolve\b",
+    r"\bequation\b",
+    r"\bexpression\b",
+    r"\bvalue of\b",
+    r"\bwhat is x\b",
+    r"\bwhat is y\b",
+    r"\bvariable\b",
 ]
 
 
-def _looks_like_percent_question(text: str) -> bool:
+def _looks_like_algebra_question(text: str) -> bool:
     low = (text or "").lower()
-    if "%" in low:
+
+    if re.search(r"\b[xyzab]\b", low) and "=" in low:
         return True
-    return any(re.search(p, low) for p in _PERCENT_PATTERNS)
+    if any(re.search(p, low) for p in _ALGEBRA_PATTERNS):
+        return True
+    return False
 
 
-def _infer_percent_subtype(text: str) -> str:
+def _infer_algebra_subtype(text: str) -> str:
     low = (text or "").lower()
 
-    if any(k in low for k in ["increase", "decrease", "increased", "decreased", "percent change", "changed by"]):
-        return "percent_change"
-    if any(k in low for k in ["discount", "sale", "off", "markdown"]):
-        return "discount"
-    if any(k in low for k in ["interest", "simple interest", "compound interest"]):
-        return "interest"
-    if any(k in low for k in ["tax", "vat", "tip", "gratuity"]):
-        return "tax_tip"
-    if any(k in low for k in ["what percent", "is what percent of", "as a percent of"]):
-        return "percent_of_percent"
-    if any(k in low for k in ["percent of", "of a number", "% of"]):
-        return "basic_percent"
-    return "generic_percent"
-
-
-def explain_percent_question(text: str):
-    if not _looks_like_percent_question(text):
+    if any(k in low for k in ["system", "simultaneous", "x and y", "two equations"]):
+        return "system"
+    if any(k in low for k in ["inequality", "<", ">", "at least", "at most", "no more than"]):
+        return "inequality"
+    if any(k in low for k in ["quadratic", "squared", "^2", "x2", "root", "factor"]):
+        return "quadratic"
+    if any(k in low for k in ["expression", "value of 2x", "value of x +", "in terms of"]):
+        return "expression_evaluation"
+    if "=" in low:
+        return "linear_equation"
+    return "generic_algebra"
+
+
+def explain_algebra_question(text: str):
+    if not _looks_like_algebra_question(text):
         return None
 
-    subtype = _infer_percent_subtype(text)
+    subtype = _infer_algebra_subtype(text)
 
     result = ExplainerResult(
         understood=True,
-        topic="percent",
-        summary="This is a percent problem. The key is to identify which quantity is the base, which is the compared amount, and what role the percent is playing."
+        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."
+        ),
     )
 
     scaffold = ExplainerScaffold(
-        concept="Percent problems are built around a base amount, a compared amount, and a rate per hundred.",
-        ask="Decide which quantity is the whole/base, which quantity is the part or changed amount, and whether the question is asking for a percent, a value, or a new total.",
-        target="Translate the wording into the correct percent relationship before doing any arithmetic.",
+        concept="Algebra represents unknown quantities symbolically, then uses valid transformations to isolate or compare them.",
+        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 = [
-        "Percent means per hundred, so it should usually be converted to a decimal or fraction before setting up the relationship.",
-        "Most percent questions reduce to one of a small number of templates, so identifying the template matters more than rushing into calculation.",
-        "The biggest source of error is choosing the wrong base quantity."
+        "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.",
     ]
 
-    if subtype == "basic_percent":
+    if subtype == "linear_equation":
         scaffold.setup_actions = [
-            "Label the known quantities as part, whole, and percent.",
-            "Convert the percent to a decimal or fraction.",
-            "Match the statement to the relationship: part = percent × whole."
+            "Identify the unknown and write the equation cleanly.",
+            "Simplify each side if needed.",
+            "Undo operations in a logical order to isolate the variable.",
         ]
         scaffold.intermediate_steps = [
-            "If the whole is unknown, assign it a variable.",
-            "Substitute the known values into the relationship.",
-            "Solve only after the structure is correct."
+            "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.",
         ]
-        scaffold.first_move = "Start by identifying the whole and the part."
-        scaffold.next_hint = "Once those roles are clear, write one equation connecting part, percent, and whole."
+        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 x represent the unknown quantity if either the part or whole is missing."
+            "Let the unknown quantity be x if the question has not already named it.",
         ]
         scaffold.equations_to_form = [
-            "part = percent × whole"
+            "Build one equation from the stated relationship.",
         ]
         scaffold.common_traps = [
-            "Using the wrong quantity as the whole.",
-            "Using 40 instead of 0.40.",
-            "Treating the wording as a percent change problem when it is only a basic percent-of problem."
+            "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.",
         ]
-
-    elif subtype == "percent_of_percent":
-        scaffold.setup_actions = [
-            "Identify the comparison being made.",
-            "Place the compared quantity over the base quantity.",
-            "Convert the resulting fraction to a percent."
+        scaffold.key_operations = [
+            "rewrite as equation",
+            "simplify both sides",
+            "use inverse operations",
         ]
-        scaffold.intermediate_steps = [
-            "Make sure the denominator is the reference/base amount.",
-            "Simplify the fraction if helpful.",
-            "Only convert to percent at the end."
-        ]
-        scaffold.first_move = "Ask: percent of what?"
-        scaffold.next_hint = "Use the base quantity as the denominator in the fraction before converting."
-        scaffold.equations_to_form = [
-            "percent = (part / whole) × 100"
-        ]
-        scaffold.common_traps = [
-            "Reversing numerator and denominator.",
-            "Using the larger number automatically as the denominator instead of the stated base.",
-            "Forgetting to multiply by 100 at the end if the question asks for a percent."
+        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 == "percent_change":
+    elif subtype == "system":
         scaffold.setup_actions = [
-            "Identify the original value and the new value.",
-            "Find the amount of change first.",
-            "Use the original value as the base in the percent-change formula."
+            "Identify the separate equations and unknowns.",
+            "Decide whether substitution or elimination is the cleaner method.",
+            "Reduce the system to one variable before solving completely.",
         ]
         scaffold.intermediate_steps = [
-            "Compute change = new − original.",
-            "Place that change over the original value.",
-            "Convert the result to a percent."
+            "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.",
         ]
-        scaffold.first_move = "Find the amount of increase or decrease before thinking about the percent."
-        scaffold.next_hint = "After that, divide by the original amount, not the new amount."
+        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 = [
-            "percent change = (new − original) / original × 100"
+            "Use the two given equations together to reduce to one unknown.",
         ]
         scaffold.common_traps = [
-            "Using the new amount as the denominator.",
-            "Skipping the change step and comparing the wrong two quantities.",
-            "Losing track of whether the result should be described as an increase or decrease."
+            "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",
+        ]
+        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 == "discount":
+    elif subtype == "inequality":
         scaffold.setup_actions = [
-            "Identify the original price and the discount rate.",
-            "Find the discount amount from the original price.",
-            "Subtract the discount from the original price if the question asks for the sale price."
+            "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.",
         ]
         scaffold.intermediate_steps = [
-            "Treat the listed price as the base.",
-            "Compute the discount amount separately from the final price.",
-            "Check whether the question asks for discount amount or discounted price."
-        ]
-        scaffold.first_move = "Use the original price as the percent base."
-        scaffold.next_hint = "Find the discount amount first, then decide whether to stop or subtract."
-        scaffold.equations_to_form = [
-            "discount = rate × original price",
-            "sale price = original price − discount"
+            "Simplify both sides first if possible.",
+            "Isolate the variable systematically.",
+            "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 = [
-            "Applying the discount to the wrong quantity.",
-            "Giving the discount amount when the question asks for the final price.",
-            "Treating multiple discounts as one simple combined subtraction without checking the structure."
+            "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",
+            "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 == "interest":
+    elif subtype == "quadratic":
         scaffold.setup_actions = [
-            "Identify principal, rate, and time.",
-            "Determine whether the question is simple interest or compound interest.",
-            "Set up the matching formula structure."
+            "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.",
         ]
         scaffold.intermediate_steps = [
-            "For simple interest, keep the principal fixed.",
-            "For compound interest, recognize that the base changes from period to period.",
-            "Check whether the question asks for interest earned or final amount."
+            "Factor if the form allows it.",
+            "Otherwise identify another clean solving route.",
+            "Check whether all resulting values are allowed in the original context.",
         ]
-        scaffold.first_move = "Work out whether the interest is simple or compound."
-        scaffold.next_hint = "Then identify which quantity stays fixed and which quantity grows."
+        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 = [
-            "Using a simple-interest structure on a compound-interest question.",
-            "Confusing interest earned with total amount.",
-            "Ignoring the time unit matching between rate and period."
+            "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",
+        ]
+        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 == "tax_tip":
+    elif subtype == "expression_evaluation":
         scaffold.setup_actions = [
-            "Identify the pre-tax or pre-tip amount.",
-            "Use that original amount as the base.",
-            "Compute the tax or tip amount before adding if a total is required."
+            "Find the variable or relationship first.",
+            "Only then substitute into the requested expression.",
+            "Simplify the final expression carefully.",
         ]
         scaffold.intermediate_steps = [
-            "Separate the added charge from the final amount.",
-            "Check whether multiple percentages are applied independently or sequentially.",
-            "Make sure the question wants the fee amount or the full total."
-        ]
-        scaffold.first_move = "Use the original listed amount as the base unless the wording clearly says otherwise."
-        scaffold.next_hint = "Find the added percent amount first, then combine only if the question asks for the total."
-        scaffold.equations_to_form = [
-            "added amount = rate × base amount",
-            "total = base amount + added amount"
+            "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.",
         ]
+        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 = [
-            "Using the final total as the percent base.",
-            "Stopping at the tax or tip amount when the question asks for the total bill.",
-            "Blending separate percentages together without checking the wording."
+            "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",
+        ]
+        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 = [
-            "Identify the base quantity.",
-            "Identify the compared quantity or changed amount.",
-            "Match the wording to a standard percent relationship."
+            "Define the unknown clearly.",
+            "Translate the wording into a symbolic relationship.",
+            "Manipulate the relationship only after the setup is clean.",
         ]
         scaffold.intermediate_steps = [
-            "Convert the percent appropriately.",
-            "Build one clear relationship before solving.",
-            "Check whether the question asks for a value, a rate, or a final amount."
+            "Simplify before isolating.",
+            "Keep track of what the question actually asks for.",
+            "Check the final quantity against the prompt.",
         ]
-        scaffold.first_move = "Work out what the percent is being taken of."
-        scaffold.next_hint = "Once the base quantity is clear, write the relationship before calculating."
+        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 = [
-            "Choosing the wrong base.",
-            "Not converting the percent properly.",
-            "Using the right numbers in the wrong relationship."
+            "Poor variable definition.",
+            "Messy setup before solving.",
+            "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
@@ -231,7 +266,9 @@ def explain_percent_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