Update formatting.py

formatting.py

@@ -1,3 +1,4 @@
+# formatting.py
 from __future__ import annotations
 
 import re
@@ -55,6 +56,15 @@ def _is_wrapper_line(line: str) -> bool:
         "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
 
@@ -274,13 +284,118 @@ def _append_section(lines: List[str], title: str, items: List[str], limit: int)
         lines.append(f"- {item}")
 
 
+def _coerce_string(value) -> str:
+    return (value or "").strip() if isinstance(value, str) else ""
+
+
+def _coerce_list(value) -> List[str]:
+    if not value:
+        return []
+    if isinstance(value, list):
+        return [str(v).strip() for v in value if str(v).strip()]
+    if isinstance(value, tuple):
+        return [str(v).strip() for v in value if str(v).strip()]
+    if isinstance(value, str):
+        text = value.strip()
+        return [text] if text else []
+    return []
+
+
+def _get_scaffold(result: ExplainerResult):
+    return getattr(result, "scaffold", 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 _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 result.understood:
+    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] = []
@@ -290,11 +405,34 @@ def format_explainer_response(
         output.append(header)
         output.append("")
 
-    plain = (getattr(result, "plain_english", "") or "").strip()
-    if plain and not _is_wrapper_line(plain):
+    # -------------------------------------------------
+    # 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 = (getattr(result, "asks_for", "") or "").strip()
+    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}")
@@ -339,11 +477,34 @@ def format_explainer_response(
             4,
         )
 
-    strategy_hint = (getattr(result, "strategy_hint", "") or "").strip()
+    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: