Update conversation_logic.py

conversation_logic.py

@@ -1,1315 +1,393 @@
 from __future__ import annotations
 
 import re
-from typing import Any, Dict, List, Optional, Set
-
-from context_parser import detect_intent, intent_to_help_mode
-from formatting import format_reply, format_explainer_response
-from generator_engine import GeneratorEngine
-from models import RetrievedChunk, SolverResult
-from quant_solver import is_quant_question
-from solver_router import route_solver
-from explainers.explainer_router import route_explainer
-from question_classifier import classify_question, normalize_category
-from retrieval_engine import RetrievalEngine
-from utils import normalize_spaces
-
-
-RETRIEVAL_ALLOWED_INTENTS = {
-    "walkthrough",
-    "step_by_step",
-    "explain",
-    "method",
-    "hint",
-    "definition",
-    "concept",
-    "instruction",
-}
-
-DIRECT_SOLVE_PATTERNS = [
-    r"\bsolve\b",
-    r"\bwhat is\b",
-    r"\bfind\b",
-    r"\bgive (?:me )?the answer\b",
-    r"\bjust the answer\b",
-    r"\banswer only\b",
-    r"\bcalculate\b",
-]
-
-STRUCTURE_KEYWORDS = {
-    "algebra": ["equation", "solve", "isolate", "variable", "linear", "expression", "unknown", "algebra"],
-    "percent": ["percent", "%", "percentage", "increase", "decrease"],
-    "ratio": ["ratio", "proportion", "part", "share"],
-    "statistics": ["mean", "median", "mode", "range", "average"],
-    "probability": ["probability", "chance", "odds"],
-    "geometry": ["triangle", "circle", "angle", "area", "perimeter", "radius", "diameter"],
-    "number_theory": ["integer", "odd", "even", "prime", "divisible", "factor", "multiple", "remainder"],
-    "sequence": ["sequence", "geometric", "arithmetic", "term", "series"],
-    "quant": ["equation", "solve", "value", "integer", "ratio", "percent"],
-    "data": ["data", "mean", "median", "trend", "chart", "table", "correlation"],
-    "verbal": ["grammar", "meaning", "author", "argument", "sentence", "word"],
-}
-
-INTENT_KEYWORDS = {
-    "walkthrough": ["walkthrough", "work through", "step by step", "full working"],
-    "step_by_step": ["step", "first step", "next step", "step by step"],
-    "explain": ["explain", "why", "understand"],
-    "method": ["method", "approach", "how do i solve", "how to solve", "equation", "formula"],
-    "hint": ["hint", "nudge", "clue", "what do i do"],
-    "definition": ["define", "definition", "what does", "what is meant by", "meaning"],
-    "concept": ["concept", "idea", "principle", "rule"],
-    "instruction": ["how do i", "how to", "what should i do first", "what step", "first step"],
-}
-
-MISMATCH_TERMS = {
-    "algebra": ["absolute value", "modulus", "square root", "quadratic", "inequality", "roots", "parabola"],
-    "percent": ["triangle", "circle", "prime", "absolute value"],
-    "ratio": ["absolute value", "quadratic", "circle"],
-    "statistics": ["absolute value", "prime", "triangle"],
-    "probability": ["absolute value", "circle area", "quadratic"],
-    "geometry": ["absolute value", "prime", "median salary"],
-    "number_theory": ["circle", "triangle", "median salary"],
-}
-
-def detect_help_mode(text: str) -> str:
-    low = (text or "").lower().strip()
-
-    if any(p in low for p in ["what does", "what is", "define", "meaning of"]):
-        return "definition"
-
-    if any(p in low for p in ["explain", "break down", "what is the question asking", "help me understand"]):
-        return "explain"
-
-    if any(p in low for p in ["step by step", "steps", "walk me through"]):
-        return "step_by_step"
-
-    if any(p in low for p in ["how do i", "how to", "approach this", "method"]):
-        return "answer"
-
-    if any(p in low for p in ["hint", "nudge"]):
-        return "hint"
-
-    if any(p in low for p in ["walkthrough", "work through"]):
-        return "walkthrough"
-
-    return "explain"
-
-def _normalize_classified_topic(topic: Optional[str], category: Optional[str], question_text: str) -> str:
-    t = (topic or "").strip().lower()
-    q = (question_text or "").lower()
-    c = normalize_category(category)
-
-    has_ratio_form = bool(re.search(r"\b\d+\s*:\s*\d+\b", q))
-    has_algebra_form = (
-        "=" in q
-        or bool(re.search(r"\b[xyz]\b", q))
-        or bool(re.search(r"\d+[a-z]\b", q))
-        or bool(re.search(r"\b[a-z]\s*[\+\-\*/=]", q))
-    )
+from typing import Any, List, Optional
 
-    if t == "ratio" and not has_ratio_form and has_algebra_form:
-        t = "algebra"
 
-    if t not in {"general_quant", "general", "unknown", ""}:
-        return t
+def style_prefix(tone: float) -> str:
+    if tone < 0.2:
+        return ""
+    if tone < 0.45:
+        return "Let’s solve it efficiently."
+    if tone < 0.75:
+        return "Let’s work through it."
+    return "You’ve got this — let’s solve it cleanly."
 
-    if "%" in q or "percent" in q:
-        return "percent"
-    if "ratio" in q or has_ratio_form:
-        return "ratio"
-    if "probability" in q or "chosen at random" in q or "odds" in q or "chance" in q:
-        return "probability"
-    if "divisible" in q or "remainder" in q or "prime" in q or "factor" in q:
-        return "number_theory"
-    if any(k in q for k in ["circle", "triangle", "perimeter", "area", "circumference"]):
-        return "geometry"
-    if any(k in q for k in ["mean", "median", "average", "sales", "revenue"]):
-        return "statistics" if c == "Quantitative" else "data"
-    if has_algebra_form or "what is x" in q or "what is y" in q or "integer" in q:
-        return "algebra"
-
-    if c == "DataInsight":
-        return "data"
-    if c == "Verbal":
-        return "verbal"
-    if c == "Quantitative":
-        return "quant"
 
