Update formatting.py

formatting.py

@@ -1,525 +1,1123 @@
-# formatting.py
+# conversation_logic.py
 from __future__ import annotations
 
 import re
-from typing import List
-
-from models import ExplainerResult
+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 _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))
+    )
 
+    if t == "ratio" and not has_ratio_form and has_algebra_form:
+        t = "algebra"
 
-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 t not in {"general_quant", "general", "unknown", ""}:
+        return t
 
+    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"
 
-def _clean_lines(core: str) -> list[str]:
-    lines = []
-    for line in (core or "").splitlines():
-        cleaned = line.strip()
-        if cleaned:
-            lines.append(cleaned)
-    return lines
+    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}")
+    return lines
 
-def _is_wrapper_line(line: str) -> bool:
-    key = _normalize_key(line).rstrip(":")
-    wrapper_lines = {
-        "let's work through it.",
-        "lets work through it.",
-        "let's solve it efficiently.",
-        "lets solve it efficiently.",
-        "you've got this — let's solve it cleanly.",
-        "youve got this — lets solve it cleanly.",
-        "you’ve got this — let’s solve it cleanly.",
-        "walkthrough",
-        "hint",
-        "steps",
-        "method",
-        "explanation",
-        "key idea",
-        "question breakdown",
-        "here’s what the question is really asking",
-        "here's what the question is really asking",
-        "let’s break down what the question is asking",
-        "lets break down what the question is asking",
-        "you’ve got this — here’s what the question is really asking",
-        "you've got this — here's what the question is really asking",
-        "what to identify first",
-        "set-up path",
-        "setup path",
-        "first move",
-        "next hint",
-        "watch out for",
-        "variables to define",
-        "equations to form",
-        "key teaching points",
-    }
-    return key in wrapper_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",
+    ]
+
+    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)
 
-def _strip_leading_wrapper_lines(lines: list[str]) -> list[str]:
-    cleaned = list(lines)
-    while cleaned and _is_wrapper_line(cleaned[0]):
-        cleaned.pop(0)
     return cleaned
 
 
-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 _limit_lines_for_verbosity(lines: list[str], verbosity: float, help_mode: str) -> list[str]:
-    if not lines:
-        return lines
-
-    if help_mode == "hint":
-        return lines[:1]
-
-    if verbosity < 0.2:
-        return lines[:1]
-
-    if verbosity < 0.45:
-        return lines[:2]
-
-    if verbosity < 0.75:
-        return lines[:3]
-
-    return lines
-
-
-def _extract_topic_from_lines(lines: list[str]) -> str:
-    joined = " ".join(lines).lower()
+def _compose_reply(
+    result: SolverResult,
+    intent: str,
+    verbosity: float,
+    category: Optional[str] = None,
+) -> str:
+    steps = _safe_steps(result.steps or [])
+    topic = (result.topic or "").lower().strip()
+
+    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 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 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 steps:
+            return f"First step: {steps[0]}"
+        return "First, identify the key relationship or comparison in the question."
+
+    if intent == "definition":
+        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 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",
+    ]
 
-    if any(word in joined for word in ["equation", "variable", "isolate", "algebra"]):
-        return "algebra"
-    if any(word in joined for word in ["percent", "percentage"]):
-        return "percent"
-    if any(word in joined for word in ["ratio", "proportion"]):
-        return "ratio"
-    if any(word in joined for word in ["probability", "outcome"]):
-        return "probability"
-    if any(word in joined for word in ["mean", "median", "average"]):
-        return "statistics"
-    if any(word in joined for word in ["triangle", "circle", "angle", "area", "perimeter"]):
-        return "geometry"
-    if any(word in joined for word in ["integer", "factor", "multiple", "prime", "remainder"]):
-        return "number_theory"
+    return any(p in t for p in explainer_signals)
 
-    return "general"
 
+def _normalize_text(text: str) -> str:
+    return re.sub(r"\s+", " ", (text or "").strip().lower())
 
-def _why_line(topic: str, lines: list[str]) -> str:
-    joined = " ".join(lines).lower()
 
-    if topic == "algebra":
-        if "equation" in joined or "isolate" in joined or "variable" in joined:
-            return "Why: this works because inverse operations undo what is attached to the variable while keeping the equation balanced."
-        return "Why: the goal is to isolate the variable without changing the balance of the relationship."
-
-    if topic == "percent":
-        return "Why: percent relationships depend on identifying the correct base value before calculating the change or part."
+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 _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 topic == "ratio":
-        return "Why: ratios compare parts consistently, so the relationship must stay proportional."
 
-    if topic == "probability":
-        return "Why: probability compares favorable outcomes to the total number of possible outcomes."
+def _intent_keywords(intent: str) -> List[str]:
+    return INTENT_KEYWORDS.get(intent, [])
 
