Update explainers/explainer_ratio.py

explainers/explainer_ratio.py

@@ -2,190 +2,169 @@ import re
 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_algebra_question(text: str) -> bool:
+def _looks_like_ratio_question(text: str) -> bool:
     low = (text or "").lower()
 
-    if re.search(r"\b[xyzab]\b", low) and "=" in low:
+    if re.search(r"\b\d+\s*:\s*\d+\b", low):
         return True
-    if any(re.search(p, low) for p in _ALGEBRA_PATTERNS):
+    if "for every" in low:
         return True
+    if "ratio" in low or "proportion" in low:
+        return True
+
     return False
 
 
-def _infer_algebra_subtype(text: str) -> str:
+def _infer_ratio_subtype(text: str) -> str:
     low = (text or "").lower()
 
-    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):
+    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_question(text: str):
+    if not _looks_like_ratio_question(text):
         return None
 
-    subtype = _infer_algebra_subtype(text)
+    subtype = _infer_ratio_subtype(text)
 
     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."
+        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."
     )
 
     scaffold = ExplainerScaffold(
-        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.",
+        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.",
         answer_hidden=True,
     )
 
     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."
+        "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."
     ]
 
-    if subtype == "linear_equation":
+    if subtype == "ratio_parts":
         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."
+            "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."
         ]
         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."
+            "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."
         ]
-        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.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.variables_to_define = [
-            "Let the unknown quantity be x if the question has not already named it."
+            "Let the common multiplier be k."
         ]
         scaffold.equations_to_form = [
-            "Build one equation from the stated relationship."
+            "amounts = ratio parts × common multiplier"
         ]
         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."
+            "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."
         ]
 
-    elif subtype == "system":
+    elif subtype == "part_to_total":
         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."
+            "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."
         ]
         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."
+            "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."
         ]
-        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."
+            "total = sum of all ratio parts × k"
         ]
         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."
+            "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."
         ]
 
-    elif subtype == "inequality":
+    elif subtype == "proportion":
         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."
+            "Identify which two ratios or rates are being set equal.",
+            "Preserve matching positions carefully.",
+            "Use cross-multiplication only after the correspondence is correct."
         ]
         scaffold.intermediate_steps = [
-            "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 = [
-            "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."
+            "Line up like-with-like before building the proportion.",
+            "Check units or roles so the comparison makes sense.",
+            "Then simplify the resulting equation."
         ]
-
-    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."
-        ]
-        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."
+        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"
         ]
-        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."
+            "Matching the wrong terms across the two ratios.",
+            "Cross-multiplying before the setup is correct.",
+            "Ignoring whether the problem is direct or inverse proportion."
         ]
 
-    elif subtype == "expression_evaluation":
+    elif subtype == "group_ratio":
         scaffold.setup_actions = [
-            "Find the variable or relationship first.",
-            "Only then substitute into the requested expression.",
-            "Simplify the final expression carefully."
+            "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."
         ]
         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."
+            "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."
+        ]
+        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 = "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."
+            "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."
         ]
 
     else:
         scaffold.setup_actions = [
-            "Define the unknown clearly.",
-            "Translate the wording into a symbolic relationship.",
-            "Manipulate the relationship only after the setup is clean."
+            "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."
         ]
         scaffold.intermediate_steps = [
-            "Simplify before isolating.",
-            "Keep track of what the question actually asks for.",
-            "Check the final quantity against the prompt."
+            "Use the sum if a total is involved.",
+            "Use subtraction if a difference is involved.",
+            "Check which final quantity the question wants."
         ]
-        scaffold.first_move = "Start by translating the words into one clean symbolic statement."
-        scaffold.next_hint = "Then simplify the structure before solving."
+        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.common_traps = [
-            "Poor variable definition.",
-            "Messy setup before solving.",
-            "Answering the wrong final quantity."
+            "Reversing the order of the ratio.",
+            "Not using one shared multiplier.",
+            "Stopping at the multiplier instead of the requested quantity."
         ]
 
     result.teaching_points = teaching_points