Update formatting.py

formatting.py

@@ -1,500 +1,269 @@
 from __future__ import annotations
 
 import re
-from typing import Any, List, Optional
+from typing import Any, Dict, List, Optional
 
+from question_support_loader import question_support_bank
 
-def style_prefix(tone: float) -> str:
-    if tone < 0.2:
-        return ""
-    if tone < 0.45:
-        return "ok.."
-    if tone < 0.75:
-        return "Let’s work through it."
-    return "You’ve got this — let’s solve it cleanly."
 
+class QuestionFallbackRouter:
+    def _clean(self, text: Optional[str]) -> str:
+        return (text or "").strip()
 
-def _normalize_key(text: str) -> str:
-    text = (text or "").strip().lower()
-    text = text.replace("’", "'")
-    text = re.sub(r"\s+", " ", text)
-    return text
-
-
-def _clean_lines(core: str) -> list[str]:
-    lines = []
-    for line in (core or "").splitlines():
-        cleaned = line.strip()
-        if cleaned:
-            lines.append(cleaned)
-    return lines
-
-
-def _dedupe_lines(lines: list[str]) -> list[str]:
-    seen = set()
-    output = []
-    for line in lines:
-        key = _normalize_key(line)
-        if key and key not in seen:
-            seen.add(key)
-            output.append(line.strip())
-    return output
-
-
-def _coerce_string(value: Any) -> str:
-    return (value or "").strip() if isinstance(value, str) else ""
-
-
-def _coerce_list(value: Any) -> List[str]:
-    if not value:
-        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 _limit_steps(steps: List[str], verbosity: float, minimum: int = 1) -> List[str]:
-    if not steps:
+    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 []
-    if verbosity < 0.25:
-        limit = minimum
-    elif verbosity < 0.5:
-        limit = max(minimum, 2)
-    elif verbosity < 0.75:
-        limit = max(minimum, 3)
-    else:
-        limit = max(minimum, 5)
-    return steps[:limit]
-
-
-def _extract_topic_from_text(text: str, fallback: Optional[str] = None) -> str:
-    low = (text or "").lower()
-    if fallback:
-        return fallback
-    if any(word in low for word in ["equation", "variable", "isolate", "algebra"]):
-        return "algebra"
-    if any(word in low for word in ["percent", "percentage", "%"]):
-        return "percent"
-    if any(word in low for word in ["ratio", "proportion"]):
-        return "ratio"
-    if any(word in low for word in ["probability", "outcome", "chance", "odds"]):
-        return "probability"
-    if any(word in low for word in ["mean", "median", "average"]):
-        return "statistics"
-    if any(word in low for word in ["triangle", "circle", "angle", "area", "perimeter"]):
-        return "geometry"
-    if any(word in low for word in ["integer", "factor", "multiple", "prime", "remainder"]):
-        return "number_theory"
-    return "general"
-
-
-def _strip_bullet_prefix(text: str) -> str:
-    return re.sub(r"^\s*-\s*", "", (text or "").strip())
-
-
-def _normalize_display_lines(lines: List[str]) -> List[str]:
-    cleaned: List[str] = []
-    for line in lines:
-        item = _strip_bullet_prefix(line)
-        if item:
-            cleaned.append(item)
-    return cleaned
-
-
-def _format_answer_mode(
-    lines: List[str],
-    topic: str,
-    tone: float,
-    verbosity: float,
-    transparency: float,
-) -> str:
-    output: List[str] = []
-    prefix = style_prefix(tone)
-    if prefix:
-        output.append(prefix)
-        output.append("")
-
-    normalized = _normalize_display_lines(lines)
-    limited = _limit_steps(normalized, verbosity, minimum=2)
-
-    if limited:
-        output.append("Answer path:")
-        for step in limited:
-            output.append(f"- {step}")
-
-    if transparency >= 0.8:
-        output.append("")
-        output.append(_why_line(topic))
-
-    return "\n".join(output).strip()
-
-
-def format_reply(
-    core: str,
-    tone: float,
-    verbosity: float,
-    transparency: float,
-    help_mode: str,
-    hint_stage: int = 0,
-    topic: Optional[str] = None,
-) -> str:
-    prefix = style_prefix(tone)
-    core = (core or "").strip()
-
-    if not core:
-        return prefix or "Start with the structure of the problem."
-
-    lines = _dedupe_lines(_clean_lines(core))
-    if not lines:
-        return prefix or "Start with the structure of the problem."
-
-    resolved_topic = _extract_topic_from_text(core, topic)
-    normalized_lines = _normalize_display_lines(lines)
-
-    if help_mode == "answer":
-        return _format_answer_mode(normalized_lines, resolved_topic, tone, verbosity, transparency)
-
-    shown = _limit_steps(normalized_lines, verbosity, minimum=1)
-    output: List[str] = []
-
-    if prefix:
-        output.append(prefix)
-        output.append("")
-
-    if help_mode == "hint":
-        index = max(0, min(int(hint_stage or 0) - 1, len(shown) - 1))
-        output.append("Hint:")
-        output.append(f"- {shown[index]}")
-        if transparency >= 0.8:
-            output.append("")
-            output.append(_why_line(resolved_topic))
-        return "\n".join(output).strip()
-
-    if help_mode == "walkthrough":
-        output.append("Walkthrough:")
-        for line in shown:
-            output.append(f"- {line}")
-        if transparency >= 0.8:
-            output.append("")
-            output.append(_why_line(resolved_topic))
-        return "\n".join(output).strip()
-
-    if help_mode in {"instruction", "step_by_step"}:
-        output.append("First step:")
-        for line in shown:
-            output.append(f"- {line}")
-        if transparency >= 0.8:
-            output.append("")
-            output.append(_why_line(resolved_topic))
-        return "\n".join(output).strip()
-
-    if help_mode in {"method", "explain", "concept", "definition"}:
-        label = {
-            "method": "Method:",
-            "explain": "Explanation:",
-            "concept": "Key idea:",
-            "definition": "Key idea:",
-        }[help_mode]
-        output.append(label)
-        for line in shown:
-            output.append(f"- {line}")
-        if transparency >= 0.75:
-            output.append("")
-            output.append(_why_line(resolved_topic))
-        return "\n".join(output).strip()
-
-    for line in shown:
-        output.append(f"- {line}")
-
-    if transparency >= 0.85:
-        output.append("")
-        output.append(_why_line(resolved_topic))
-
-    return "\n".join(output).strip()
-
-
-def _get_scaffold(result: Any):
-    return getattr(result, "scaffold", None)
-
-
-def _staged_scaffold_lines(
-    result: Any,
-    help_mode: str,
-    hint_stage: int,
-    verbosity: float,
-    transparency: float,
-) -> List[str]:
-    output: List[str] = []
-    scaffold = _get_scaffold(result)
-    if scaffold is None:
-        return output
-
-    stage = max(0, min(int(hint_stage), 3))
-
-    concept = _coerce_string(getattr(scaffold, "concept", ""))
-    ask = _coerce_string(getattr(scaffold, "ask", ""))
-    first_move = _coerce_string(getattr(scaffold, "first_move", ""))
-    next_hint = _coerce_string(getattr(scaffold, "next_hint", ""))
-    setup_actions = _coerce_list(getattr(scaffold, "setup_actions", []))
-    intermediate_steps = _coerce_list(getattr(scaffold, "intermediate_steps", []))
-    variables_to_define = _coerce_list(getattr(scaffold, "variables_to_define", []))
-    equations_to_form = _coerce_list(getattr(scaffold, "equations_to_form", []))
-    common_traps = _coerce_list(getattr(scaffold, "common_traps", []))
-    hint_ladder = _coerce_list(getattr(scaffold, "hint_ladder", []))
-    key_operations = _coerce_list(getattr(scaffold, "key_operations", []))
-
-    if help_mode == "hint":
-        if hint_ladder:
-            if stage <= 0:
-                chosen = hint_ladder[0]
-            elif stage == 1:
-                chosen = hint_ladder[min(1, len(hint_ladder) - 1)]
-            elif stage == 2:
-                chosen = hint_ladder[min(2, len(hint_ladder) - 1)]
-            else:
-                chosen = next_hint or hint_ladder[-1]
-
-            output.append("Hint:")
-            output.append(f"- {chosen}")
-
-            if stage >= 2 and first_move:
-                output.append("")
-                output.append("Focus on this move:")
-                output.append(f"- {first_move}")
-
-            if stage >= 3 and equations_to_form:
-                output.append("")
-                output.append("Set it up like this:")
-                for item in equations_to_form[:1]:
-                    output.append(f"- {item}")
-
-            if stage >= 3 and key_operations:
-                output.append("")
-                output.append("Operation to use:")
-                for item in key_operations[-2:]:
-                    output.append(f"- {item}")
-
-            if transparency >= 0.8 and concept:
-                output.append("")
-                output.append("Core idea:")
-                output.append(f"- {concept}")
-
-            return output
-
-        if first_move:
-            output.append("Hint:")
-            output.append(f"- {first_move}")
-            return output
-
-    if stage == 0:
-        if concept and transparency >= 0.75:
-            output.append("Core idea:")
-            output.append(f"- {concept}")
-            output.append("")
-
-        if ask:
-            output.append("What to identify first:")
-            output.append(f"- {ask}")
-
-        if setup_actions:
-            output.append("")
-            output.append("Set-up path:")
-            for item in _limit_steps(setup_actions, verbosity, minimum=2):
-                output.append(f"- {item}")
-
-        if first_move or hint_ladder:
-            output.append("")
-            output.append("First move:")
-            output.append(f"- {first_move or hint_ladder[0]}")
-
-        if intermediate_steps:
-            output.append("")
-            output.append("How to build it:")
-            for item in _limit_steps(intermediate_steps, verbosity, minimum=2):
-                output.append(f"- {item}")
-
-        if variables_to_define:
-            output.append("")
-            output.append("Variables to define:")
-            for item in variables_to_define[:3]:
-                output.append(f"- {item}")
-
-        if equations_to_form:
-            output.append("")
-            output.append("Equations to form:")
-            for item in equations_to_form[:3]:
-                output.append(f"- {item}")
-
-        if key_operations:
-            output.append("")
-            output.append("Key operations:")
-            for item in key_operations[:3]:
-                output.append(f"- {item}")
-
-        if next_hint or len(hint_ladder) >= 2:
-            output.append("")
-            output.append("Next hint:")
-            output.append(f"- {next_hint or hint_ladder[1]}")
-
-        if common_traps and verbosity >= 0.7:
-            output.append("")
-            output.append("Watch out for:")
-            for item in common_traps[:3]:
-                output.append(f"- {item}")
-
-        return output
-
-    if stage == 1:
-        if ask:
-            output.append("What to identify first:")
-            output.append(f"- {ask}")
-
-        if first_move or hint_ladder:
-            output.append("")
-            output.append("First move:")
-            output.append(f"- {first_move or hint_ladder[0]}")
-
-        if next_hint or len(hint_ladder) >= 2:
-            output.append("")
-            output.append("Next hint:")
-            output.append(f"- {next_hint or hint_ladder[1]}")
-
-        return output
-
-    if stage == 2:
-        if setup_actions:
-            output.append("Set-up path:")
-            for item in _limit_steps(setup_actions, verbosity, minimum=2):
-                output.append(f"- {item}")
-
-        if intermediate_steps:
-            output.append("")
-            output.append("How to build it:")
-            for item in _limit_steps(intermediate_steps, verbosity, minimum=2):
-                output.append(f"- {item}")
-
-        if variables_to_define:
-            output.append("")
-            output.append("Variables to define:")
-            for item in variables_to_define[:2]:
-                output.append(f"- {item}")
-
-        if equations_to_form:
-            output.append("")
-            output.append("Equations to form:")
-            for item in equations_to_form[:2]:
-                output.append(f"- {item}")
-
-        return output
-
-    if setup_actions:
-        output.append("Set-up path:")
-        for item in _limit_steps(setup_actions, verbosity, minimum=2):
-            output.append(f"- {item}")
-
-    if intermediate_steps:
-        output.append("")
-        output.append("How to build it:")
-        for item in _limit_steps(intermediate_steps, verbosity, minimum=2):
-            output.append(f"- {item}")
-
-    if variables_to_define:
-        output.append("")
-        output.append("Variables to define:")
-        for item in variables_to_define[:3]:
-            output.append(f"- {item}")
-
-    if equations_to_form:
-        output.append("")
-        output.append("Equations to form:")
-        for item in equations_to_form[:3]:
-            output.append(f"- {item}")
-
-    if key_operations:
-        output.append("")
-        output.append("Key operations:")
-        for item in key_operations[:3]:
-            output.append(f"- {item}")
-
-    if next_hint or len(hint_ladder) >= 2:
-        output.append("")
-        output.append("Next hint:")
-        output.append(f"- {next_hint or hint_ladder[1]}")
-
-    if common_traps and verbosity >= 0.65:
-        output.append("")
-        output.append("Watch out for:")
-        for item in common_traps[:3]:
-            output.append(f"- {item}")
-
-    return output
-
-
-def format_explainer_response(
-    result: Any,
-    tone: float,
-    verbosity: float,
-    transparency: float,
-    help_mode: str = "explain",
-    hint_stage: int = 0,
-) -> str:
-    if not result or not getattr(result, "understood", False):
-        return "I can help explain what the question is asking, but I need the full wording of the question."
-
-    output: List[str] = []
-    prefix = style_prefix(tone)
-    if prefix:
-        output.append(prefix)
-
-    stage = max(0, int(getattr(result, "hint_stage", hint_stage) or 0))
-
-    summary = _coerce_string(getattr(result, "summary", ""))
-    teaching_points = _coerce_list(getattr(result, "teaching_points", []))
-
-    if help_mode != "hint" and stage == 0 and summary:
-        if output:
-            output.append("")
-        output.append(summary)
-
-    scaffold_lines = _staged_scaffold_lines(
-        result=result,
-        help_mode=help_mode,
-        hint_stage=stage,
-        verbosity=verbosity,
-        transparency=transparency,
-    )
-    if scaffold_lines:
-        if output:
-            output.append("")
-        output.extend(scaffold_lines)
-
-    if help_mode != "hint" and teaching_points and (stage == 0 or stage >= 3) and verbosity >= 0.55:
-        output.append("")
-        output.append("Key teaching points:")
-        for item in _limit_steps(teaching_points, verbosity, minimum=2):
-            output.append(f"- {item}")
-
-    topic = _extract_topic_from_text(
-        f"{summary} {' '.join(teaching_points)}",
-        getattr(result, "topic", None),
-    )
-
-    if help_mode != "hint" and transparency >= 0.8 and stage not in {1, 2}:
-        output.append("")
-        output.append(_why_line(topic))
-
-    cleaned: List[str] = []
-    previous_blank = False
-    for line in output:
-        is_blank = not line.strip()
-        if is_blank and previous_blank:
-            continue
-        cleaned.append(line)
-        previous_blank = is_blank
 
-    return "\n".join(cleaned).strip()
+    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()