-    if topic == "statistics":
-        return "Why: statistical measures describe the distribution, so the method depends on what feature the question asks for."
 
-    if topic == "geometry":
-        return "Why: geometry problems depend on the properties of the figure and the relationships between its parts."
+def _is_direct_solve_request(text: str, intent: str) -> bool:
+    if intent == "answer":
+        return True
 
-    if topic == "number_theory":
-        return "Why: number properties such as divisibility, factors, and remainders follow fixed rules that guide the method."
+    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
 
-    return "Why: focus on the structure of the problem before doing any calculations."
 
+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()
 
-def _tone_adjust_line(line: str, tone: float) -> str:
-    line = (line or "").strip()
-    if not line:
-        return line
+    if intent == "hint":
+        return False
 
-    if tone < 0.25:
-        line = re.sub(r"^let’s\s+", "", line, flags=re.IGNORECASE)
-        line = re.sub(r"^let's\s+", "", line, flags=re.IGNORECASE)
-        line = re.sub(r"^here is the idea in context:\s*", "", line, flags=re.IGNORECASE)
-        return line.strip()
+    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
 
-    return line
+    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"}
 
-def format_reply(core: str, tone: float, verbosity: float, transparency: float, help_mode: str) -> str:
-    prefix = style_prefix(tone)
-    core = (core or "").strip()
+    if not solved and normalized_category in {"Verbal", "DataInsight"}:
+        return True
 
-    if not core:
-        return prefix or "Start with the structure of the problem."
+    return False
 
-    lines = _clean_lines(core)
-    lines = _strip_leading_wrapper_lines(lines)
-    lines = [_tone_adjust_line(line, tone) for line in lines]
-    lines = [line for line in lines if line]
-    lines = _dedupe_lines(lines)
-    lines = _limit_lines_for_verbosity(lines, verbosity, help_mode)
 
-    if not lines:
-        return prefix or "Start with the structure of the problem."
+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
 
-    topic = _extract_topic_from_lines(lines)
+    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
 
-    output: list[str] = []
+        if cleaned:
+            parts.append(cleaned)
+        else:
+            parts.append(raw)
 
-    if prefix:
-        output.append(prefix)
-        output.append("")
+    normalized_category = normalize_category(category)
+    if normalized_category and normalized_category != "General":
+        parts.append(normalized_category)
 
-    if help_mode == "hint":
-        output.append("Hint:")
-        output.extend(lines[:1])
+    if topic:
+        parts.append(topic)
 
-        if transparency >= 0.8:
-            output.append("")
-            output.append(_why_line(topic, lines[:1]))
+    if question_type:
+        parts.append(question_type.replace("_", " "))
 
-        return "\n".join(output).strip()
+    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")
 
-    if help_mode == "walkthrough":
-        output.append("Walkthrough:")
-        output.extend(lines)
+    return " ".join(parts).strip()
 
-        if transparency >= 0.8:
-            output.append("")
-            output.append(_why_line(topic, lines))
 
-        return "\n".join(output).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 help_mode in {"step_by_step", "method", "explain", "concept"}:
-        label = {
-            "step_by_step": "Steps:",
-            "method": "Method:",
-            "explain": "Explanation:",
-            "concept": "Key idea:",
-        }.get(help_mode, "Explanation:")
-        output.append(label)
-        output.extend(lines)
+    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 transparency >= 0.75:
-            output.append("")
-            output.append(_why_line(topic, lines))
+    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 "\n".join(output).strip()
+    return (
+        "I need a bit more information to help properly. "
+        "Please send the full question or exact wording."
+    )
 
-    output.extend(lines)
 
-    if transparency >= 0.85 and help_mode != "answer":
-        output.append("")
-        output.append(_why_line(topic, lines))
+def _is_bad_generated_reply(text: str, user_text: str = "") -> bool:
+    t = (text or "").strip()
+    tl = t.lower()
+    ul = (user_text or "").strip().lower()
 
-    return "\n".join(output).strip()
+    if not t:
+        return True
 
+    if len(t) < 12:
+        return True
 
-# -------------------------------------------------
-# Explainer formatting
-# -------------------------------------------------
+    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 _explainer_header(tone: float) -> str:
-    if tone < 0.2:
-        return "Question breakdown:"
-    if tone < 0.45:
-        return "Here’s what the question is really asking:"
-    if tone < 0.75:
-        return "Let’s break down what the question is asking:"
-    return "You’ve got this — here’s what the question is really asking:"
 
+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"],
+    }
 
-def _clean_section_items(items: List[str]) -> List[str]:
-    cleaned = []
-    seen = set()
+    for chunk in chunks:
+        raw_text = (chunk.text or "").strip()
+        if not raw_text:
+            continue
 
