Update conversation_logic.py

conversation_logic.py

@@ -1,393 +1,582 @@
 from __future__ import annotations
 
 import re
-from typing import Any, List, Optional
+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
+
+
+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))
+    )
 
+    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 _normalize_key(text: str) -> str:
-    text = (text or "").strip().lower()
-    text = text.replace("’", "'")
-    text = re.sub(r"\s+", " ", text)
-    return text
+    if c == "DataInsight":
+        return "data"
+    if c == "Verbal":
+        return "verbal"
+    if c == "Quantitative":
+        return "quant"
 
+    return "general"
+
+
+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",
+        r"\bfinal answer\b",
+    ]
 
-def _clean_lines(core: str) -> list[str]:
-    lines = []
-    for line in (core or "").splitlines():
-        cleaned = line.strip()
-        if cleaned:
-            lines.append(cleaned)
-    return lines
+    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 _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 _normalize_text(text: str) -> str:
+    return re.sub(r"\s+", " ", (text or "").strip().lower())
 
-def _coerce_string(value: Any) -> str:
-    return (value or "").strip() if isinstance(value, str) else ""
 
+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 _coerce_list(value: Any) -> 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 _safe_append(lines: List[str], value: str) -> None:
-    text = (value or "").strip()
-    if text:
-        lines.append(text)
-
+def _safe_meta_text(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or 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"
 
+def _extract_explainer_scaffold(explainer_result: Any) -> Dict[str, Any]:
+    scaffold = getattr(explainer_result, "scaffold", None)
 
-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,
+    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)),
+        "solution_path_type": _safe_meta_text(getattr(scaffold, "solution_path_type", None)),
+        "key_operations": _safe_meta_list(getattr(scaffold, "key_operations", [])),
+        "hint_ladder": _safe_meta_list(getattr(scaffold, "hint_ladder", [])),
+    }
+
+
+def _build_scaffold_reply(
+    intent: str,
     help_mode: str,
-    hint_stage: int = 0,
-    topic: Optional[str] = None,
-) -> str:
-    prefix = style_prefix(tone)
-    core = (core or "").strip()
-
-    if not core:
-        return prefix or "Start with the structure of the problem."
-
-    lines = _dedupe_lines(_clean_lines(core))
-    if not lines:
-        return prefix or "Start with the structure of the problem."
-
-    resolved_topic = _extract_topic_from_text(core, topic)
-
-    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,
+    scaffold: Dict[str, Any],
+    summary: Optional[str],
+    teaching_points: List[str],
     verbosity: float,
     transparency: float,
-) -> List[str]:
-    output: List[str] = []
-    scaffold = _get_scaffold(result)
-    if scaffold is None:
-        return output
-
-    stage = max(0, min(int(hint_stage), 3))
-
-    concept = _coerce_string(getattr(scaffold, "concept", ""))
-    ask = _coerce_string(getattr(scaffold, "ask", ""))
-    first_move = _coerce_string(getattr(scaffold, "first_move", ""))
-    next_hint = _coerce_string(getattr(scaffold, "next_hint", ""))
-    setup_actions = _coerce_list(getattr(scaffold, "setup_actions", []))
-    intermediate_steps = _coerce_list(getattr(scaffold, "intermediate_steps", []))
-    variables_to_define = _coerce_list(getattr(scaffold, "variables_to_define", []))
-    equations_to_form = _coerce_list(getattr(scaffold, "equations_to_form", []))
-    common_traps = _coerce_list(getattr(scaffold, "common_traps", []))
-    hint_ladder = _coerce_list(getattr(scaffold, "hint_ladder", []))
-
-    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:
+) -> 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 []
+
+    target_mode = help_mode or intent
+
+    if target_mode == "hint" or intent == "hint":
+        return first_move or next_hint or (setup_actions[0] if setup_actions else None) or ask or (teaching_points[0] if teaching_points else None)
+
+    if target_mode == "instruction" or intent == "instruction":
         if first_move:
-            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 setup_actions:
-        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}")
-
-    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,
-    transparency: float,
-    hint_stage: int = 0,
-) -> str:
-    if not result or not getattr(result, "understood", False):
-        return "I can help explain what the question is asking, but I need the full wording of the question."
+            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"}:
+        sequence: List[str] = []
+        if ask:
+            sequence.append(f"Identify this first: {ask}")
+        if first_move and first_move not in sequence:
+            sequence.append(first_move)
+        sequence.extend(setup_actions)
+        sequence.extend(intermediate_steps)
+        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
+
+        shown = sequence[:1] if verbosity < 0.25 else sequence[:2] if verbosity < 0.6 else sequence[:4] if verbosity < 0.85 else 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}")
+        if first_move:
+            lines.append(first_move)
+        lines.extend(setup_actions[:2])
+        if transparency >= 0.45:
+            lines.extend(intermediate_steps[:2])
+        if next_hint and transparency >= 0.65:
+            lines.append(f"Next idea: {next_hint}")
+
+        if not lines and teaching_points:
+            lines.extend(teaching_points[:2])
 
-    output: List[str] = []
-    prefix = style_prefix(tone)
-    if prefix:
-        output.append(prefix)
-        output.append("")
+        if not lines:
+            return None
 
-    output.append("Question breakdown:")
-    output.append("")
+        return "\n".join(f"- {s}" for s in lines)
 
