Update explainers/explainer_ratio.py

explainers/explainer_ratio.py

@@ -1,183 +1,191 @@
 import re
-from explainer_types import ExplainerResult, ExplainerScaffold
-
-
-_RATIO_PATTERNS = [
-    r"\bratio\b",
-    r"\bproportion\b",
-    r"\bfor every\b",
-    r"\bto\b",
-    r":",
-    r"\bout of\b",
-    r"\brespectively\b",
-    r"\bpart to part\b",
-    r"\bpart to whole\b",
+from .explainer_types import ExplainerResult, ExplainerScaffold
+
+
+_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_ratio_question(text: str) -> bool:
+def _looks_like_algebra_question(text: str) -> bool:
     low = (text or "").lower()
 
-    if re.search(r"\b\d+\s*:\s*\d+\b", low):
+    if re.search(r"\b[xyzab]\b", low) and "=" in low:
         return True
-    if "for every" in low:
+    if any(re.search(p, low) for p in _ALGEBRA_PATTERNS):
         return True
-    if "ratio" in low or "proportion" in low:
-        return True
-
     return False
 
 
-def _infer_ratio_subtype(text: str) -> str:
+def _infer_algebra_subtype(text: str) -> str:
     low = (text or "").lower()
 
-    if any(k in low for k in ["for every", "ratio of", "respectively"]):
-        return "ratio_parts"
-    if any(k in low for k in ["total", "sum", "combined"]):
-        return "part_to_total"
-    if any(k in low for k in ["proportion", "directly proportional", "inversely proportional"]):
-        return "proportion"
-    if any(k in low for k in ["mixture", "men and women", "boys and girls", "red and blue", "apples and oranges"]):
-        return "group_ratio"
-    return "generic_ratio"
-
-
-def explain_ratio(text: str):
-    if not _looks_like_ratio_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_ratio_subtype(text)
+    subtype = _infer_algebra_subtype(text)
 
     result = ExplainerResult(
         understood=True,
-        topic="ratio",
-        summary="This is a ratio problem. The main job is to preserve the order of the ratio and convert ratio parts into actual quantities using one shared multiplier."
+        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="A ratio compares quantities by relative size, not by actual amount.",
-        ask="Decide what each side of the ratio refers to, keep the order exact, and determine whether the question wants one part, a total, a difference, or a scaled version.",
-        target="Translate the ratio into variable-based quantities that can be linked to the condition in the question.",
+        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,
     )
 
     teaching_points = [
-        "A ratio does not give actual quantities until a common scale factor is applied.",
-        "Most ratio questions become simple algebra once each part is written in terms of the same multiplier.",
-        "The order matters. Reversing the ratio changes the meaning of the whole setup."
+        "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 == "ratio_parts":
+    if subtype == "linear_equation":
         scaffold.setup_actions = [
-            "Write each ratio part using a common multiplier such as ak and bk.",
-            "Keep the terms in the same order as the original ratio statement.",
-            "Use the condition in the question to connect those expressions to actual values."
+            "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 one part is known, solve for the multiplier first.",
-            "If a total is given, add the ratio expressions.",
-            "If a difference is given, subtract the relevant ratio expressions."
+            "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 = "Rewrite each ratio term as a multiple of the same variable."
-        scaffold.next_hint = "Then connect those expressions to the value or condition given in the question."
+        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 common multiplier be k."
+            "Let the unknown quantity be x if the question has not already named it."
         ]
         scaffold.equations_to_form = [
-            "amounts = ratio parts × common multiplier"
+            "Build one equation from the stated relationship."
         ]
         scaffold.common_traps = [
-            "Reversing the order of the ratio.",
-            "Treating the ratio numbers as final quantities instead of scaled parts.",
-            "Forgetting that different parts must all use the same multiplier."
+            "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 == "part_to_total":
+    elif subtype == "system":
         scaffold.setup_actions = [
-            "Represent each part with a shared multiplier.",
-            "Add the ratio parts to represent the total.",
-            "Match the part or total expression to the given condition."
+            "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 = [
-            "Translate the whole ratio into algebraic amounts first.",
-            "Use the sum of all parts for the total.",
-            "Check whether the question asks for one component or the overall total."
-        ]
-        scaffold.first_move = "Turn the ratio into variable-based amounts and add them to get the total structure."
-        scaffold.next_hint = "Use the given total to solve for the shared multiplier."
-        scaffold.variables_to_define = [
-            "Let the common multiplier be k."
+            "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 = "Choose one variable to eliminate or substitute."
+        scaffold.next_hint = "Turn the system into a single-variable equation before solving."
         scaffold.equations_to_form = [
-            "total = sum of all ratio parts × k"
+            "Use the two given equations together to reduce to one unknown."
         ]
         scaffold.common_traps = [
-            "Using only one part instead of the full sum when a total is given.",
-            "Dropping one category from the total.",
-            "Solving for the multiplier and forgetting to return to the quantity actually asked for."
+            "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."
         ]
 
-    elif subtype == "proportion":
+    elif subtype == "inequality":
         scaffold.setup_actions = [
-            "Identify which two ratios or rates are being set equal.",
-            "Preserve matching positions carefully.",
-            "Use cross-multiplication only after the correspondence is correct."
+            "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 = [
-            "Line up like-with-like before building the proportion.",
-            "Check units or roles so the comparison makes sense.",
-            "Then simplify the resulting equation."
-        ]
-        scaffold.first_move = "Match the corresponding quantities in the two ratios."
-        scaffold.next_hint = "Once the matching is correct, form the equation between the two ratios."
-        scaffold.equations_to_form = [
-            "first ratio = second ratio"
+            "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 = [
-            "Matching the wrong terms across the two ratios.",
-            "Cross-multiplying before the setup is correct.",
-            "Ignoring whether the problem is direct or inverse proportion."
+            "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."
         ]
 
-    elif subtype == "group_ratio":
+    elif subtype == "quadratic":
         scaffold.setup_actions = [
-            "Assign each group its ratio-based expression.",
-            "Use the stated total, difference, or known subgroup size to create an equation.",
-            "Solve for the common multiplier before finding the requested quantity."
+            "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 = [
-            "Make sure each category is represented exactly once.",
-            "Check whether the condition is about the whole group or one subgroup.",
-            "Return to the requested category at the end."
+            "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 = "Represent each group using the same scaling variable."
-        scaffold.next_hint = "Then use the condition involving the total or one group to solve for that variable."
-        scaffold.variables_to_define = [
-            "Let the common multiplier be k."
+        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."
+        ]
+
+    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."
+        ]
+        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."
         ]
+        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 separate multipliers for parts of the same ratio.",
-            "Answering with the multiplier instead of the requested group amount.",
-            "Losing the original ratio order when translating categories."
+            "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."
         ]
 
     else:
         scaffold.setup_actions = [
-            "Identify what each term in the ratio represents.",
-            "Translate the ratio into algebraic quantities with a common scale factor.",
-            "Use the stated condition to solve for the scale factor."
+            "Define the unknown clearly.",
+            "Translate the wording into a symbolic relationship.",
+            "Manipulate the relationship only after the setup is clean."
         ]
         scaffold.intermediate_steps = [
-            "Use the sum if a total is involved.",
-            "Use subtraction if a difference is involved.",
-            "Check which final quantity the question wants."
+            "Simplify before isolating.",
+            "Keep track of what the question actually asks for.",
+            "Check the final quantity against the prompt."
         ]
-        scaffold.first_move = "Start by assigning a shared multiplier to the ratio parts."
-        scaffold.next_hint = "Then use the given condition to turn the ratio setup into an equation."
+        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 = [
-            "Reversing the order of the ratio.",
-            "Not using one shared multiplier.",
-            "Stopping at the multiplier instead of the requested quantity."
+            "Poor variable definition.",
+            "Messy setup before solving.",
+            "Answering the wrong final quantity."
         ]
 
     result.teaching_points = teaching_points