Update explainers/explainer_ratio.py

explainers/explainer_ratio.py

@@ -1,61 +1,191 @@
 import re
-from models import ExplainerResult
+from explainer_types import ExplainerResult, ExplainerScaffold
 
 
-def explain_ratio_question(text: str) -> ExplainerResult | None:
-    t = text.lower()
+_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",
+]
 
-    # STRONG detection
-    has_ratio_word = "ratio" in t or "proportion" in t
-    has_ratio_form = bool(re.search(r"\b\d+\s*:\s*\d+\b", t))
 
-    if not has_ratio_word and not has_ratio_form:
-        return None
-
-    givens = []
-    relationships = []
-    constraints = []
-    trap_notes = []
+def _looks_like_ratio_question(text: str) -> bool:
+    low = (text or "").lower()
 
-    ratio_matches = re.findall(r"\b\d+\s*:\s*\d+\b", t)
+    if re.search(r"\b\d+\s*:\s*\d+\b", low):
+        return True
+    if "for every" in low:
+        return True
+    if "ratio" in low or "proportion" in low:
+        return True
 
-    if ratio_matches:
-        givens.append(f"A ratio is given: {', '.join(ratio_matches[:3])}")
-    else:
-        givens.append("A proportional relationship is described")
+    return False
 
-    if "total" in t or "class" in t:
-        givens.append("A total amount may be relevant")
 
-    relationships.append("This is a fixed proportional relationship between quantities")
+def _infer_ratio_subtype(text: str) -> str:
+    low = (text or "").lower()
 
-    if "fraction" in t or "what fraction" in t:
-        relationships.append("You may need to convert a ratio into a fraction of the whole")
+    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"
 
-    if "boys to girls" in t or "men to women" in t:
-        relationships.append("This compares two groups within a total")
 
-    asks_for = "a missing part, total, or fraction from the ratio"
+def explain_ratio(text: str):
+    if not _looks_like_ratio_question(text):
+        return None
 
-    trap_notes.extend([
-        "Do not confuse part-to-part ratios with part-to-whole fractions",
-        "Keep the ratio order consistent",
-        "If a total is given, first find the total number of ratio parts",
-    ])
+    subtype = _infer_ratio_subtype(text)
 
-    return ExplainerResult(
+    result = ExplainerResult(
         understood=True,
         topic="ratio",
-        asks_for=asks_for,
-        givens=givens,
-        constraints=constraints,
-        relationships=relationships,
-        needed_concepts=[
-            "ratio structure",
-            "proportional scaling",
-            "part-to-whole conversion",
-        ],
-        trap_notes=trap_notes,
-        strategy_hint="Work out how many total parts the ratio represents, then map that to the quantity you need.",
-        plain_english="The question is describing a ratio between quantities and asking you to find a missing part or convert it into a fraction of the whole.",
-    )
+        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="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 = [
+        "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 == "ratio_parts":
+        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."
+        ]
+        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."
+        ]
+        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 common multiplier be k."
+        ]
+        scaffold.equations_to_form = [
+            "amounts = ratio parts × common multiplier"
+        ]
+        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."
+        ]
+
+    elif subtype == "part_to_total":
+        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."
+        ]
+        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."
+        ]
+        scaffold.equations_to_form = [
+            "total = sum of all ratio parts × k"
+        ]
+        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."
+        ]
+
+    elif subtype == "proportion":
+        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."
+        ]
+        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"
+        ]
+        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."
+        ]
+
+    elif subtype == "group_ratio":
+        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."
+        ]
+        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."
+        ]
+        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.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."
+        ]
+
+    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."
+        ]
+        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."
+        ]
+        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 = [
+            "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
+    result.scaffold = scaffold
+    result.meta = {
+        "intent": "explain_question",
+        "bridge_ready": True,
+        "hint_style": "step_ready",
+        "subtype": subtype,
+    }
+    return result