-    return "general"
+def _normalize_key(text: str) -> str:
+    text = (text or "").strip().lower()
+    text = text.replace("’", "'")
+    text = re.sub(r"\s+", " ", text)
+    return text
 
 
-def _teaching_lines(chunks: List[RetrievedChunk]) -> List[str]:
-    lines: List[str] = []
-    for chunk in chunks:
-        text = (chunk.text or "").strip().replace("\n", " ")
-        if len(text) > 220:
-            text = text[:217].rstrip() + "…"
-        topic = chunk.topic or "general"
-        lines.append(f"- {topic}: {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 _safe_steps(steps: List[str]) -> List[str]:
-    cleaned: List[str] = []
-    banned_patterns = [
-        r"\bthe answer is\b",
-        r"\banswer:\b",
-        r"\bthat gives\b",
-        r"\btherefore\b",
-        r"\bso x\s*=",
-        r"\bso y\s*=",
-        r"\bx\s*=",
-        r"\by\s*=",
-        r"\bresult is\b",
-    ]
+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
 
-    for step in steps:
-        s = (step or "").strip()
-        lowered = s.lower()
-        if any(re.search(p, lowered) for p in banned_patterns):
-            continue
-        cleaned.append(s)
 
-    return cleaned
+def _coerce_string(value: Any) -> str:
+    return (value or "").strip() if isinstance(value, str) else ""
 
 
-def _normalize_text(text: str) -> str:
-    return re.sub(r"\s+", " ", (text or "").strip().lower())
-
-
-def _extract_keywords(text: str) -> Set[str]:
-    raw = re.findall(r"[a-zA-Z][a-zA-Z0-9_+-]*", (text or "").lower())
-    stop = {
-        "the", "a", "an", "is", "are", "to", "of", "for", "and", "or", "in", "on", "at", "by", "this", "that",
-        "it", "be", "do", "i", "me", "my", "you", "how", "what", "why", "give", "show", "please", "can",
-    }
-    return {w for w in raw if len(w) > 2 and w not in stop}
-
-
-def _safe_meta_list(items: Any) -> List[str]:
-    if not items:
+def _coerce_list(value: Any) -> List[str]:
+    if not value:
         return []
-    if isinstance(items, list):
-        return [str(x).strip() for x in items if str(x).strip()]
-    if isinstance(items, tuple):
-        return [str(x).strip() for x in items if str(x).strip()]
-    if isinstance(items, str):
-        text = items.strip()
+    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 _safe_meta_text(value: Any) -> Optional[str]:
-    if value is None:
-        return None
-    text = str(value).strip()
-    return text or None
+def _safe_append(lines: List[str], value: str) -> None:
+    text = (value or "").strip()
+    if text:
+        lines.append(text)
 
 
-def _extract_explainer_scaffold(explainer_result: Any) -> Dict[str, Any]:
-    scaffold = getattr(explainer_result, "scaffold", None)
+def _limit_steps(steps: List[str], verbosity: float, minimum: int = 1) -> List[str]:
+    if not steps:
+        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 _why_line(topic: str) -> str:
+    topic = (topic or "").lower()
+
+    if topic == "algebra":
+        return "Why: algebra works by keeping the relationship balanced while undoing the operations attached to the variable."
+    if topic == "percent":
+        return "Why: percent questions depend on choosing the correct base before doing any calculation."
+    if topic == "ratio":
+        return "Why: ratio questions depend on preserving the comparison and using one shared scale factor."
+    if topic == "probability":
+        return "Why: probability compares successful outcomes to all possible outcomes."
+    if topic == "statistics":
+        return "Why: the right method depends on which summary measure the question actually asks for."
+    if topic == "geometry":
+        return "Why: geometry depends on the relationships between the parts of the figure."
+    if topic == "number_theory":
+        return "Why: number properties follow fixed rules about divisibility, factors, and remainders."
+    return "Why: start with the structure of the problem before calculating."
+
+
+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"
 
-    if scaffold is None:
-        return {}
-
-    return {
-        "concept": _safe_meta_text(getattr(scaffold, "concept", None)),
-        "ask": _safe_meta_text(getattr(scaffold, "ask", None)),
-        "givens": _safe_meta_list(getattr(scaffold, "givens", [])),
-        "target": _safe_meta_text(getattr(scaffold, "target", None)),
-        "setup_actions": _safe_meta_list(getattr(scaffold, "setup_actions", [])),
-        "intermediate_steps": _safe_meta_list(getattr(scaffold, "intermediate_steps", [])),
-        "first_move": _safe_meta_text(getattr(scaffold, "first_move", None)),
-        "next_hint": _safe_meta_text(getattr(scaffold, "next_hint", None)),
-        "common_traps": _safe_meta_list(getattr(scaffold, "common_traps", [])),
-        "variables_to_define": _safe_meta_list(getattr(scaffold, "variables_to_define", [])),
-        "equations_to_form": _safe_meta_list(getattr(scaffold, "equations_to_form", [])),
-        "answer_hidden": bool(getattr(scaffold, "answer_hidden", True)),
-    }
-
-
-def _build_scaffold_reply(
-    intent: str,
+
+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("")
+
+    limited = _limit_steps(lines, verbosity, minimum=2)
+    if limited:
+        output.append("Answer path:")
+        if len(limited) >= 1:
+            output.append(f"- What to identify: {limited[0]}")
+        if len(limited) >= 2:
+            output.append(f"- First move: {limited[1]}")
+        if len(limited) >= 3:
+            output.append(f"- Next step: {limited[2]}")
+        for extra in limited[3:]:
+            output.append(f"- Keep in mind: {extra}")
+
+    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,
-    scaffold: Dict[str, Any],
-    summary: Optional[str],
-    teaching_points: List[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)
+
+    if help_mode == "answer":
+        return _format_answer_mode(lines, resolved_topic, tone, verbosity, transparency)
+
+    shown = _limit_steps(lines, verbosity, minimum=1)
+    output: List[str] = []
+
+    if prefix:
+        output.append(prefix)
+        output.append("")
+
+    if help_mode == "hint":
+        output.append("Hint:")
+        output.append(f"- {shown[0]}")
+        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", "walkthrough"}:
+        label = "First step:" if help_mode == "instruction" else "Walkthrough:"
+        output.append(label)
+        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,
+    hint_stage: int,
     verbosity: float,
     transparency: float,
-) -> Optional[str]:
-    if not scaffold and not summary and not teaching_points:
-        return None
-
-    ask = _safe_meta_text(scaffold.get("ask")) if scaffold else None
-    first_move = _safe_meta_text(scaffold.get("first_move")) if scaffold else None
-    next_hint = _safe_meta_text(scaffold.get("next_hint")) if scaffold else None
-    setup_actions = _safe_meta_list(scaffold.get("setup_actions", [])) if scaffold else []
-    intermediate_steps = _safe_meta_list(scaffold.get("intermediate_steps", [])) if scaffold else []
-    variables_to_define = _safe_meta_list(scaffold.get("variables_to_define", [])) if scaffold else []
-    equations_to_form = _safe_meta_list(scaffold.get("equations_to_form", [])) if scaffold else []
-    common_traps = _safe_meta_list(scaffold.get("common_traps", [])) if scaffold else []
-
-    target_mode = help_mode or intent
-
-    if target_mode == "hint" or intent == "hint":
-        if first_move:
-            return first_move
-        if next_hint:
-            return next_hint
-        if setup_actions:
-            return setup_actions[0]
-        if ask:
-            return ask
-        if teaching_points:
-            return teaching_points[0]
-        return None
-
-    if target_mode == "instruction" or intent == "instruction":
-        if first_move:
-            return f"First step: {first_move}"
-        if setup_actions:
-            return f"First step: {setup_actions[0]}"
-        if ask:
-            return f"First, identify this: {ask}"
-        return None
-
-    if target_mode == "definition" or intent == "definition":
-        if summary:
-            return summary
-        if teaching_points:
-            return f"Here is the idea in context:\n- {teaching_points[0]}"
-        if ask:
-            return ask
-        return None
-
-    if target_mode in {"walkthrough", "step_by_step"} or intent in {"walkthrough", "step_by_step"}:
-        lines: List[str] = []
-
-        sequence: List[str] = []
-        if ask:
-            sequence.append(f"Identify this first: {ask}")
-        sequence.extend(setup_actions)
-        sequence.extend(intermediate_steps)
-
-        if first_move and first_move not in sequence:
-            sequence.insert(0, first_move)
-
-        if next_hint and next_hint not in sequence:
-            sequence.append(next_hint)
-
-        if not sequence and summary:
-            sequence.append(summary)
-
-        if not sequence and teaching_points:
-            sequence.extend(teaching_points[:3])
-
-        if not sequence:
-            return None
-
-        if verbosity < 0.25:
-            shown = sequence[:1]
-        elif verbosity < 0.6:
-            shown = sequence[:2]
-        elif verbosity < 0.85:
-            shown = sequence[:4]
-        else:
-            shown = sequence[:6]
-
-        return "\n".join(f"- {s}" for s in shown)
-
-    if target_mode in {"method", "concept", "explain"} or intent in {"method", "concept", "explain"}:
-        lines: List[str] = []
-
-        if summary:
-            lines.append(summary)
-
-        if ask:
-            lines.append(f"Start by identifying: {ask}")
-
-        core_steps: List[str] = []
+) -> 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", []))
+
+    if concept and stage == 0 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 stage == 0:
         if first_move:
