Create question_fallback_router.py

question_fallback_router.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional
+
+from question_support_loader import question_support_bank
+
+
+class QuestionFallbackRouter:
+    def _clean(self, text: Optional[str]) -> str:
+        return (text or "").strip()
+
+    def _listify(self, value: Any) -> List[str]:
+        if value is None:
+            return []
+        if isinstance(value, list):
+            return [str(v).strip() for v in value if str(v).strip()]
+        if isinstance(value, tuple):
+            return [str(v).strip() for v in value if str(v).strip()]
+        if isinstance(value, str):
+            text = value.strip()
+            return [text] if text else []
+        return []
+
+    def _normalize_topic(self, topic: Optional[str], question_text: str) -> str:
+        q = (question_text or "").lower()
+        t = (topic or "").strip().lower()
+        if t and t not in {"general", "unknown", "general_quant"}:
+            return t
+        if "%" in q or "percent" in q:
+            return "percent"
+        if "ratio" in q or re.search(r"\b\d+\s*:\s*\d+\b", q):
+            return "ratio"
+        if any(k in q for k in ["probability", "odds", "chance", "random"]):
+            return "probability"
+        if any(k in q for k in ["remainder", "factor", "multiple", "prime", "divisible"]):
+            return "number_theory"
+        if any(k in q for k in ["triangle", "circle", "angle", "area", "perimeter"]):
+            return "geometry"
+        if any(k in q for k in ["mean", "median", "average", "standard deviation"]):
+            return "statistics"
+        if "=" in q or re.search(r"\b[xyz]\b", q):
+            return "algebra"
+        return "general"
+
+    def _preview_question(self, question_text: str) -> str:
+        cleaned = " ".join(question_text.split())
+        if len(cleaned) <= 120:
+            return cleaned
+        return cleaned[:117].rstrip() + "..."
+
+    def _topic_defaults(self, topic: str, question_text: str, options_text: Optional[List[str]]) -> Dict[str, Any]:
+        preview = self._preview_question(question_text)
+        has_options = bool(options_text)
+
+        generic = {
+            "first_step": f"Focus on what the question is asking in: {preview}",
+            "hint_ladder": [
+                "Identify the exact quantity the question wants.",
+                "Translate the relationships in the stem into a setup you can work with.",
+                "Check each step against the wording before choosing an option.",
+            ],
+            "walkthrough_steps": [
+                "Underline what is given and what must be found.",
+                "Set up the relationship before you calculate.",
+                "Work step by step and keep the units or labels consistent.",
+            ],
+            "method_steps": [
+                "Start from the structure of the problem rather than jumping into arithmetic.",
+                "Use the wording to decide which relationship matters most.",
+            ],
+            "answer_path": [
+                "Set up the correct structure first.",
+                "Only then simplify or evaluate the result.",
+            ],
+            "common_trap": "Rushing into calculation before setting up the relationship.",
+        }
+
+        if topic == "algebra":
+            generic.update(
+                {
+                    "first_step": "Write the equation exactly as given and identify the operation attached to the variable.",
+                    "hint_ladder": [
+                        "Look at which operation is attached to the variable first.",
+                        "Undo that operation on both sides, not just one side.",
+                        "Keep simplifying until the variable is isolated.",
+                    ],
+                    "walkthrough_steps": [
+                        "Copy the equation exactly as written.",
+                        "Use inverse operations to undo what is attached to the variable.",
+                        "Do the same thing to both sides each time.",
+                        "Once the variable is isolated, compare with the answer choices if there are any.",
+                    ],
+                    "method_steps": [
+                        "Algebra questions are about preserving balance while isolating the unknown.",
+                        "Treat each operation in reverse order to peel the equation back.",
+                    ],
+                    "common_trap": "Changing only one side of the equation or combining terms too early.",
+                }
+            )
+        elif topic == "percent":
+            generic.update(
+                {
+                    "first_step": "Identify the base quantity before doing any percent calculation.",
+                    "hint_ladder": [
+                        "Decide what quantity the percent is 'of'.",
+                        "Rewrite the percent as a decimal or fraction if that helps.",
+                        "Set up part = percent × base, or reverse it if the base is unknown.",
+                    ],
+                    "walkthrough_steps": [
+                        "Find the base quantity the percent refers to.",
+                        "Translate the wording into a percent relationship.",
+                        "Solve for the missing quantity.",
+                        "Check whether the question asks for the part, the whole, or a percent change.",
+                    ],
+                    "method_steps": [
+                        "Percent questions become easier once you identify the correct base.",
+                        "Do not apply the percent to the wrong quantity.",
+                    ],
+                    "common_trap": "Using the wrong base quantity.",
+                }
+            )
+        elif topic == "ratio":
+            generic.update(
+                {
+                    "first_step": "Keep the ratio order consistent and assign one shared multiplier.",
+                    "hint_ladder": [
+                        "Write each part of the ratio with the same multiplier.",
+                        "Use the total or known part to solve for that multiplier.",
+                        "Substitute back into the specific part you need.",
+                    ],
+                    "walkthrough_steps": [
+                        "Translate the ratio into algebraic parts with one common scale factor.",
+                        "Use the total or given piece to solve for the factor.",
+                        "Find the required part and check the order of the ratio.",
+                    ],
+                    "method_steps": [
+                        "Ratio questions are controlled by one shared multiplier.",
+                        "Preserve the ratio order all the way through.",
+                    ],
+                    "common_trap": "Reversing the ratio order or using different multipliers for different parts.",
+                }
+            )
+        elif topic == "probability":
+            generic.update(
+                {
+                    "first_step": "Count the successful outcomes and the total possible outcomes separately.",
+                    "hint_ladder": [
+                        "Decide exactly what counts as a success.",
+                        "Count all possible outcomes under the same rules.",
+                        "Write probability as successful over total, then simplify if needed.",
+                    ],
+                    "walkthrough_steps": [
+                        "Identify the event the question cares about.",
+                        "Count the successful outcomes.",
+                        "Count the full sample space.",
+                        "Form the probability and simplify carefully.",
+                    ],
+                    "method_steps": [
+                        "Probability is a comparison of favorable outcomes to all valid outcomes.",
+                        "Make sure the numerator and denominator come from the same setup.",
+                    ],
+                    "common_trap": "Counting the right numerator with the wrong denominator.",
+                }
+            )
+        elif topic == "number_theory":
+            generic.update(
+                {
+                    "first_step": "Identify which number property matters most: factors, multiples, divisibility, or remainders.",
+                    "common_trap": "Using arithmetic intuition instead of the actual number-property rule being tested.",
+                }
+            )
+
+        if has_options:
+            generic["answer_path"].append("Use the choices to check which one matches your setup instead of guessing.")
+
+        return generic
+
+    def get_support_pack(
+        self,
+        *,
+        question_id: Optional[str],
+        question_text: str,
+        options_text: Optional[List[str]],
+        topic: Optional[str],
+        category: Optional[str],
+    ) -> Dict[str, Any]:
+        stored = question_support_bank.get(question_id=question_id, question_text=question_text)
+        resolved_topic = self._normalize_topic(topic, question_text)
+        if stored:
+            pack = dict(stored)
+            pack.setdefault("topic", resolved_topic)
+            pack.setdefault("category", category or "General")
+            pack.setdefault("support_source", "question_bank")
+            return pack
+
+        generated = self._topic_defaults(resolved_topic, question_text, options_text)
+        generated.update(
+            {
+                "question_id": question_id,
+                "question_text": question_text,
+                "options_text": list(options_text or []),
+                "topic": resolved_topic,
+                "category": category or "General",
+                "support_source": "generated_question_specific",
+            }
+        )
+        return generated
+
+    def build_response(
+        self,
+        *,
+        question_id: Optional[str],
+        question_text: str,
+        options_text: Optional[List[str]],
+        topic: Optional[str],
+        category: Optional[str],
+        help_mode: str,
+        hint_stage: int,
+        verbosity: float,
+    ) -> Dict[str, Any]:
+        pack = self.get_support_pack(
+            question_id=question_id,
+            question_text=question_text,
+            options_text=options_text,
+            topic=topic,
+            category=category,
+        )
+
+        mode = (help_mode or "answer").lower()
+        stage = max(1, min(int(hint_stage or 1), 3))
+
+        hint_ladder = self._listify(pack.get("hint_ladder") or pack.get("hints"))
+        walkthrough_steps = self._listify(pack.get("walkthrough_steps"))
+        method_steps = self._listify(pack.get("method_steps") or pack.get("method_explanation"))
+        answer_path = self._listify(pack.get("answer_path"))
+        common_trap = self._clean(pack.get("common_trap"))
+        first_step = self._clean(pack.get("first_step"))
+
+        if mode == "hint":
+            selected = []
+            if first_step and stage == 1:
+                selected.append(first_step)
+            if hint_ladder:
+                idx = min(stage - 1, len(hint_ladder) - 1)
+                selected.append(hint_ladder[idx])
+            if common_trap and verbosity >= 0.55:
+                selected.append(f"Watch out for this trap: {common_trap}")
+            lines = selected or [first_step or "Start by identifying the structure of the question."]
+        elif mode in {"walkthrough", "step_by_step", "instruction"}:
+            lines = walkthrough_steps or answer_path or hint_ladder or [first_step or "Start by setting up the problem."]
+            if first_step and (not lines or lines[0] != first_step):
+                lines = [first_step] + lines
+        elif mode in {"method", "explain", "concept", "definition"}:
+            lines = method_steps or walkthrough_steps or answer_path or [first_step or "Start from the problem structure."]
+            if common_trap and verbosity >= 0.65:
+                lines = list(lines) + [f"Common trap: {common_trap}"]
+        else:
+            lines = answer_path or walkthrough_steps or hint_ladder or [first_step or "Start by identifying the relationship in the question."]
+            if first_step and (not lines or lines[0] != first_step):
+                lines = [first_step] + lines
+
+        return {
+            "lines": lines,
+            "pack": pack,
+        }
+
+
+question_fallback_router = QuestionFallbackRouter()