Update explainers/explainer_algebra.py

explainers/explainer_algebra.py

@@ -1,15 +1,199 @@
-from explainer_percent import explain_percent
-from explainer_ratio import explain_ratio
-from explainer_algebra import explain_algebra
-
-
-def route_explainer(text: str):
-    for fn in (
-        explain_percent,
-        explain_ratio,
-        explain_algebra,
-    ):
-        result = fn(text)
-        if result is not None and getattr(result, "understood", False):
-            return result
-    return None
+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:
+    low = (text or "").lower()
+
+    if re.search(r"\b[xyzab]\b", low) and "=" in low:
+        return True
+    if any(re.search(p, low) for p in _ALGEBRA_PATTERNS):
+        return True
+    return False
+
+
+def _infer_algebra_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):
+        return None
+
+    subtype = _infer_algebra_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."
+    )
+
+    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.",
+        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."
+    ]
+
+    if subtype == "linear_equation":
+        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."
+        ]
+        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."
+        ]
+        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 unknown quantity be x if the question has not already named it."
+        ]
+        scaffold.equations_to_form = [
+            "Build one equation from the stated relationship."
+        ]
+        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."
+        ]
+
+    elif subtype == "system":
+        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."
+        ]
+        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."
+        ]
+        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."
+        ]
+        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."
+        ]
+
+    elif subtype == "inequality":
+        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."
+        ]
+        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."
+        ]
+
+    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 = "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 = [
+            "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 = [
+            "Define the unknown clearly.",
+            "Translate the wording into a symbolic relationship.",
+            "Manipulate the relationship only after the setup is clean."
+        ]
+        scaffold.intermediate_steps = [
+            "Simplify before isolating.",
+            "Keep track of what the question actually asks for.",
+            "Check the final quantity against the prompt."
+        ]
+        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 = [
+            "Poor variable definition.",
+            "Messy setup before solving.",
+            "Answering the wrong final 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