-            core_steps.append(first_move)
-        core_steps.extend(setup_actions[:3])
-
-        if transparency >= 0.45:
-            core_steps.extend(intermediate_steps[:2])
-
-        if core_steps:
-            lines.extend(core_steps[:1] if verbosity < 0.35 else core_steps[:3] if verbosity < 0.75 else core_steps[:5])
-
-        if transparency >= 0.55 and variables_to_define:
-            lines.append(f"Useful variable setup: {variables_to_define[0]}")
+            output.append("")
+            output.append("First move:")
+            output.append(f"- {first_move}")
+        elif hint_ladder:
+            output.append("")
+            output.append("First move:")
+            output.append(f"- {hint_ladder[0]}")
+        return output
 
-        if transparency >= 0.6 and equations_to_form:
-            lines.append(f"Key equation: {equations_to_form[0]}")
-
-        if transparency >= 0.65 and next_hint:
-            lines.append(f"Next idea: {next_hint}")
-
-        if (transparency >= 0.75 or verbosity >= 0.75) and common_traps:
-            lines.append(f"Watch out for: {common_traps[0]}")
-
-        if not lines and teaching_points:
-            lines.extend(teaching_points[:2])
-
-        if not lines:
-            return None
-
-        return "\n".join(f"- {s}" if not s.startswith("- ") and len(lines) > 1 else s for s in lines)
-
-    # generic fallback
-    if first_move:
-        return first_move
     if setup_actions:
-        return setup_actions[0]
-    if summary:
-        return summary
-    if teaching_points:
-        return teaching_points[0]
-
-    return None
+        output.append("")
+        output.append("Set-up path:")
+        for item in _limit_steps(setup_actions, verbosity, minimum=2 if stage >= 1 else 1):
+            output.append(f"- {item}")
 
+    if first_move:
+        output.append("")
+        output.append("First move:")
+        output.append(f"- {first_move}")
 
