Update formatting.py

formatting.py

@@ -1,302 +1,297 @@
 from __future__ import annotations
 
 import re
-from typing import Any, Dict, List, Optional
+from typing import Any, 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 work through it step by step."
 
-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 []
+def _clean_lines(core: str) -> List[str]:
+    lines: List[str] = []
+    for line in (core or "").splitlines():
+        cleaned = line.strip()
+        if cleaned:
+            lines.append(cleaned)
+    return lines
+
+
+def _normalize_key(text: str) -> str:
+    text = (text or "").strip().lower()
+    text = text.replace("’", "'")
+    text = re.sub(r"\s+", " ", text)
+    return text
+
+
+def _dedupe_lines(lines: List[str]) -> List[str]:
+    seen = set()
+    output: List[str] = []
+    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 _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 _limit_steps(steps: List[str], verbosity: float, minimum: int = 1) -> List[str]:
+    if not steps:
         return []
+    if verbosity < 0.2:
+        limit = minimum
+    elif verbosity < 0.45:
+        limit = max(minimum, 2)
+    elif verbosity < 0.7:
+        limit = max(minimum, 3)
+    else:
+        limit = max(minimum, 5)
+    return steps[:limit]
+
 
-    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.",
-        }
+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", "data", "variance", "standard deviation"]):
+        return "statistics"
+    if any(word in low for word in ["triangle", "circle", "angle", "area", "perimeter", "circumference", "rectangle"]):
+        return "geometry"
+    if any(word in low for word in ["integer", "factor", "multiple", "prime", "remainder", "divisible"]):
+        return "number_theory"
+    return "general"
 
+
+def _why_line(topic: Optional[str]) -> str:
+    topic = (topic or "general").strip().lower()
+
+    if topic == "algebra":
+        return "Why this helps: algebra becomes easier when you reverse operations in order and keep the variable isolated."
+    if topic == "percent":
+        return "Why this helps: percent problems work best when you identify the base amount and apply each change to the correct value."
+    if topic == "ratio":
+        return "Why this helps: ratios represent parts of a whole, so turning them into total parts keeps the set-up consistent."
+    if topic == "probability":
+        return "Why this helps: probability is favorable outcomes over total outcomes, so clear counting matters first."
+    if topic == "statistics":
+        return "Why this helps: statistics questions depend on choosing the right measure before you calculate anything."
+    if topic == "geometry":
+        return "Why this helps: geometry usually becomes manageable once you identify the correct formula and substitute carefully."
+    if topic == "number_theory":
+        return "Why this helps: number theory questions usually depend on patterns, divisibility, or factor structure rather than brute force."
+    return "Why this helps: identifying the structure first makes the next step clearer and reduces avoidable mistakes."
+
+
+def _tone_rewrite(line: str, tone: float, position: int = 0) -> str:
+    text = (line or "").strip()
+    if not text:
+        return text
+
+    if tone < 0.2:
+        return text
+    if tone < 0.45:
+        return text[:1].upper() + text[1:] if text else text
+    if tone < 0.75:
+        return f"Start here: {text[0].lower() + text[1:] if len(text) > 1 else text.lower()}" if position == 0 else text
+    return f"A good place to start is this: {text[0].lower() + text[1:] if len(text) > 1 else text.lower()}" if position == 0 else text
+
+
+def _transparency_expansion(line: str, topic: str, transparency: float, position: int = 0) -> str:
+    text = (line or "").strip()
+    if not text:
+        return text
+
+    if transparency < 0.35:
+        return text
+    if transparency < 0.7:
+        if position == 0:
+            if topic == "algebra":
+                return f"{text} This helps isolate the variable."
+            if topic == "percent":
+                return f"{text} This keeps track of the percent relationship correctly."
+            if topic == "ratio":
+                return f"{text} This helps turn the ratio into usable parts."
+            if topic == "probability":
+                return f"{text} This sets up favorable versus total outcomes."
+        return text
+
+    if position == 0:
         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}"]
