Update question_fallback_router.py

question_fallback_router.py

@@ -7,6 +7,16 @@ from question_support_loader import question_support_bank
 
 
 class QuestionFallbackRouter:
+    """
+    Authoritative support-bank router.
+
+    Design goals:
+    - authored question support should beat generic topic help whenever a match exists
+    - generated topic defaults should only fill real gaps
+    - hint/walkthrough/method/answer ladders should prefer authored sequences as-is
+    - generic "first step" text should not pollute an authored hint ladder
+    """
+
     def _clean(self, text: Optional[str]) -> str:
         return (text or "").strip()
 
@@ -39,8 +49,6 @@ class QuestionFallbackRouter:
 
         if t and t not in {"general", "unknown", "general_quant", "quant"}:
             return t
-        if t == "quant":
-            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):
@@ -74,9 +82,7 @@ class QuestionFallbackRouter:
     def _extract_ratio(self, question_text: str) -> Optional[str]:
         text = self._clean(question_text)
         m = re.search(r"\b(\d+\s*:\s*\d+)\b", text)
-        if m:
-            return self._clean(m.group(1))
-        return None
+        return self._clean(m.group(1)) if m else None
 
     def _extract_percent_values(self, question_text: str) -> List[str]:
         return re.findall(r"\d+\.?\d*\s*%", question_text or "")
@@ -90,34 +96,6 @@ class QuestionFallbackRouter:
             and re.search(r"\d+[a-z]\b|\b[a-z]\b", q)
         )
 
-    def _pack_looks_generic(self, pack: Dict[str, Any], topic: str) -> bool:
-        if not pack:
-            return True
-        joined = " ".join(
-            [
-                self._clean(pack.get("first_step")),
-                self._clean(pack.get("hint_1")),
-                self._clean(pack.get("hint_2")),
-                self._clean(pack.get("hint_3")),
-                " ".join(self._listify(pack.get("walkthrough_steps"))),
-                " ".join(self._listify(pack.get("method_explanation"))),
-            ]
-        ).lower()
-        generic_signals = [
-            "write the equation clearly and identify the variable",
-            "undo operations in reverse order",
-            "keep both sides balanced",
-            "break the question into known and unknown parts",
-            "what is being asked?",
-            "what information is given?",
-            "translate words into math",
-        ]
-        if any(signal in joined for signal in generic_signals):
-            return True
-        if topic == "algebra" and "look at the structure" in joined:
-            return True
-        return False
-
     def _topic_defaults(self, topic: str, question_text: str, options_text: Optional[List[str]]) -> Dict[str, Any]:
         preview = self._preview_question(question_text)
         equation = self._extract_equation(question_text)
@@ -125,23 +103,20 @@ class QuestionFallbackRouter:
         percent_values = self._extract_percent_values(question_text)
         has_options = bool(options_text)
 