-def _compose_reply(
-    result: SolverResult,
-    intent: str,
+    if stage == 1:
+        if next_hint:
+            output.append("")
+            output.append("Next hint:")
+            output.append(f"- {next_hint}")
+        elif len(hint_ladder) >= 2:
+            output.append("")
+            output.append("Next hint:")
+            output.append(f"- {hint_ladder[1]}")
+        return output
+
+    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 next_hint:
+        output.append("")
+        output.append("Next hint:")
+        output.append(f"- {next_hint}")
+
+    if stage == 2:
+        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 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 common_traps:
+        output.append("")
+        output.append("Watch out for:")
+        for item in common_traps[:4]:
+            output.append(f"- {item}")
+
+    return output
+
+
+def format_explainer_response(
+    result: Any,
+    tone: float,
     verbosity: float,
-    category: Optional[str] = None,
+    transparency: float,
+    hint_stage: int = 0,
 ) -> str:
-    steps = _safe_steps(result.steps or [])
-    topic = (result.topic or "").lower().strip()
-    meta = result.meta or {}
-
-    scaffold_reply = _build_scaffold_reply(
-        intent=intent,
-        help_mode=result.help_mode,
-        scaffold=meta.get("scaffold", {}) if isinstance(meta, dict) else {},
-        summary=_safe_meta_text(meta.get("explainer_summary")) if isinstance(meta, dict) else None,
-        teaching_points=_safe_meta_list(meta.get("explainer_teaching_points", [])) if isinstance(meta, dict) else [],
-        verbosity=verbosity,
-        transparency=0.5,
-    )
-
-    def topic_hint_fallback() -> str:
-        if topic == "algebra":
-            return "Solve for the variable."
-        if topic == "percent":
-            return "Find the percent relationship first."
-        if topic == "ratio":
-            return "Set up the ratio relationship."
-        if topic == "probability":
-            return "Identify the total possible outcomes first."
-        if topic == "statistics":
-            return "Work out which measure the question is asking for."
-        if topic == "geometry":
-            return "Focus on the figure relationships first."
-        if topic == "number_theory":
-            return "Use the number properties in the question."
-        return "Focus on the main relationship first."
-
-    def topic_method_fallback() -> str:
-        if scaffold_reply:
-            return scaffold_reply
-
-        if topic == "algebra":
-            return "\n".join([
-                "- Treat it as an equation.",
-                "- Undo operations on both sides to isolate the variable.",
-            ])
-        if topic == "percent":
-            return "\n".join([
-                "- Identify whether you need the part, the whole, or the percent.",
-                "- Then set up the percent relationship carefully.",
-            ])
-        if topic == "ratio":
-            return "\n".join([
-                "- Identify which quantities are being compared.",
-                "- Keep the ratio in the correct order throughout.",
-            ])
-        if topic == "probability":
-            return "\n".join([
-                "- Identify what counts as a successful outcome.",
-                "- Then compare favorable outcomes to total possible outcomes.",
-            ])
-        if topic == "statistics":
-            return "\n".join([
-                "- Identify which statistic the question is asking for.",
-                "- Then use the relevant values only.",
-            ])
-        if topic == "geometry":
-            return "\n".join([
-                "- Identify the relevant shape properties.",
-                "- Then use the relationships given in the diagram or wording.",
-            ])
-        if topic == "number_theory":
-            return "\n".join([
-                "- Identify the relevant number property.",
-                "- Then apply the divisibility or factor rule carefully.",
-            ])
-        return "I can explain the method, but I do not have enough structured steps yet."
-
-    if intent == "hint":
-        if scaffold_reply:
-            return scaffold_reply
-
-        if steps:
-            first = steps[0].lower()
-
-            if "equation" in first or "=" in first:
-                return "Treat it as an equation."
-            if "isolate" in first or "variable" in first or "solve" in first:
-                return "Solve for the variable."
-            if "percent" in first:
-                return "Find the percent relationship first."
-            if "ratio" in first:
-                return "Set up the ratio relationship."
-            if "probability" in first:
-                return "Identify the total possible outcomes first."
-
-        return topic_hint_fallback()
-
-    if intent == "instruction":
-        if scaffold_reply:
-            return scaffold_reply
-        if steps:
-            return f"First step: {steps[0]}"
-        return "First, identify the key relationship or comparison in the question."
-
-    if intent == "definition":
-        if scaffold_reply:
-            return scaffold_reply
-        if steps:
-            return f"Here is the idea in context:\n- {steps[0]}"
-        return "This is asking for the meaning of the term or idea in the question."
-
-    if intent in {"walkthrough", "step_by_step", "explain", "method", "concept"}:
-        if not steps:
-            return topic_method_fallback()
-
-        generic_lines = {
-            "solve for the variable.",
-            "treat it as an equation.",
-            "identify the quantity the question wants.",
-            "focus on the relationship in the question.",
-        }
-
-        meaningful_steps = []
-        for s in steps:
-            clean = (s or "").strip()
-            if not clean:
-                continue
-            if clean.lower() in generic_lines and len(steps) > 1:
-                continue
-            meaningful_steps.append(clean)
-
-        if not meaningful_steps:
-            meaningful_steps = steps
-
-        if verbosity < 0.25:
-            shown_steps = meaningful_steps[:1]
-        elif verbosity < 0.6:
-            shown_steps = meaningful_steps[:2]
-        elif verbosity < 0.85:
-            shown_steps = meaningful_steps[:3]
-        else:
-            shown_steps = meaningful_steps
-
-        return "\n".join(f"- {s}" for s in shown_steps)
-
-    if steps:
-        if verbosity < 0.35:
-            shown_steps = steps[:1]
-        else:
-            shown_steps = steps[:2]
-
-        if len(shown_steps) == 1:
-            return shown_steps[0]
-
-        return "\n".join(f"- {s}" for s in shown_steps)
-
-    if scaffold_reply:
-        return scaffold_reply
-
-    if normalize_category(category) == "Verbal":
-        return "I can help analyse the wording or logic, but I need the full question text to guide you properly."
-
-    if normalize_category(category) == "DataInsight":
-        return "I can help reason through the data, but I need the full question or chart details to guide you properly."
-
-    return "I can help with this, but I need the full question text to guide you properly."
-
-
-def is_explainer_request(text: str) -> bool:
-    t = (text or "").strip().lower()
-
-    explainer_signals = [
-        "how do i solve",
-        "how to solve",
-        "explain this",
-        "walk me through",
-        "walkthrough",
-        "show me how",
-        "what is the method",
-        "how would you do this",
-        "help me understand",
-        "what's the approach",
-        "what is the approach",
-        "how should i think about this",
-        "what is this asking",
-        "how do i approach this",
-        "can you explain",
-        "explain how",
-        "explain why",
-        "break this down",
-        "question breakdown",
-        "what should i identify first",
-        "what do i do first",
-        "what is the first move",
-    ]
-
-    return any(p in t for p in explainer_signals)
-
-
-def _infer_structure_terms(question_text: str, topic: Optional[str], question_type: Optional[str]) -> List[str]:
-    terms: List[str] = []
-
-    if topic and topic in STRUCTURE_KEYWORDS:
-        terms.extend(STRUCTURE_KEYWORDS[topic])
-
-    if question_type:
-        terms.extend(question_type.replace("_", " ").split())
-
-    q = (question_text or "").lower()
-    if "=" in q:
-        terms.extend(["equation", "solve"])
-    if "x" in q or "y" in q:
-        terms.extend(["variable", "isolate"])
-    if "/" in q or "divide" in q:
-        terms.extend(["divide", "undo operations"])
-    if "*" in q or "times" in q or "multiply" in q:
-        terms.extend(["multiply", "undo operations"])
-    if "%" in q or "percent" in q:
-        terms.extend(["percent", "percentage"])
-    if "ratio" in q or re.search(r"\b\d+\s*:\s*\d+\b", q):
-        terms.extend(["ratio", "proportion"])
-    if "mean" in q or "average" in q:
-        terms.extend(["mean", "average"])
-    if "median" in q:
-        terms.extend(["median"])
-    if "probability" in q or "odds" in q or "chance" in q:
-        terms.extend(["probability", "outcome", "event"])
-    if "remainder" in q or "divisible" in q:
-        terms.extend(["remainder", "divisible"])
-
-    return list(dict.fromkeys(terms))
-
-
-def _infer_mismatch_terms(topic: Optional[str], question_text: str) -> List[str]:
-    if not topic or topic not in MISMATCH_TERMS:
-        return []
-    q = (question_text or "").lower()
-    return [term for term in MISMATCH_TERMS[topic] if term not in q]
-
+    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."
 
-def _intent_keywords(intent: str) -> List[str]:
-    return INTENT_KEYWORDS.get(intent, [])
+    output: List[str] = []
+    prefix = style_prefix(tone)
+    if prefix:
+        output.append(prefix)
+        output.append("")
 
+    output.append("Question breakdown:")
+    output.append("")
 
-def _is_direct_solve_request(text: str, intent: str) -> bool:
-    if intent == "answer":
-        return True
-
-    t = _normalize_text(text)
-    if any(re.search(p, t) for p in DIRECT_SOLVE_PATTERNS):
-        if not any(word in t for word in ["how", "explain", "why", "method", "hint", "define", "definition", "step"]):
-            return True
-    return False
-
-
-def should_retrieve(
-    intent: str,
-    solved: bool,
-    raw_user_text: str,
-    category: Optional[str] = None,
-    domain: Optional[str] = None,
-    topic: Optional[str] = None,
-) -> bool:
-    normalized_category = normalize_category(category)
-    normalized_domain = (domain or "").strip().lower()
-    normalized_topic = (topic or "").strip().lower()
-
-    if intent == "hint":
-        return False
-
-    if normalized_domain == "quant":
-        if intent in {"walkthrough", "step_by_step", "method", "explain", "concept"}:
-            return normalized_topic not in {"", "general", "unknown", "general_quant"}
-        return False
-
-    if intent in {"walkthrough", "step_by_step", "method", "explain", "concept", "definition", "instruction"}:
-        return True
-
-    if _is_direct_solve_request(raw_user_text, intent):
-        return (not solved) and normalized_category in {"Verbal", "DataInsight"}
-
-    if not solved and normalized_category in {"Verbal", "DataInsight"}:
-        return True
-
-    return False
-
-
-def _score_chunk(
-    chunk: RetrievedChunk,
-    intent: str,
-    topic: Optional[str],
-    question_text: str,
-    question_type: Optional[str] = None,
-) -> float:
-    text = f"{chunk.topic} {chunk.text}".lower()
-    score = 0.0
-
-    if topic:
-        chunk_topic = (chunk.topic or "").lower()
-        if chunk_topic == topic.lower():
-            score += 4.0
-        elif topic.lower() in text:
-            score += 2.0
-
-    for term in _infer_structure_terms(question_text, topic, question_type):
-        if term.lower() in text:
-            score += 1.5
-
-    for term in _intent_keywords(intent):
-        if term.lower() in text:
-            score += 1.2
-
-    overlap = sum(1 for kw in _extract_keywords(question_text) if kw in text)
-    score += min(overlap * 0.4, 3.0)
-
-    for bad in _infer_mismatch_terms(topic, question_text):
-        if bad.lower() in text:
-            score -= 2.5
-
-    return score
-
-
-def _filter_retrieved_chunks(
-    chunks: List[RetrievedChunk],
-    intent: str,
-    topic: Optional[str],
-    question_text: str,
-    question_type: Optional[str] = None,
-    min_score: float = 3.2,
-    max_chunks: int = 3,
-) -> List[RetrievedChunk]:
-    scored: List[tuple[float, RetrievedChunk]] = []
-    normalized_topic = (topic or "").lower()
-
-    for chunk in chunks:
-        chunk_topic = (chunk.topic or "").lower()
-
-        if normalized_topic and normalized_topic not in {"general", "unknown", "general_quant"}:
-            if chunk_topic == "general":
-                continue
-
-        s = _score_chunk(chunk, intent, topic, question_text, question_type)
-        if s >= min_score:
-            scored.append((s, chunk))
-
-    scored.sort(key=lambda x: x[0], reverse=True)
-    filtered = [chunk for _, chunk in scored[:max_chunks]]
-    if filtered:
-        return filtered
-
-    fallback: List[tuple[float, RetrievedChunk]] = []
-    for chunk in chunks:
-        s = _score_chunk(chunk, intent, topic, question_text, question_type)
-        if s >= 2.0:
-            fallback.append((s, chunk))
-
-    fallback.sort(key=lambda x: x[0], reverse=True)
-    return [chunk for _, chunk in fallback[:max_chunks]]
-
-
-def _build_retrieval_query(
-    raw_user_text: str,
-    question_text: str,
-    intent: str,
-    topic: Optional[str],
-    solved: bool,
-    question_type: Optional[str] = None,
-    category: Optional[str] = None,
-) -> str:
-    parts: List[str] = []
-
-    raw = (raw_user_text or "").strip()
-    question = (question_text or "").strip()
-
-    if question:
-        parts.append(question)
-    elif raw:
-        lowered = raw.lower()
-
-        wrappers = [
-            "how do i solve",
-            "how to solve",
-            "solve",
-            "can you solve",
-            "walk me through",
-            "explain",
-            "help me solve",
-            "show me how to solve",
-        ]
-
-        cleaned = raw
-        for w in wrappers:
-            if lowered.startswith(w):
-                cleaned = raw[len(w):].strip(" :.-?")
-                break
+    summary = _coerce_string(getattr(result, "summary", ""))
+    if summary:
+        output.append(summary)
 
-        if cleaned:
-            parts.append(cleaned)
-        else:
-            parts.append(raw)
-
-    normalized_category = normalize_category(category)
-    if normalized_category and normalized_category != "General":
-        parts.append(normalized_category)
-
-    if topic:
-        parts.append(topic)
-
-    if question_type:
-        parts.append(question_type.replace("_", " "))
-
-    if intent in {"definition", "concept"}:
-        parts.append("definition concept explanation")
-    elif intent in {"walkthrough", "step_by_step", "method", "instruction"}:
-        parts.append("equation solving method isolate variable worked example")
-    elif intent == "hint":
-        parts.append("equation solving hint first step isolate variable")
-    elif intent == "explain":
-        parts.append("equation solving explanation reasoning")
-    elif not solved:
-        parts.append("teaching explanation method")
-
-    return " ".join(parts).strip()
-
-
-def _fallback_more_info_reply(
-    category: Optional[str],
-    topic: Optional[str],
-    intent: str,
-) -> str:
-    normalized_category = normalize_category(category)
-
-    if normalized_category == "Quantitative" or topic in {
-        "algebra", "percent", "ratio", "probability", "number_theory", "geometry", "statistics", "quant"
-    }:
-        if intent in {"walkthrough", "step_by_step", "method", "explain", "hint", "instruction"}:
-            return (
-                "I need the full question wording to guide this properly step by step. "
-                "Please paste the complete problem, and include the answer choices if there are any."
-            )
-        return (
-            "I need the full question wording to help properly. "
-            "Please paste the complete problem, and include the answer choices if there are any."
-        )
-
-    if normalized_category == "DataInsight":
-        return (
-            "I need the full chart, table, or question wording to help properly. "
-            "Please send the complete prompt and any answer choices."
-        )
-
-    if normalized_category == "Verbal":
-        return (
-            "I need the full passage, sentence, or question wording to help properly. "
-            "Please paste the complete text and any answer choices."
-        )
-
-    return (
-        "I need a bit more information to help properly. "
-        "Please send the full question or exact wording."
+    scaffold_lines = _staged_scaffold_lines(
+        result=result,
+        hint_stage=hint_stage,
+        verbosity=verbosity,
+        transparency=transparency,
+    )
+    if scaffold_lines:
+        if summary:
+            output.append("")
+        output.extend(scaffold_lines)
+
+    teaching_points = _coerce_list(getattr(result, "teaching_points", []))
+    if teaching_points and (verbosity >= 0.55 or hint_stage >= 2):
+        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 transparency >= 0.8:
+        output.append("")
+        output.append(_why_line(topic))
 
-def _is_bad_generated_reply(text: str, user_text: str = "") -> bool:
-    t = (text or "").strip()
-    tl = t.lower()
-    ul = (user_text or "").strip().lower()
-
-    if not t:
-        return True
-
-    if len(t) < 12:
-        return True
-
-    bad_exact = {
-        "0",
-        "formula",
-        "formula formula",
-        "the answer",
-        "answer only",
-        "unknown",
-        "none",
-        "n/a",
-    }
-    if tl in bad_exact:
-        return True
-
-    bad_substrings = [
-        "if the problem is not fully solvable",
-        "if the problem is not fully solvable from the parse",
-        "give the test a chance to solve it",
-        "use the formula formula",
-        "cannot parse alone yet",
-        "i cannot parse",
-        "current parse alone",
-        "from the parse alone",
-    ]
-    if any(b in tl for b in bad_substrings):
-        return True
-
-    banned_answer_patterns = [
-        r"\bthe answer is\b",
-        r"\banswer:\b",
-        r"\bx\s*=",
-        r"\by\s*=",
-        r"\btherefore\b",
-        r"\bthat gives\b",
-        r"\bresult is\b",
-    ]
-    if any(re.search(p, tl) for p in banned_answer_patterns):
-        return True
-
-    words = re.findall(r"\b\w+\b", tl)
-    if len(words) >= 4:
-        unique_ratio = len(set(words)) / max(1, len(words))
-        if unique_ratio < 0.45:
-            return True
-
-    user_keywords = _extract_keywords(ul)
-    gen_keywords = _extract_keywords(tl)
-    if user_keywords and gen_keywords:
-        overlap = user_keywords.intersection(gen_keywords)
-        if len(overlap) == 0 and len(t) < 180:
-            return True
-
-    nonsense_patterns = [
-        r"\bformula\s+formula\b",
-        r"\btest\s+a\s+chance\s+to\s+solve\b",
-        r"^[\W_]*\d+[\W_]*$",
-    ]
-    if any(re.search(p, tl) for p in nonsense_patterns):
-        return True
-
-    return False
-
-
-def _clean_teaching_text(text: str) -> str:
-    text = normalize_spaces((text or "").replace("\n", " ").strip())
-    text = re.sub(r"^[\-\•\*\d\.\)\s]+", "", text)
-    if len(text) > 160:
-        text = text[:157].rstrip() + "..."
-    return text
-
-
-def _looks_question_specific(text: str, question_text: str) -> bool:
-    t = (text or "").strip().lower()
-    q = (question_text or "").strip().lower()
-
-    if not t:
-        return True
-
-    banned_phrases = [
-        "the correct answer",
-        "answer choice",
-        "statement 1",
-        "statement 2",
-        "option a",
-        "option b",
-        "option c",
-        "option d",
-        "option e",
-        "try choice",
-        "plug in numbers",
-        "backsolving",
-        "working backwards",
-        "chapter",
-        "note:",
-    ]
-    if any(p in t for p in banned_phrases):
-        return True
-
-    if "gmat" in t[:25]:
-        return True
-
-    if "..." in t:
-        return True
-
-    if len(re.findall(r"\d+", t)) >= 3:
-        q_numbers = set(re.findall(r"\d+", q))
-        t_numbers = set(re.findall(r"\d+", t))
-        if t_numbers and t_numbers != q_numbers and len(t_numbers - q_numbers) >= 1:
-            return True
-
-    q_vars = set(re.findall(r"\b[a-z]\b", q))
-    t_vars = set(re.findall(r"\b[a-z]\b", t))
-    allowed_vars = q_vars | {"x", "y"}
-
-    if t_vars and q_vars:
-        extra_vars = t_vars - allowed_vars
-        if len(extra_vars) >= 1:
-            return True
-    if re.search(r"\bset\s+[a-z]\s+equal\s+to\b", t):
-        return True
-
-    if re.search(r"\bsolve for [a-z]\b", t) and q_vars:
-        mentioned = set(re.findall(r"\b[a-z]\b", t))
-        if mentioned - q_vars:
-            return True
-
-    if len(t.split()) > 35:
-        return True
-
-    return False
-
-
-def _pick_teaching_line(
-    chunks: List[RetrievedChunk],
-    current_reply: str,
-    question_text: str,
-    topic: Optional[str] = None,
-) -> Optional[str]:
-    if not chunks:
-        return None
-
-    reply_keywords = _extract_keywords(current_reply)
-    desired_topic = (topic or "").lower().strip()
-
-    best_line = None
-    best_score = float("-inf")
-
-    topic_phrases = {
-        "algebra": ["equation", "isolate", "variable", "undo operations", "inverse operation"],
-        "percent": ["percent", "percentage", "base", "rate", "original value"],
-        "ratio": ["ratio", "proportion", "part", "share"],
-        "probability": ["probability", "outcome", "event", "sample space"],
-        "statistics": ["mean", "median", "average", "distribution"],
-        "geometry": ["angle", "triangle", "circle", "area", "perimeter"],
-        "number_theory": ["integer", "divisible", "remainder", "factor", "multiple", "prime"],
-    }
-
-    for chunk in chunks:
-        raw_text = (chunk.text or "").strip()
-        if not raw_text:
-            continue
-
-        text = _clean_teaching_text(raw_text)
-        if not text:
-            continue
-
-        lower_text = text.lower()
-        chunk_topic = (chunk.topic or "").lower().strip()
-
-        if _looks_question_specific(lower_text, question_text):
-            continue
-
-        chunk_keywords = _extract_keywords(lower_text)
-        novelty_vs_reply = len(chunk_keywords - reply_keywords)
-        overlap_with_reply = len(chunk_keywords & reply_keywords)
-
-        topic_bonus = 0.0
-        if desired_topic and chunk_topic == desired_topic:
-            topic_bonus += 3.0
-        elif desired_topic and desired_topic in chunk_topic:
-            topic_bonus += 2.0
-
-        phrase_bonus = 0.0
-        for phrase in topic_phrases.get(desired_topic, []):
-            if phrase in lower_text:
-                phrase_bonus += 1.0
-
-        score = (
-            topic_bonus
-            + phrase_bonus
-            + 1.2 * novelty_vs_reply
-            - 0.8 * overlap_with_reply
-        )
-
-        if len(text.split()) < 5:
-            score -= 2.0
-
-        if score > best_score:
-            best_score = score
-            best_line = text
-
-    if best_score < 2.5:
-        return None
-
-    return best_line
-
-
-class ConversationEngine:
-    def __init__(
-        self,
-        retriever: Optional[RetrievalEngine] = None,
-        generator: Optional[GeneratorEngine] = None,
-        **kwargs,
-    ) -> None:
-        self.retriever = retriever
-        self.generator = generator
-
-    def generate_response(
-        self,
-        raw_user_text: Optional[str] = None,
-        tone: float = 0.5,
-        verbosity: float = 0.5,
-        transparency: float = 0.5,
-        intent: Optional[str] = None,
-        help_mode: Optional[str] = None,
-        retrieval_context: Optional[List[RetrievedChunk]] = None,
-        chat_history: Optional[List[Dict[str, Any]]] = None,
-        question_text: Optional[str] = None,
-        options_text: Optional[List[str]] = None,
-        **kwargs,
-    ) -> SolverResult:
-        solver_input = (question_text or raw_user_text or "").strip()
-        user_text = (raw_user_text or "").strip()
-
-        reply: Optional[str] = None
-        selected_chunks: List[RetrievedChunk] = []
-
-        category = normalize_category(kwargs.get("category"))
-        classification = classify_question(question_text=solver_input, category=category)
-        inferred_category = normalize_category(classification.get("category") or category)
-
-        question_topic = _normalize_classified_topic(
-            classification.get("topic"),
-            inferred_category,
-            solver_input,
-        )
-        question_type = classification.get("type")
-
-        resolved_intent = intent or detect_intent(user_text, help_mode)
-        resolved_help_mode = help_mode or intent_to_help_mode(resolved_intent)
-
-        is_quant = inferred_category == "Quantitative" or is_quant_question(solver_input)
-
-        result = SolverResult(
-            domain="quant" if is_quant else "general",
-            solved=False,
-            help_mode=resolved_help_mode,
-            answer_letter=None,
-            answer_value=None,
-            topic=question_topic,
-            used_retrieval=False,
-            used_generator=False,
-            internal_answer=None,
-            steps=[],
-            teaching_chunks=[],
-            meta={},
-        )
-
-        # 1. Try explainer early so scaffold is available even when solver is weak
-        explainer_result = route_explainer(solver_input)
-        explainer_understood = bool(explainer_result is not None and getattr(explainer_result, "understood", False))
-        explainer_scaffold = _extract_explainer_scaffold(explainer_result) if explainer_understood else {}
-        explainer_summary = getattr(explainer_result, "summary", None) if explainer_understood else None
-        explainer_teaching_points = _safe_meta_list(
-            getattr(explainer_result, "teaching_points", [])
-        ) if explainer_understood else []
-
-        # 1a. Explicit explainer request returns scaffold-rich explainer response
-        if explainer_result is not None and getattr(explainer_result, "understood", False):
-            reply = format_explainer_response(
-                result=explainer_result,
-                tone=tone,
-                verbosity=verbosity,
-                transparency=transparency,
-            )
-            
-            result.domain = "quant" if inferred_category == "Quantitative" or is_quant_question(solver_input) else "general"
-            result.solved = False
-            result.help_mode = detect_help_mode(user_text or solver_input)
-            result.topic = explainer_result.topic
-            result.answer_letter = None
-            result.answer_value = None
-            result.internal_answer = None
-            result.reply = reply
-            result.meta = {
-                "intent": "explain_question",
-                "question_text": solver_input,
-                "used_explainer": True,
-            }
-            return result
-
-        # 2. normal solver path
-        if is_quant:
-            solved_result = route_solver(solver_input)
-
-            if solved_result is not None:
-                result = solved_result
-
-            result.help_mode = resolved_help_mode
-
-            if not result.topic or result.topic in {"general_quant", "general", "unknown"}:
-                result.topic = getattr(explainer_result, "topic", None) if explainer_understood else question_topic
-
-            result.domain = "quant"
-
-        # 2a. Attach explainer scaffold into result meta so generic paths can use it
-        if result.meta is None:
-            result.meta = {}
-
-        if explainer_understood:
-            result.meta["explainer_used"] = True
-            result.meta["bridge_ready"] = bool(getattr(explainer_result, "meta", {}).get("bridge_ready", False))
-            result.meta["hint_style"] = getattr(explainer_result, "meta", {}).get("hint_style")
-            result.meta["explainer_summary"] = explainer_summary
-            result.meta["explainer_teaching_points"] = explainer_teaching_points
-            result.meta["scaffold"] = explainer_scaffold
-
-        # 3. compose base reply
-        reply = _compose_reply(
-            result=result,
-            intent=resolved_intent,
-            verbosity=verbosity,
-            category=inferred_category,
-        )
-
-        # 4. optional retrieval
-        allow_retrieval = should_retrieve(
-            intent=resolved_intent,
-            solved=bool(result.solved),
-            raw_user_text=user_text or solver_input,
-            category=inferred_category,
-            domain=result.domain,
-            topic=result.topic,
-        )
-
-        if allow_retrieval and reply and len(reply) < 220:
-            if retrieval_context:
-                filtered = _filter_retrieved_chunks(
-                    chunks=retrieval_context,
-                    intent=resolved_intent,
-                    topic=result.topic,
-                    question_text=solver_input,
-                    question_type=question_type,
-                )
-                if filtered:
-                    selected_chunks = filtered
-                    result.used_retrieval = True
-                    result.teaching_chunks = filtered
-
-            elif self.retriever is not None:
-                retrieved = self.retriever.search(
-                    query=_build_retrieval_query(
-                        raw_user_text=user_text,
-                        question_text=solver_input,
-                        intent=resolved_intent,
-                        topic=result.topic,
-                        solved=bool(result.solved),
-                        question_type=question_type,
-                        category=inferred_category,
-                    ),
-                    topic=result.topic or "",
-                    intent=resolved_intent,
-                    k=6,
-                )
-                filtered = _filter_retrieved_chunks(
-                    chunks=retrieved,
-                    intent=resolved_intent,
-                    topic=result.topic,
-                    question_text=solver_input,
-                    question_type=question_type,
-                )
-                if filtered:
-                    selected_chunks = filtered
-                    result.used_retrieval = True
-                    result.teaching_chunks = filtered
-
-            if selected_chunks and resolved_help_mode in {"walkthrough", "step_by_step", "method", "explain", "concept"}:
-                teaching_line = _pick_teaching_line(
-                    chunks=selected_chunks,
-                    current_reply=reply,
-                    question_text=solver_input,
-                    topic=result.topic,
-                )
-                if teaching_line:
-                    reply = f"{reply}\n\nKey idea: {teaching_line}"
-
-        # 5. generator only for non-quant
-        should_try_generator = (
-            self.generator is not None
-            and not result.solved
-            and resolved_help_mode not in {"hint", "instruction"}
-            and result.domain != "quant"
-        )
-
-        if should_try_generator:
-            try:
-                generated = self.generator.generate(
-                    user_text=user_text or solver_input,
-                    question_text=solver_input,
-                    topic=result.topic or "",
-                    intent=resolved_intent,
-                    retrieval_context=selected_chunks,
-                    chat_history=chat_history or [],
-                )
-
-                if generated and generated.strip():
-                    candidate = generated.strip()
-
-                    if not _is_bad_generated_reply(candidate, user_text or solver_input):
-                        reply = candidate
-                        result.used_generator = True
-                    else:
-                        reply = _fallback_more_info_reply(
-                            category=inferred_category,
-                            topic=result.topic,
-                            intent=resolved_intent,
-                        )
-                else:
-                    reply = _fallback_more_info_reply(
-                        category=inferred_category,
-                        topic=result.topic,
-                        intent=resolved_intent,
-                    )
-
-            except Exception:
-                reply = _fallback_more_info_reply(
-                    category=inferred_category,
-                    topic=result.topic,
-                    intent=resolved_intent,
-                )
-
-        # 6. final fallback
-        if not reply:
-            reply = _fallback_more_info_reply(
-                category=inferred_category,
-                topic=result.topic,
-                intent=resolved_intent,
-            )
-
-        reply = format_reply(reply, tone, verbosity, transparency, resolved_help_mode)
-
-        result.answer_letter = None
-        result.answer_value = None
-        result.internal_answer = None
-        result.reply = reply
-        result.help_mode = resolved_help_mode
-
-        final_meta = dict(result.meta or {})
-        final_meta.update({
-            "intent": resolved_intent,
-            "question_text": question_text or "",
-            "options_count": len(options_text or []),
-            "category": inferred_category,
-            "question_type": question_type,
-            "classified_topic": question_topic,
-        })
-        result.meta = final_meta
-
-        return result
+    return "\n".join(_dedupe_lines(output)).strip()