+            return f"{text} In algebra, the goal is to isolate the variable by reversing operations in the opposite order."
+        if topic == "percent":
+            return f"{text} Percent questions are easiest when you identify the base amount and apply the change to the right quantity."
+        if topic == "ratio":
+            return f"{text} Ratio questions become easier once you treat the ratio numbers as parts of one total."
+        if topic == "probability":
+            return f"{text} Probability depends on counting the favorable cases and the total possible cases accurately."
+        if topic == "statistics":
+            return f"{text} Statistics questions usually depend on choosing the correct measure before calculating."
+        if topic == "geometry":
+            return f"{text} Geometry problems are usually solved by matching the shape to the correct formula first."
+        return f"{text} This works because it clarifies the structure before you calculate."
+    return text
+
+
+def _styled_lines(lines: List[str], tone: float, transparency: float, topic: str) -> List[str]:
+    output: List[str] = []
+    for i, line in enumerate(lines):
+        rewritten = _tone_rewrite(line, tone, i)
+        rewritten = _transparency_expansion(rewritten, topic, transparency, i)
+        output.append(rewritten)
+    return output
+
+
+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)
+
+    output: List[str] = []
+    if prefix:
+        output.append(prefix)
+        output.append("")
+
+    if help_mode == "hint":
+        if verbosity < 0.25:
+            idx = max(0, min(int(hint_stage or 1) - 1, len(normalized_lines) - 1))
+            shown = [normalized_lines[idx]]
+        elif verbosity < 0.6:
+            idx = max(0, min(int(hint_stage or 1) - 1, len(normalized_lines) - 1))
+            shown = normalized_lines[idx:idx + 2] or [normalized_lines[idx]]
         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
+            shown = normalized_lines[: min(3, len(normalized_lines))]
+
+        shown = _styled_lines(shown, tone, transparency, resolved_topic)
+        output.append("Hint:")
+        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()
+
+    if help_mode in {"walkthrough", "instruction", "step_by_step"}:
+        shown = _limit_steps(normalized_lines, verbosity, minimum=2 if help_mode == "walkthrough" else 1)
+        shown = _styled_lines(shown, tone, transparency, resolved_topic)
+        output.append("Walkthrough:" if help_mode == "walkthrough" else "Step-by-step path:")
+        for line in shown:
+            output.append(f"- {line}")
+
+        if transparency >= 0.7:
+            output.append("")
+            output.append(_why_line(resolved_topic))
+        return "\n".join(output).strip()
+
+    if help_mode in {"method", "explain", "concept", "definition"}:
+        shown = _limit_steps(normalized_lines, verbosity, minimum=1)
+        shown = _styled_lines(shown, tone, transparency, resolved_topic)
+        output.append("Explanation:")
+        for line in shown:
+            output.append(f"- {line}")
 
-        return {
-            "lines": lines,
-            "pack": pack,
-        }
+        if transparency >= 0.6:
+            output.append("")
+            output.append(_why_line(resolved_topic))
+        return "\n".join(output).strip()
 
+    if help_mode == "answer":
+        shown = _limit_steps(normalized_lines, verbosity, minimum=2)
+        shown = _styled_lines(shown, tone, transparency if verbosity >= 0.45 else min(transparency, 0.4), resolved_topic)
+        output.append("Answer path:")
+        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()
+
+    shown = _limit_steps(normalized_lines, verbosity, minimum=1)
+    shown = _styled_lines(shown, tone, transparency, resolved_topic)
+    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()
 
-question_fallback_router = QuestionFallbackRouter()
 
 def format_explainer_response(
-    result,
+    result: Any,
     tone: float,
     verbosity: float,
     transparency: float,
     help_mode: str = "explain",
     hint_stage: int = 0,
 ) -> str:
-    """
-    Fallback wrapper so old conversation_logic still works.
-    Routes everything through format_reply.
-    """
-
     if not result:
-        return "Start by identifying what the question is asking."
+        return "I can help explain what the question is asking, but I need the full wording of the question."
 
-    core_lines = []
+    summary = getattr(result, "summary", "") or ""
+    teaching_points = getattr(result, "teaching_points", []) or []
 
-    # Try to extract useful text from result
-    if hasattr(result, "summary") and result.summary:
-        core_lines.append(result.summary)
+    core_lines: List[str] = []
+    if isinstance(summary, str) and summary.strip():
+        core_lines.append(summary.strip())
 
-    if hasattr(result, "teaching_points") and result.teaching_points:
-        core_lines.extend(result.teaching_points)
+    if isinstance(teaching_points, list):
+        for item in teaching_points:
+            text = str(item).strip()
+            if text:
+                core_lines.append(text)
 
-    core = "\n".join(core_lines).strip()
+    if not core_lines:
+        core_lines = ["Start by identifying what the question is asking."]
 
     return format_reply(
-        core=core,
+        core="\n".join(core_lines),
         tone=tone,
         verbosity=verbosity,
         transparency=transparency,