Create explainer_ratio.py

explainers/explainer_ratio.py

@@ -0,0 +1,66 @@
+# explainer_ratio.py
+
+import re
+from models import ExplainerResult
+
+
+def explain_ratio_question(text: str) -> ExplainerResult | None:
+    t = text.lower()
+
+    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 = []
+
+    ratio_matches = re.findall(r"\b\d+\s*:\s*\d+\b", t)
+    if ratio_matches:
+        givens.append(f"A ratio is given: {', '.join(ratio_matches[:3])}")
+    else:
+        givens.append("A ratio or proportional relationship is given")
+
+    if "total" in t:
+        givens.append("A total amount may also be given")
+
+    if "boys to girls" in t or "men to women" in t or "part to part" in t:
+        relationships.append("This is comparing one group to another group")
+    else:
+        relationships.append("This is a fixed proportional relationship between quantities")
+
+    if "total" in t:
+        relationships.append("You may need to connect ratio parts to a whole total")
+
+    if "remaining" in t or "left" in t:
+        constraints.append("Pay attention to what remains after a change")
+
+    asks_for = None
+    if "what is" in t or "find" in t or "how many" in t:
+        asks_for = "the missing part or total in the ratio relationship"
+
+    trap_notes.extend([
+        "Do not confuse part-to-part ratios with part-to-whole relationships",
+        "Keep the ratio order consistent",
+        "If a total is given, first find how many equal parts the ratio contains",
+    ])
+
+    return ExplainerResult(
+        understood=True,
+        topic="ratio",
+        asks_for=asks_for,
+        givens=givens,
+        constraints=constraints,
+        relationships=relationships,
+        needed_concepts=[
+            "ratio structure",
+            "part-to-part or part-to-whole setup",
+            "equal scaling of ratio parts",
+        ],
+        trap_notes=trap_notes,
+        strategy_hint="Decide whether the ratio compares two parts or links parts to a total before setting anything up.",
+        plain_english="The question is describing a ratio relationship and asking you to identify a missing part or total from that proportional setup.",
+    )