-        generic = {
+        pack: Dict[str, Any] = {
             "first_step": f"Focus on what the question is really asking in: {preview}",
-            "hint_1": "Identify the exact quantity you need to find.",
-            "hint_2": "Translate the key relationship in the question into a usable setup.",
-            "hint_3": "Check each step against the wording before choosing an option.",
             "hint_ladder": [
                 "Identify the exact quantity you need to find.",
-                "Translate the key relationship in the question into a usable setup.",
-                "Check each step against the wording before choosing an option.",
+                "Translate the key relationship into a usable setup.",
+                "Check that your setup matches 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 labels or units consistent.",
+                "Work step by step and keep units or labels consistent.",
             ],
             "method_steps": [
-                "Start from the structure of the problem rather than jumping into arithmetic.",
+                "Start from the structure of the problem rather than jumping straight into arithmetic.",
                 "Use the wording to decide which relationship matters most.",
             ],
             "answer_path": [
@@ -153,12 +128,9 @@ class QuestionFallbackRouter:
 
         if topic == "algebra":
             if self._looks_like_linear_equation(question_text):
-                generic.update(
+                pack.update(
                     {
                         "first_step": "Look at the variable side and identify the outermost operation attached to the variable.",
-                        "hint_1": "Undo the outside addition or subtraction on both sides before touching the coefficient.",
-                        "hint_2": "Once only the variable term remains, undo the multiplication or division.",
-                        "hint_3": "After isolating the variable, compare carefully with what the question actually asks for.",
                         "hint_ladder": [
                             "Look at the variable side and identify the outermost operation attached to the variable.",
                             "Undo the outside addition or subtraction on both sides before touching the coefficient.",
@@ -183,40 +155,35 @@ class QuestionFallbackRouter:
                     }
                 )
             elif equation:
-                generic.update(
+                pack.update(
                     {
                         "first_step": f"Start from the equation {equation} and decide which operation should be reversed first.",
-                        "hint_1": "Preserve balance by doing the same operation to both sides.",
-                        "hint_2": "Reverse the operations in a sensible order instead of trying to simplify everything at once.",
-                        "hint_3": "Only evaluate the target expression after the variables are in a usable form.",
+                        "hint_ladder": [
+                            "Preserve balance by doing the same operation to both sides.",
+                            "Reverse the operations in a sensible order instead of trying to simplify everything at once.",
+                            "Only evaluate the target expression after the variables are in a usable form.",
+                        ],
                     }
                 )
-
         elif topic == "percent":
             first_step = "Identify the base quantity before doing any percent calculation."
             if percent_values:
                 first_step = f"Track the percentage relationship carefully here: {' then '.join(percent_values[:2]) if len(percent_values) > 1 else percent_values[0]}"
             if "increased by" in question_text.lower() and "decreased by" in question_text.lower():
-                generic.update(
+                pack.update(
                     {
                         "first_step": "Turn each percentage change into its own multiplier before combining anything.",
-                        "hint_1": "An increase and a decrease of the same percent do not cancel because they apply to different bases.",
-                        "hint_2": "Apply the first multiplier, then apply the second multiplier to the updated amount.",
-                        "hint_3": "Compare the final amount with the original amount only at the end.",
                         "hint_ladder": [
-                            "Turn each percentage change into its own multiplier before combining anything.",
+                            "An increase and a decrease of the same percent do not cancel because they apply to different bases.",
                             "Apply the first multiplier, then apply the second multiplier to the updated amount.",
                             "Compare the final amount with the original amount only at the end.",
                         ],
                     }
                 )
             else:
-                generic.update(
+                pack.update(
                     {
                         "first_step": first_step,
-                        "hint_1": "Ask 'percent of what?' so you choose the correct base quantity.",
-                        "hint_2": "Rewrite the percent as a decimal or fraction if that makes the relationship clearer.",
-                        "hint_3": "Set up part = percent × base, or reverse that relationship if the base is unknown.",
                         "hint_ladder": [
                             "Ask 'percent of what?' so you choose the correct base quantity.",
                             "Rewrite the percent as a decimal or fraction if that makes the relationship clearer.",
@@ -224,17 +191,13 @@ class QuestionFallbackRouter:
                         ],
                     }
                 )
-
         elif topic == "ratio":
             first_step = "Keep the ratio order consistent and assign one shared multiplier."
             if ratio_text:
                 first_step = f"Use the ratio {ratio_text} as parts of one whole."
-            generic.update(
+            pack.update(
                 {
                     "first_step": first_step,
-                    "hint_1": "Write each part of the ratio using the same multiplier.",
-                    "hint_2": "Use the total or known part to solve for that shared multiplier.",
-                    "hint_3": "Substitute back into the exact quantity the question asks for.",
                     "hint_ladder": [
                         "Write each part of the ratio using the same multiplier.",
                         "Use the total or known part to solve for that shared multiplier.",
@@ -253,19 +216,22 @@ class QuestionFallbackRouter:
                     "common_trap": "Using the raw ratio numbers as real values before solving for the common multiplier.",
                 }
             )
-
         elif topic == "probability":
-            generic.update(
+            hint_ladder = [
+                "Decide what counts as a successful outcome before you count anything.",
+                "Count the favorable outcomes that satisfy the condition.",
+                "Count the total possible outcomes in the sample space.",
+            ]
+            if "at least" in question_text.lower():
+                hint_ladder = [
+                    "Decide what counts as a successful outcome before you count anything.",
+                    "Check whether the complement is easier to count than the requested event.",
+                    "Build the probability as favorable over total, then simplify if needed.",
+                ]
+            pack.update(
                 {
                     "first_step": "Decide what counts as a successful outcome before you count anything.",
-                    "hint_1": "Count the favorable outcomes that satisfy the condition.",
-                    "hint_2": "Count the total possible outcomes in the sample space.",
-                    "hint_3": "Build the probability as favorable over total, then simplify if needed.",
-                    "hint_ladder": [
-                        "Decide what counts as a successful outcome before you count anything.",
-                        "Count the favorable outcomes that satisfy the condition.",
-                        "Count the total possible outcomes in the sample space.",
-                    ],
+                    "hint_ladder": hint_ladder,
                     "walkthrough_steps": [
                         "Define the event the question cares about.",
                         "Count or construct the favorable cases.",
@@ -279,23 +245,12 @@ class QuestionFallbackRouter:
                     "common_trap": "Changing the denominator incorrectly or forgetting which cases are actually favorable.",
                 }
             )
-            if "at least" in question_text.lower():
-                generic["hint_2"] = "Check whether the complement is easier to count than the requested event."
-                generic["hint_ladder"] = [
-                    generic["hint_1"],
-                    "Check whether the complement is easier to count than the requested event.",
-                    generic["hint_3"],
-                ]
-
         elif topic == "statistics":
             qlow = question_text.lower()
             if any(k in qlow for k in ["variability", "spread", "standard deviation"]):
-                generic.update(
+                pack.update(
                     {
                         "first_step": "Notice that this is about spread, not average.",
-                        "hint_1": "Use the middle value as a centre and compare how far the outer values sit from it.",
-                        "hint_2": "A set with values clustered tightly has lower variability than a set spread farther apart.",
-                        "hint_3": "Choose the set with the widest spread, not the largest mean.",
                         "hint_ladder": [
                             "Notice that this is about spread, not average.",
                             "Use the middle value as a centre and compare how far the outer values sit from it.",
@@ -304,52 +259,153 @@ class QuestionFallbackRouter:
                     }
                 )
             else:
-                generic.update(
+                pack.update(
                     {
                         "first_step": "Identify which statistical measure the question wants before calculating anything.",
-                        "hint_1": "Check whether the task is asking for mean, median, range, or another measure.",
-                        "hint_2": "Organise the data in a clean order if that helps reveal the measure.",
-                        "hint_3": "Use the exact definition of the requested measure rather than a nearby one.",
+                        "hint_ladder": [
+                            "Check whether the task is asking for mean, median, range, or another measure.",
+                            "Organise the data in a clean order if that helps reveal the measure.",
+                            "Use the exact definition of the requested measure rather than a nearby one.",
+                        ],
                     }
                 )
 
         if has_options:
-            generic["answer_path"] = list(generic.get("answer_path", [])) + [
-                "Use the answer choices to check which setup fits the question instead of guessing."
+            pack["answer_path"] = list(pack.get("answer_path", [])) + [
+                "Use the answer choices to test which setup actually matches the question."
             ]
 
-        return generic
+        return pack
+
+    def _pack_looks_generic(self, pack: Dict[str, Any], topic: str) -> bool:
+        if not pack:
+            return True
+        joined = " ".join(
+            [
+                self._clean(pack.get("first_step")),
+                " ".join(self._listify(pack.get("hint_ladder"))),
+                " ".join(self._listify(pack.get("walkthrough_steps"))),
+                " ".join(self._listify(pack.get("method_steps"))),
+                " ".join(self._listify(pack.get("method_explanation"))),
+                " ".join(self._listify(pack.get("answer_path"))),
+            ]
+        ).lower()
+        generic_signals = [
+            "identify the exact quantity you need to find",
+            "translate the key relationship",
+            "set up the relationship before you calculate",
+            "work step by step",
+            "use the wording to decide",
+            "start from the structure",
+            "focus on what the question is really asking",
+            "underline what is given and what must be found",
+        ]
+        if any(signal in joined for signal in generic_signals):
+            return True
+        if topic == "algebra" and "look at the variable side" not in joined and "equation" in joined and "both sides" in joined:
+            return True
+        return False
+
+    def _extract_authored_pack(self, stored: Dict[str, Any]) -> Dict[str, Any]:
+        if not stored:
+            return {}
+        pack: Dict[str, Any] = {}
+        text_fields = [
+            "first_step",
+            "concept",
+            "common_trap",
+            "stem",
+            "question_text",
+            "topic",
+            "category",
+        ]
+        list_fields = [
+            "hint_ladder",
+            "hints",
+            "walkthrough_steps",
+            "method_steps",
+            "method_explanation",
+            "answer_path",
+            "choices",
+            "options_text",
+        ]
+        for key in text_fields:
+            value = self._clean(stored.get(key))
+            if value:
+                pack[key] = value
+        for key in list_fields:
+            values = self._dedupe(self._listify(stored.get(key)))
+            if values:
+                pack[key] = values
+        for key in ("hint_1", "hint_2", "hint_3"):
+            value = self._clean(stored.get(key))
+            if value:
+                pack[key] = value
+        if "support_match" in stored:
+            pack["support_match"] = dict(stored["support_match"])
+        return pack
+
+    def _confidence_rank(self, confidence: str) -> int:
+        mapping = {"exact": 4, "high": 3, "medium": 2, "low": 1}
+        return mapping.get((confidence or "").lower(), 0)
 
     def _merge_support_pack(self, generated: Dict[str, Any], stored: Optional[Dict[str, Any]], topic: str) -> Dict[str, Any]:
         if not stored:
-            merged = dict(generated)
-            merged["support_source"] = "generated_question_specific"
-            return merged
-
-        merged = dict(generated)
-        merged.update(dict(stored))
-
-        if self._pack_looks_generic(stored, topic):
-            for key in [
-                "first_step",
-                "hint_1",
-                "hint_2",
-                "hint_3",
-                "hint_ladder",
-                "walkthrough_steps",
-                "method_steps",
-                "answer_path",
-                "common_trap",
-            ]:
-                if key in generated:
-                    merged[key] = generated[key]
-            merged["support_source"] = "question_bank_refined"
+            pack = dict(generated)
+            pack["support_source"] = "generated_question_specific"
+            pack["support_priority"] = 10
+            pack["has_authored_support"] = False
+            pack["_generated"] = dict(generated)
+            return pack
+
+        authored = self._extract_authored_pack(stored)
+        support_match = dict(authored.get("support_match") or {})
+        confidence = str(support_match.get("confidence") or "").lower()
+        authored_generic = self._pack_looks_generic(authored, topic)
+
+        pack = dict(authored)
+        pack["_generated"] = dict(generated)
+        pack["has_authored_support"] = True
+        pack["support_match"] = support_match
+
+        for key in ["first_step", "common_trap", "concept", "topic", "category"]:
+            if not self._clean(pack.get(key)):
+                val = self._clean(generated.get(key))
+                if val:
+                    pack[key] = val
+
+        for key in ["hint_ladder", "walkthrough_steps", "method_steps", "method_explanation", "answer_path"]:
+            if not self._listify(pack.get(key)):
+                vals = self._dedupe(self._listify(generated.get(key)))
+                if vals:
+                    pack[key] = vals
+
+        for key in ["hint_1", "hint_2", "hint_3"]:
+            if not self._clean(pack.get(key)):
+                val = self._clean(generated.get(key))
+                if val:
+                    pack[key] = val
+
+        if authored_generic and self._confidence_rank(confidence) <= 1:
+            blended = dict(generated)
+            for key, value in authored.items():
+                if isinstance(value, str) and self._clean(value):
+                    blended[key] = value
+                elif isinstance(value, (list, tuple)) and self._listify(value):
+                    blended[key] = list(value)
+                elif key == "support_match":
+                    blended[key] = value
+            pack = blended
+            pack["_generated"] = dict(generated)
+            pack["has_authored_support"] = True
+            pack["support_match"] = support_match
+            pack["support_source"] = "question_bank_refined"
+            pack["support_priority"] = 60
         else:
-            merged.setdefault("support_source", "question_bank")
+            pack["support_source"] = "question_bank"
+            pack["support_priority"] = 100 if self._confidence_rank(confidence) >= 2 else 80
 
-        merged.setdefault("method_steps", generated.get("method_steps", []))
-        merged.setdefault("answer_path", generated.get("answer_path", []))
-        return merged
+        return pack
 
     def get_support_pack(
         self,
@@ -378,45 +434,60 @@ class QuestionFallbackRouter:
         pack.setdefault("category", category or "General")
         return pack
 
+    def _authored_or_generated(self, pack: Dict[str, Any], key: str) -> Any:
+        value = pack.get(key)
+        if isinstance(value, str):
+            if self._clean(value):
+                return value
+        elif isinstance(value, (list, tuple)):
+            if self._listify(value):
+                return value
+        generated = dict(pack.get("_generated") or {})
+        return generated.get(key)
+
     def _hint_ladder_from_pack(self, pack: Dict[str, Any]) -> List[str]:
         hints: List[str] = []
-        first_step = self._clean(pack.get("first_step"))
-        if first_step:
-            hints.append(first_step)
-        for key in ("hint_1", "hint_2", "hint_3"):
-            value = self._clean(pack.get(key))
-            if value:
-                hints.append(value)
-        hints.extend(self._listify(pack.get("hint_ladder")))
-        hints.extend(self._listify(pack.get("hints")))
+        ladder = self._listify(self._authored_or_generated(pack, "hint_ladder"))
+        authored_hints = self._listify(self._authored_or_generated(pack, "hints"))
+        if ladder or authored_hints:
+            hints.extend(ladder)
+            hints.extend(authored_hints)
+        else:
+            first_step = self._clean(self._authored_or_generated(pack, "first_step"))
+            if first_step:
+                hints.append(first_step)
+            for key in ("hint_1", "hint_2", "hint_3"):
+                value = self._clean(self._authored_or_generated(pack, key))
+                if value:
+                    hints.append(value)
         return self._dedupe(hints)
 
     def _walkthrough_from_pack(self, pack: Dict[str, Any]) -> List[str]:
-        lines: List[str] = []
-        first_step = self._clean(pack.get("first_step"))
-        if first_step:
-            lines.append(first_step)
-        lines.extend(self._listify(pack.get("walkthrough_steps")))
-        return self._dedupe(lines)
+        lines = self._dedupe(self._listify(self._authored_or_generated(pack, "walkthrough_steps")))
+        if lines:
+            return lines
+        first_step = self._clean(self._authored_or_generated(pack, "first_step"))
+        hint_ladder = self._hint_ladder_from_pack(pack)
+        return self._dedupe(([first_step] if first_step else []) + hint_ladder[:4])
 
     def _method_from_pack(self, pack: Dict[str, Any]) -> List[str]:
         lines: List[str] = []
-        concept = self._clean(pack.get("concept"))
+        concept = self._clean(self._authored_or_generated(pack, "concept"))
         if concept:
             lines.append(concept)
-        lines.extend(self._listify(pack.get("method_steps")))
-        lines.extend(self._listify(pack.get("method_explanation")))
-        if not lines:
-            lines.extend(self._walkthrough_from_pack(pack)[:3])
-        return self._dedupe(lines)
+        lines.extend(self._listify(self._authored_or_generated(pack, "method_steps")))
+        lines.extend(self._listify(self._authored_or_generated(pack, "method_explanation")))
+        if lines:
+            return self._dedupe(lines)
+        return self._walkthrough_from_pack(pack)[:3]
 
     def _answer_path_from_pack(self, pack: Dict[str, Any]) -> List[str]:
-        lines: List[str] = []
-        first_step = self._clean(pack.get("first_step"))
-        if first_step:
-            lines.append(first_step)
-        lines.extend(self._listify(pack.get("answer_path")))
-        return self._dedupe(lines)
+        lines = self._dedupe(self._listify(self._authored_or_generated(pack, "answer_path")))
+        if lines:
+            return lines
+        first_step = self._clean(self._authored_or_generated(pack, "first_step"))
+        hint_ladder = self._hint_ladder_from_pack(pack)
+        return self._dedupe(([first_step] if first_step else []) + hint_ladder[:3])
 
     def _verbosity_limit(self, verbosity: float, low: int, mid: int, high: int) -> int:
         if verbosity < 0.25:
@@ -446,14 +517,14 @@ class QuestionFallbackRouter:
         )
 
         mode = (help_mode or "answer").lower()
-        stage = max(1, min(int(hint_stage or 1), 4))
+        stage = max(1, min(int(hint_stage or 1), 6))
 
-        first_step = self._clean(pack.get("first_step"))
+        first_step = self._clean(self._authored_or_generated(pack, "first_step"))
         hint_ladder = self._hint_ladder_from_pack(pack)
         walkthrough_steps = self._walkthrough_from_pack(pack)
         method_steps = self._method_from_pack(pack)
         answer_path = self._answer_path_from_pack(pack)
-        common_trap = self._clean(pack.get("common_trap"))
+        common_trap = self._clean(self._authored_or_generated(pack, "common_trap"))
 
         lines: List[str] = []
 
@@ -465,7 +536,7 @@ class QuestionFallbackRouter:
                     selected.append(hint_ladder[idx + 1])
             else:
                 selected = [first_step or "Start by identifying the structure of the question."]
-            if verbosity >= 0.75 and stage >= 3 and common_trap:
+            if verbosity >= 0.8 and stage >= 3 and common_trap:
                 selected.append(f"Watch out for this trap: {common_trap}")
             lines = self._dedupe(selected)
 
@@ -473,20 +544,20 @@ class QuestionFallbackRouter:
             source = walkthrough_steps or answer_path or hint_ladder
             limit = self._verbosity_limit(verbosity, low=2, mid=4, high=6)
             lines = source[:limit] if source else [first_step or "Start by setting up the problem."]
-            if verbosity >= 0.7 and common_trap:
+            if verbosity >= 0.75 and common_trap:
                 lines = list(lines) + [f"Watch out for this trap: {common_trap}"]
 
         elif mode in {"method", "explain", "concept", "definition"}:
             source = method_steps or walkthrough_steps or answer_path or hint_ladder
             limit = self._verbosity_limit(verbosity, low=1, mid=2, high=4)
             lines = source[:limit] if source else [first_step or "Start from the problem structure."]
-            if verbosity >= 0.65 and common_trap:
+            if verbosity >= 0.7 and common_trap:
                 lines = list(lines) + [f"Common trap: {common_trap}"]
 
         else:
             source = answer_path or walkthrough_steps or hint_ladder
             limit = self._verbosity_limit(verbosity, low=2, mid=3, high=5)
-            lines = source[:limit] if source else [first_step or "Start by identifying the relationship in the question."]
+            lines = source[:limit] if source else [first_step or "Start by identifying the main relationship in the question."]
 
         lines = self._dedupe(lines)
         return {"lines": lines, "pack": pack}