-    for item in items or []:
-        text = (item or "").strip()
+        text = _clean_teaching_text(raw_text)
         if not text:
             continue
-        if _is_wrapper_line(text):
-            continue
-        key = _normalize_key(text)
-        if key in seen:
-            continue
-        seen.add(key)
-        cleaned.append(text)
 
-    return cleaned
+        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
+        )
 
-def _append_section(lines: List[str], title: str, items: List[str], limit: int) -> None:
-    cleaned = _clean_section_items(items)
-    if not cleaned:
-        return
+        if len(text.split()) < 5:
+            score -= 2.0
 
-    lines.append("")
-    lines.append(title)
-    for item in cleaned[:limit]:
-        lines.append(f"- {item}")
+        if score > best_score:
+            best_score = score
+            best_line = text
 
+    if best_score < 2.5:
+        return None
 
-def _coerce_string(value) -> str:
-    return (value or "").strip() if isinstance(value, str) else ""
+    return best_line
 
 
-def _coerce_list(value) -> List[str]:
-    if not value:
+def _safe_meta_list(items: Any) -> List[str]:
+    if not items:
         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()
+    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()
         return [text] if text else []
     return []
 
 
-def _get_scaffold(result: ExplainerResult):
-    return getattr(result, "scaffold", None)
+def _safe_meta_text(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
 
 
-def _explainer_topic(result: ExplainerResult) -> str:
-    topic = _coerce_string(getattr(result, "topic", ""))
-    if topic:
-        return topic
-
-    joined = " ".join(
-        _coerce_list(getattr(result, "teaching_points", []))
-        + _coerce_list(getattr(result, "givens", []))
-        + _coerce_list(getattr(result, "relationships", []))
-    )
-    return _extract_topic_from_lines([joined]) if joined else "general"
+def _extract_explainer_scaffold(explainer_result: Any) -> Dict[str, Any]:
+    scaffold = getattr(explainer_result, "scaffold", None)
 
+    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_sections(
-    result: ExplainerResult,
-    verbosity: float,
-    transparency: float,
-) -> List[str]:
-    output: List[str] = []
-    scaffold = _get_scaffold(result)
 
-    if scaffold is None:
-        return output
-
-    ask = _coerce_string(getattr(scaffold, "ask", ""))
-    setup_actions = _coerce_list(getattr(scaffold, "setup_actions", []))
-    intermediate_steps = _coerce_list(getattr(scaffold, "intermediate_steps", []))
-    first_move = _coerce_string(getattr(scaffold, "first_move", ""))
-    next_hint = _coerce_string(getattr(scaffold, "next_hint", ""))
-    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", []))
-
-    if ask:
-        output.append("")
-        output.append("What to identify first:")
-        output.append(f"- {ask}")
-
-    if setup_actions:
-        output.append("")
-        output.append("Set-up path:")
-        limit = 2 if verbosity < 0.4 else 3 if verbosity < 0.75 else 5
-        for item in setup_actions[:limit]:
-            output.append(f"- {item}")
-
-    if verbosity >= 0.55 and intermediate_steps:
-        output.append("")
-        output.append("How to build it:")
-        limit = 2 if verbosity < 0.75 else 4
-        for item in intermediate_steps[:limit]:
-            output.append(f"- {item}")
-
-    if first_move:
-        output.append("")
-        output.append("First move:")
-        output.append(f"- {first_move}")
-
-    if next_hint and (transparency >= 0.35 or verbosity >= 0.45):
-        output.append("")
-        output.append("Next hint:")
-        output.append(f"- {next_hint}")
-
-    if verbosity >= 0.65 and variables_to_define:
-        output.append("")
-        output.append("Variables to define:")
-        for item in variables_to_define[:3]:
-            output.append(f"- {item}")
-
-    if transparency >= 0.55 and equations_to_form:
-        output.append("")
-        output.append("Equations to form:")
-        for item in equations_to_form[:3]:
-            output.append(f"- {item}")
-
-    if transparency >= 0.6 or verbosity >= 0.75:
-        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: ExplainerResult,
-    tone: float,
-    verbosity: float,
-    transparency: float,
-) -> 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] = []
-
-    header = _explainer_header(tone)
-    if header:
-        output.append(header)
-        output.append("")
-
-    # -------------------------------------------------
-    # New publish-ready scaffold-aware path
-    # -------------------------------------------------
-    summary = _coerce_string(getattr(result, "summary", ""))
-    teaching_points = _coerce_list(getattr(result, "teaching_points", []))
-
-    if summary and not _is_wrapper_line(summary):
-        output.append(summary)
-
-    scaffold_sections = _build_scaffold_sections(result, verbosity, transparency)
-    if scaffold_sections:
-        output.extend(scaffold_sections)
-
-    if teaching_points and verbosity >= 0.5:
-        output.append("")
-        output.append("Key teaching points:")
-        limit = 2 if verbosity < 0.75 else 4
-        for item in teaching_points[:limit]:
-            output.append(f"- {item}")
-
-    # -------------------------------------------------
-    # Backward-compatible support for older explainer fields
-    # -------------------------------------------------
-    plain = _coerce_string(getattr(result, "plain_english", ""))
-    if plain and not summary and not _is_wrapper_line(plain):
-        output.append(plain)
-
-    asks_for = _coerce_string(getattr(result, "asks_for", ""))
-    if asks_for and transparency >= 0.3:
-        output.append("")
-        output.append(f"The question is asking for: {asks_for}")
-
-    if verbosity >= 0.4:
-        _append_section(
-            output,
-            "What the question gives you:",
-            getattr(result, "givens", []) or [],
-            5 if verbosity >= 0.7 else 3,
+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,
         )
