Update conversation_logic.py

conversation_logic.py

@@ -1,4 +1,3 @@
-# conversation_logic.py
 from __future__ import annotations
 
 import re
@@ -152,6 +151,203 @@ def _safe_steps(steps: List[str]) -> List[str]:
     return cleaned
 
 
+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:
+        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()
+        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 _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_reply(
+    intent: str,
+    help_mode: str,
+    scaffold: Dict[str, Any],
+    summary: Optional[str],
+    teaching_points: List[str],
+    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] = []
+        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]}")
+
+        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
+
+
 def _compose_reply(
     result: SolverResult,
     intent: str,
@@ -160,6 +356,17 @@ def _compose_reply(
 ) -> 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":
@@ -179,6 +386,9 @@ def _compose_reply(
         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.",
@@ -217,6 +427,9 @@ def _compose_reply(
         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()
 
@@ -234,11 +447,15 @@ def _compose_reply(
         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."
@@ -288,6 +505,9 @@ def _compose_reply(
 
         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."
 
@@ -328,19 +548,6 @@ def is_explainer_request(text: str) -> bool:
     return any(p in t for p in explainer_signals)
 
 
-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 _infer_structure_terms(question_text: str, topic: Optional[str], question_type: Optional[str]) -> List[str]:
     terms: List[str] = []
 
@@ -822,48 +1029,6 @@ def _pick_teaching_line(
     return best_line
 
 
-def _safe_meta_list(items: Any) -> List[str]:
-    if not items:
-        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()
-        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 _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)),
-    }
-
-
 class ConversationEngine:
     def __init__(
         self,
@@ -925,47 +1090,49 @@ class ConversationEngine:
             meta={},
         )
 
-        # 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,
-                )
+        # 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 is_explainer_request(user_text or solver_input) and explainer_understood:
+            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
+            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": explainer_summary,
+                "explainer_teaching_points": explainer_teaching_points,
+                "scaffold": explainer_scaffold,
+            }
+            return result
 
         # 2. normal solver path
         if is_quant:
@@ -977,10 +1144,22 @@ class ConversationEngine:
             result.help_mode = resolved_help_mode
 
             if not result.topic or result.topic in {"general_quant", "general", "unknown"}:
-                result.topic = question_topic
+                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,
@@ -1110,14 +1289,16 @@ class ConversationEngine:
         result.internal_answer = None
         result.reply = reply
         result.help_mode = resolved_help_mode
-        result.meta = {
+
+        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,
-            "explainer_used": False,
-        }
+        })
+        result.meta = final_meta
 
         return result