-    summary = _coerce_string(getattr(result, "summary", ""))
-    if summary:
-        output.append(summary)
+    return first_move or (setup_actions[0] if setup_actions else None) or summary or (teaching_points[0] if teaching_points else None)
 
-    scaffold_lines = _staged_scaffold_lines(
-        result=result,
-        hint_stage=hint_stage,
+
+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()
+    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=transparency,
+        transparency=0.5,
     )
-    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 intent == "hint":
+        return scaffold_reply or (steps[0] if steps else "Start by identifying the main relationship in the problem.")
+
+    if intent == "instruction":
+        return scaffold_reply or (f"First step: {steps[0]}" if steps else "First, identify the key relationship or comparison in the question.")
+
+    if intent == "definition":
+        return scaffold_reply or (f"Here is the idea in context:\n- {steps[0]}" if steps else "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 scaffold_reply:
+            return scaffold_reply
+        if steps:
+            shown_steps = steps[:1] if verbosity < 0.25 else steps[:2] if verbosity < 0.6 else steps[:3] if verbosity < 0.85 else steps
+            return "\n".join(f"- {s}" for s in shown_steps)
+
+    if steps:
+        shown_steps = steps[:1] if verbosity < 0.35 else steps[:2]
+        return shown_steps[0] if len(shown_steps) == 1 else "\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 need the full question wording to guide this properly."
+
+
+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 _is_progression_request(text: str) -> bool:
+    t = (text or "").strip().lower()
+    return any(
+        phrase in t
+        for phrase in [
+            "hint",
+            "next hint",
+            "another hint",
+            "next step",
+            "first step",
+            "walk me through",
+            "step by step",
+            "show the steps",
+            "go on",
+            "continue",
+        ]
     )
 
-    if transparency >= 0.8:
-        output.append("")
-        output.append(_why_line(topic))
 
-    return "\n".join(_dedupe_lines(output)).strip()
+def _history_hint_stage(chat_history: Optional[List[Dict[str, Any]]]) -> int:
+    if not chat_history:
+        return 0
+
+    best = 0
+    for item in chat_history:
+        if not isinstance(item, dict):
+            continue
+
+        if "hint_stage" in item:
+            try:
+                best = max(best, int(item["hint_stage"]))
+            except Exception:
+                pass
+
+        meta = item.get("meta")
+        if isinstance(meta, dict) and "hint_stage" in meta:
+            try:
+                best = max(best, int(meta["hint_stage"]))
+            except Exception:
+                pass
+
+    return min(best, 3)
+
+
+def _resolve_hint_stage(
+    user_text: str,
+    intent: str,
+    help_mode: str,
+    chat_history: Optional[List[Dict[str, Any]]],
+) -> int:
+    history_stage = _history_hint_stage(chat_history)
+    low = (user_text or "").strip().lower()
+
+    if help_mode == "definition":
+        return 0
+
+    if help_mode in {"walkthrough", "step_by_step"}:
+        return 3
+
+    if _is_direct_solve_request(user_text, intent):
+        return 3
+
+    if any(p in low for p in ["next hint", "another hint", "next step", "continue", "go on"]):
+        return min(history_stage + 1, 3)
+
+    if "first step" in low:
+        return max(history_stage, 1)
+
+    if "hint" in low:
+        return max(history_stage, 1)
+
+    if intent in {"method", "instruction", "explain", "concept"}:
+        return max(history_stage, 1)
+
+    if _is_progression_request(low):
+        return min(max(history_stage, 1), 3)
+
+    return history_stage
+
+
+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()
+
+        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,
+        )
+
+        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={},
+        )
+
+        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 []
+
+        if is_quant:
+            solved_result = route_solver(solver_input)
+            if solved_result is not None:
+                result = solved_result
+
+            result.help_mode = resolved_help_mode
+            result.domain = "quant"
+
+            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.meta = result.meta or {}
+
+        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
+
+        hint_stage = _resolve_hint_stage(
+            user_text=user_text or solver_input,
+            intent=resolved_intent,
+            help_mode=resolved_help_mode,
+            chat_history=chat_history,
+        )
+
+        result.meta["hint_stage"] = hint_stage
+        result.meta["max_stage"] = 3
+        result.meta["can_reveal_answer"] = bool(
+            result.solved and _is_direct_solve_request(user_text or solver_input, resolved_intent) and hint_stage >= 3
+        )
+
+        if explainer_understood:
+            reply = format_explainer_response(
+                result=explainer_result,
+                tone=tone,
+                verbosity=verbosity,
+                transparency=transparency,
+                hint_stage=hint_stage,
+            )
+        else:
+            reply = _compose_reply(
+                result=result,
+                intent=resolved_intent,
+                verbosity=verbosity,
+                category=inferred_category,
+            )
+            reply = format_reply(
+                reply,
+                tone=tone,
+                verbosity=verbosity,
+                transparency=transparency,
+                help_mode=resolved_help_mode,
+                hint_stage=hint_stage,
+                topic=result.topic,
+            )
+
+        if not result.meta.get("can_reveal_answer", False):
+            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
+        result.meta["question_text"] = question_text or ""
+        result.meta["options_count"] = len(options_text or [])
+        result.meta["category"] = inferred_category
+        result.meta["classified_topic"] = question_topic
+
+        return result