-
-    if verbosity >= 0.65:
-        _append_section(
-            output,
-            "Constraints or conditions:",
-            getattr(result, "constraints", []) or [],
-            5,
+        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={},
         )
 
-    if transparency >= 0.45:
-        _append_section(
-            output,
-            "Key relationship:",
-            getattr(result, "relationships", []) or [],
-            4,
+        # 1. explainer path first
+        if is_explainer_request(user_text or solver_input):
+            explainer_result = route_explainer(solver_input)
+
+            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,
+                )
+
+                scaffold_meta = _extract_explainer_scaffold(explainer_result)
+
+                result.domain = "quant" if is_quant else "general"
+                result.solved = False
+                result.help_mode = "explain"
+                result.topic = getattr(explainer_result, "topic", None) or question_topic
+                result.answer_letter = None
+                result.answer_value = None
+                result.internal_answer = None
+                result.used_retrieval = False
+                result.used_generator = False
+                result.reply = reply
+                result.meta = {
+                    "intent": "explain_question",
+                    "question_text": question_text or "",
+                    "options_count": len(options_text or []),
+                    "category": inferred_category,
+                    "question_type": question_type,
+                    "classified_topic": question_topic,
+                    "explainer_used": True,
+                    "bridge_ready": bool(getattr(explainer_result, "meta", {}).get("bridge_ready", False)),
+                    "hint_style": getattr(explainer_result, "meta", {}).get("hint_style"),
+                    "explainer_summary": getattr(explainer_result, "summary", None),
+                    "explainer_teaching_points": _safe_meta_list(
+                        getattr(explainer_result, "teaching_points", [])
+                    ),
+                    "scaffold": scaffold_meta,
+                }
+                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 = question_topic
+
+            result.domain = "quant"
+
+        # 3. compose base reply
+        reply = _compose_reply(
+            result=result,
+            intent=resolved_intent,
+            verbosity=verbosity,
+            category=inferred_category,
         )
 
-    if transparency >= 0.5:
-        _append_section(
-            output,
-            "Concepts you will probably need:",
-            getattr(result, "needed_concepts", []) or [],
-            4,
+        # 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 transparency >= 0.55 or verbosity >= 0.7:
-        _append_section(
-            output,
-            "Watch out for:",
-            getattr(result, "trap_notes", []) or [],
-            4,
+        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"
         )
 
-    strategy_hint = _coerce_string(getattr(result, "strategy_hint", ""))
-    if strategy_hint and verbosity >= 0.35 and not _is_wrapper_line(strategy_hint):
-        output.append("")
-        output.append(f"Best starting move: {strategy_hint}")
-
-    if transparency >= 0.8:
-        topic = _explainer_topic(result)
-        why_seed_lines: List[str] = []
-
-        if summary:
-            why_seed_lines.append(summary)
-
-        scaffold = _get_scaffold(result)
-        if scaffold is not None:
-            ask = _coerce_string(getattr(scaffold, "ask", ""))
-            first_move = _coerce_string(getattr(scaffold, "first_move", ""))
-            if ask:
-                why_seed_lines.append(ask)
-            if first_move:
-                why_seed_lines.append(first_move)
-
-        if not why_seed_lines:
-            why_seed_lines.extend(teaching_points[:2])
-
-        if why_seed_lines:
-            output.append("")
-            output.append(_why_line(topic, why_seed_lines))
-
-    final_lines = []
-    previous_key = None
-    for line in output:
-        if line is None:
-            continue
-        text = str(line).rstrip()
-        key = _normalize_key(text)
-        if key == previous_key and key:
-            continue
-        final_lines.append(text)
-        previous_key = key
-
-    text = "\n".join(final_lines).strip()
-
-    if not text:
-        return "I can help explain what the question is asking, but I need the full wording of the question."
-
-    return text
+        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
+        result.meta = {
+            "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,
+            "explainer_used": False,
+        }
+
+        return result