Update formatting.py

formatting.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import re
-from typing import Any, List
+from typing import Any, List, Optional
 
 
 def style_prefix(tone: float) -> str:
@@ -54,10 +54,12 @@ def _is_wrapper_line(line: str) -> bool:
         "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",
+        "what to identify",
         "set-up path",
         "setup path",
         "first move",
         "next hint",
+        "next steps",
         "watch out for",
         "variables to define",
         "equations to form",
@@ -67,6 +69,8 @@ def _is_wrapper_line(line: str) -> bool:
         "constraints or conditions",
         "key relationship",
         "concepts you will probably need",
+        "best starting move",
+        "final answer",
     }
     return key in wrapper_lines
 
@@ -107,13 +111,10 @@ def _limit_lines_for_verbosity(lines: list[str], verbosity: float, help_mode: st
 
     if verbosity < 0.2:
         return lines[:1]
-
     if verbosity < 0.45:
         return lines[:2]
-
     if verbosity < 0.75:
         return lines[:3]
-
     return lines
 
 
@@ -181,6 +182,104 @@ def _tone_adjust_line(line: str, tone: float) -> str:
     return line
 
 
+def _coerce_string(value: Any) -> str:
+    return (value or "").strip() if isinstance(value, str) else ""
+
+
+def _coerce_list(value: Any) -> 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 _clean_section_items(items: List[str]) -> List[str]:
+    cleaned = []
+    seen = set()
+
+    for item in items or []:
+        text = (item or "").strip()
+        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
+
+
+def _append_section(lines: List[str], title: str, items: List[str], limit: int) -> None:
+    cleaned = _clean_section_items(items)
+    if not cleaned:
+        return
+
+    lines.append("")
+    lines.append(title)
+    for item in cleaned[:limit]:
+        lines.append(f"- {item}")
+
+
+def _get_scaffold(result: Any):
+    return getattr(result, "scaffold", None)
+
+
+def _explainer_topic(result: Any) -> 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 _safe_solver_steps(steps: Optional[List[str]]) -> List[str]:
+    if not steps:
+        return []
+    banned = [
+        r"\bthe answer is\b",
+        r"\banswer:\b",
+        r"\bfinal answer\b",
+        r"\bx\s*=",
+        r"\by\s*=",
+        r"\bresult is\b",
+        r"\btherefore\b",
+    ]
+    cleaned: List[str] = []
+    for step in steps:
+        s = str(step or "").strip()
+        if not s:
+            continue
+        low = s.lower()
+        if any(re.search(p, low) for p in banned):
+            continue
+        cleaned.append(s)
+    return _dedupe_lines(cleaned)
+
+
+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 _format_answer_mode(
     lines: List[str],
     topic: str,
@@ -239,7 +338,6 @@ def format_reply(core: str, tone: float, verbosity: float, transparency: float,
         return _format_answer_mode(lines, topic, tone, verbosity, transparency)
 
     lines = _limit_lines_for_verbosity(lines, verbosity, help_mode)
-
     if not lines:
         return prefix or "Start with the structure of the problem."
 
@@ -295,92 +393,24 @@ def format_reply(core: str, tone: float, verbosity: float, transparency: float,
     return "\n".join(output).strip()
 
 
-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 _clean_section_items(items: List[str]) -> List[str]:
-    cleaned = []
-    seen = set()
-
-    for item in items or []:
-        text = (item or "").strip()
-        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
-
-
-def _append_section(lines: List[str], title: str, items: List[str], limit: int) -> None:
-    cleaned = _clean_section_items(items)
-    if not cleaned:
-        return
-
-    lines.append("")
-    lines.append(title)
-    for item in cleaned[:limit]:
-        lines.append(f"- {item}")
-
-
-def _coerce_string(value: Any) -> str:
-    return (value or "").strip() if isinstance(value, str) else ""
-
-
-def _coerce_list(value: Any) -> 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: Any):
-    return getattr(result, "scaffold", None)
-
-
-def _explainer_topic(result: Any) -> 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(
+def _build_progression_sections(
     result: Any,
+    help_mode: str,
+    hint_stage: int,
     verbosity: float,
     transparency: float,
+    solver_steps: Optional[List[str]] = None,
+    can_reveal_answer: bool = False,
+    final_answer: Optional[str] = None,
 ) -> List[str]:
     output: List[str] = []
     scaffold = _get_scaffold(result)
-
     if scaffold is None:
         return output
 
     ask = _coerce_string(getattr(scaffold, "ask", ""))
+    concept = _coerce_string(getattr(scaffold, "concept", ""))
+    target = _coerce_string(getattr(scaffold, "target", ""))
     setup_actions = _coerce_list(getattr(scaffold, "setup_actions", []))
     intermediate_steps = _coerce_list(getattr(scaffold, "intermediate_steps", []))
     first_move = _coerce_string(getattr(scaffold, "first_move", ""))
@@ -388,9 +418,97 @@ def _build_scaffold_sections(
     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", []))
+    key_operations = _coerce_list(getattr(scaffold, "key_operations", []))
+
+    safe_steps = _safe_solver_steps(solver_steps)
+
+    if help_mode == "definition":
+        stage = 0
+    elif help_mode in {"walkthrough", "step_by_step"}:
+        stage = 3
+    elif help_mode == "answer" and can_reveal_answer:
+        stage = 3
+    elif help_mode == "answer":
+        stage = max(2, hint_stage)
+    else:
+        stage = min(max(hint_stage, 0), 3)
+
+    if stage == 0:
+        if concept:
+            output.append(concept)
+        if ask:
+            output.append("")
+            output.append("What to identify:")
+            output.append(f"- {ask}")
+        if first_move:
+            output.append("")
+            output.append("First move:")
+            output.append(f"- {first_move}")
+        elif safe_steps:
+            output.append("")
+            output.append("First move:")
+            output.append(f"- {safe_steps[0]}")
+        return output
+
+    if stage == 1:
+        if ask:
+            output.append("What to identify:")
+            output.append(f"- {ask}")
+        if setup_actions:
+            output.append("")
+            output.append("Set-up path:")
+            for item in setup_actions[:2]:
+                output.append(f"- {item}")
+        if first_move:
+            output.append("")
+            output.append("First move:")
+            output.append(f"- {first_move}")
+        if next_hint:
+            output.append("")
+            output.append("Next hint:")
+            output.append(f"- {next_hint}")
+        elif safe_steps:
+            output.append("")
+            output.append("Next hint:")
+            output.append(f"- {safe_steps[0]}")
+        return output
+
+    if stage == 2:
+        if ask:
+            output.append("What to identify:")
+            output.append(f"- {ask}")
+        if target:
+            output.append("")
+            output.append(f"Target: {target}")
+        if setup_actions:
+            output.append("")
+            output.append("Set-up path:")
+            for item in setup_actions[: min(3, len(setup_actions))]:
+                output.append(f"- {item}")
+        progression_steps = intermediate_steps[:2] or safe_steps[:2]
+        if progression_steps:
+            output.append("")
+            output.append("Next steps:")
+            for item in progression_steps:
+                output.append(f"- {item}")
+        if next_hint:
+            output.append("")
+            output.append("Next hint:")
+            output.append(f"- {next_hint}")
+        if variables_to_define and transparency >= 0.45:
+            output.append("")
+            output.append("Variables to define:")
+            for item in variables_to_define[:2]:
+                output.append(f"- {item}")
+        if equations_to_form and transparency >= 0.5:
+            output.append("")
+            output.append("Equations to form:")
+            for item in equations_to_form[:2]:
+                output.append(f"- {item}")
+        return output
 
     if ask:
-        output.append("")
         output.append("What to identify first:")
         output.append(f"- {ask}")
 
@@ -401,11 +519,12 @@ def _build_scaffold_sections(
         for item in setup_actions[:limit]:
             output.append(f"- {item}")
 
-    if verbosity >= 0.55 and intermediate_steps:
+    deep_steps = intermediate_steps or safe_steps
+    if deep_steps:
         output.append("")
         output.append("How to build it:")
         limit = 2 if verbosity < 0.75 else 4
-        for item in intermediate_steps[:limit]:
+        for item in deep_steps[:limit]:
             output.append(f"- {item}")
 
     if first_move:
@@ -418,24 +537,39 @@ def _build_scaffold_sections(
         output.append("Next hint:")
         output.append(f"- {next_hint}")
 
-    if verbosity >= 0.65 and variables_to_define:
+    if hint_ladder and verbosity >= 0.65:
+        output.append("")
+        output.append("Hint ladder:")
+        for item in hint_ladder[:3]:
+            output.append(f"- {item}")
+
+    if variables_to_define and verbosity >= 0.65:
         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:
+    if equations_to_form and transparency >= 0.55:
         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}")
+    if key_operations and transparency >= 0.55:
+        output.append("")
+        output.append("Key operations:")
+        for item in key_operations[:3]:
+            output.append(f"- {item}")
+
+    if (transparency >= 0.6 or verbosity >= 0.75) and common_traps:
+        output.append("")
+        output.append("Watch out for:")
+        for item in common_traps[:4]:
+            output.append(f"- {item}")
+
+    if help_mode == "answer" and can_reveal_answer and final_answer:
+        output.append("")
+        output.append(f"Final answer: {final_answer}")
 
     return output
 
@@ -445,6 +579,11 @@ def format_explainer_response(
     tone: float,
     verbosity: float,
     transparency: float,
+    help_mode: str = "explain",
+    hint_stage: int = 0,
+    solver_steps: Optional[List[str]] = None,
+    can_reveal_answer: bool = False,
+    final_answer: Optional[str] = None,
 ) -> 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."
@@ -462,11 +601,20 @@ def format_explainer_response(
     if summary and not _is_wrapper_line(summary):
         output.append(summary)
 
-    scaffold_sections = _build_scaffold_sections(result, verbosity, transparency)
+    scaffold_sections = _build_progression_sections(
+        result=result,
+        help_mode=help_mode,
+        hint_stage=hint_stage,
+        verbosity=verbosity,
+        transparency=transparency,
+        solver_steps=solver_steps,
+        can_reveal_answer=can_reveal_answer,
+        final_answer=final_answer,
+    )
     if scaffold_sections:
         output.extend(scaffold_sections)
 
-    if teaching_points and verbosity >= 0.5:
+    if teaching_points and verbosity >= 0.55 and hint_stage >= 2:
         output.append("")
         output.append("Key teaching points:")
         limit = 2 if verbosity < 0.75 else 4
@@ -478,11 +626,11 @@ def format_explainer_response(
         output.append(plain)
 
     asks_for = _coerce_string(getattr(result, "asks_for", ""))
-    if asks_for and transparency >= 0.3:
+    if asks_for and transparency >= 0.35 and hint_stage >= 2:
         output.append("")
         output.append(f"The question is asking for: {asks_for}")
 
-    if verbosity >= 0.4:
+    if verbosity >= 0.45 and hint_stage >= 2:
         _append_section(
             output,
             "What the question gives you:",
@@ -490,7 +638,7 @@ def format_explainer_response(
             5 if verbosity >= 0.7 else 3,
         )
 
-    if verbosity >= 0.65:
+    if verbosity >= 0.7 and hint_stage >= 3:
         _append_section(
             output,
             "Constraints or conditions:",
@@ -498,7 +646,7 @@ def format_explainer_response(
             5,
         )
 
-    if transparency >= 0.45:
+    if transparency >= 0.5 and hint_stage >= 2:
         _append_section(
             output,
             "Key relationship:",
@@ -506,7 +654,7 @@ def format_explainer_response(
             4,
         )
 
-    if transparency >= 0.5:
+    if transparency >= 0.55 and hint_stage >= 2:
         _append_section(
             output,
             "Concepts you will probably need:",
@@ -514,7 +662,7 @@ def format_explainer_response(
             4,
         )
 
-    if transparency >= 0.55 or verbosity >= 0.7:
+    if (transparency >= 0.6 or verbosity >= 0.75) and hint_stage >= 3:
         _append_section(
             output,
             "Watch out for:",
@@ -523,7 +671,7 @@ def format_explainer_response(
         )
 
     strategy_hint = _coerce_string(getattr(result, "strategy_hint", ""))
-    if strategy_hint and verbosity >= 0.35 and not _is_wrapper_line(strategy_hint):
+    if strategy_hint and verbosity >= 0.35 and not _is_wrapper_line(strategy_hint) and hint_stage >= 1:
         output.append("")
         output.append(f"Best starting move: {strategy_hint}")