Update formatting.py

formatting.py

@@ -1,228 +1,3 @@
-from __future__ import annotations
-
-import re
-from typing import Any, List, Optional
-
-
-def style_prefix(tone: float) -> str:
-    if tone < 0.2:
-        return ""
-    if tone < 0.45:
-        return "ok.."
-    if tone < 0.75:
-        return "Let’s work through it."
-    return "You’ve got this — let’s solve it cleanly."
-
-
-def _normalize_key(text: str) -> str:
-    text = (text or "").strip().lower()
-    text = text.replace("’", "'")
-    text = re.sub(r"\s+", " ", text)
-    return text
-
-
-def _clean_lines(core: str) -> list[str]:
-    lines = []
-    for line in (core or "").splitlines():
-        cleaned = line.strip()
-        if cleaned:
-            lines.append(cleaned)
-    return lines
-
-
-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 _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 _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 _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,
-    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,
@@ -248,77 +23,122 @@ def _staged_scaffold_lines(
     hint_ladder = _coerce_list(getattr(scaffold, "hint_ladder", []))
     key_operations = _coerce_list(getattr(scaffold, "key_operations", []))
 
-    if concept and stage == 0 and transparency >= 0.75:
-        output.append("Core idea:")
-        output.append(f"- {concept}")
-        output.append("")
+    # STAGE 0 = full scaffold / walkthrough
+    if stage == 0:
+        if concept 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 ask:
+            output.append("What to identify first:")
+            output.append(f"- {ask}")
 
-    if stage == 0:
-        if first_move:
+        if setup_actions:
             output.append("")
-            output.append("First move:")
-            output.append(f"- {first_move}")
-        elif hint_ladder:
+            output.append("Set-up path:")
+            for item in _limit_steps(setup_actions, verbosity, minimum=2):
+                output.append(f"- {item}")
+
+        if first_move or hint_ladder:
             output.append("")
             output.append("First move:")
-            output.append(f"- {hint_ladder[0]}")
-        return output
+            output.append(f"- {first_move or hint_ladder[0]}")
 
-    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 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 first_move:
-        output.append("")
-        output.append("First move:")
-        output.append(f"- {first_move}")
+        if variables_to_define:
+            output.append("")
+            output.append("Variables to define:")
+            for item in variables_to_define[:3]:
+                output.append(f"- {item}")
 
-    if stage == 1:
-        if next_hint:
+        if equations_to_form:
             output.append("")
-            output.append("Next hint:")
-            output.append(f"- {next_hint}")
-        elif len(hint_ladder) >= 2:
+            output.append("Equations to form:")
+            for item in equations_to_form[:3]:
+                output.append(f"- {item}")
+
+        if key_operations:
+            output.append("")
+            output.append("Key operations:")
+            for item in key_operations[:3]:
+                output.append(f"- {item}")
+
+        if next_hint or len(hint_ladder) >= 2:
             output.append("")
             output.append("Next hint:")
-            output.append(f"- {hint_ladder[1]}")
+            output.append(f"- {next_hint or hint_ladder[1]}")
+
+        if common_traps and verbosity >= 0.7:
+            output.append("")
+            output.append("Watch out for:")
+            for item in common_traps[:3]:
+                output.append(f"- {item}")
+
         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}")
+    # STAGE 1 = short hint only
+    if stage == 1:
+        if ask:
+            output.append("What to identify first:")
+            output.append(f"- {ask}")
 
-    if next_hint:
-        output.append("")
-        output.append("Next hint:")
-        output.append(f"- {next_hint}")
+        if first_move or hint_ladder:
+            output.append("")
+            output.append("First move:")
+            output.append(f"- {first_move or hint_ladder[0]}")
+
+        if next_hint or len(hint_ladder) >= 2:
+            output.append("")
+            output.append("Next hint:")
+            output.append(f"- {next_hint or hint_ladder[1]}")
 
+        return output
+
+    # STAGE 2 = deeper structure only
     if stage == 2:
+        if setup_actions:
+            output.append("Set-up path:")
+            for item in _limit_steps(setup_actions, verbosity, minimum=2):
+                output.append(f"- {item}")
+
+        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 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}")
-        if key_operations:
-            output.append("")
-            output.append("Key operations:")
-            for item in key_operations[:3]:
-                output.append(f"- {item}")
+
         return output
 
+    # STAGE 3+ = fuller help, still no answer reveal
+    if setup_actions:
+        output.append("Set-up path:")
+        for item in _limit_steps(setup_actions, verbosity, minimum=2):
+            output.append(f"- {item}")
+
+    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 variables_to_define:
         output.append("")
         output.append("Variables to define:")
@@ -337,63 +157,15 @@ def _staged_scaffold_lines(
         for item in key_operations[:3]:
             output.append(f"- {item}")
 
-    if common_traps:
+    if next_hint or len(hint_ladder) >= 2:
         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."
-
-    output: List[str] = []
-    prefix = style_prefix(tone)
-    if prefix:
-        output.append(prefix)
-        output.append("")
-
-    output.append("Question breakdown:")
-    output.append("")
-
-    summary = _coerce_string(getattr(result, "summary", ""))
-    if summary:
-        output.append(summary)
-
-    scaffold_lines = _staged_scaffold_lines(
-        result=result,
-        hint_stage=hint_stage,
-        verbosity=verbosity,
-        transparency=transparency,
-    )
-    if scaffold_lines:
-        if summary:
-            output.append("")
-        output.extend(scaffold_lines)
+        output.append("Next hint:")
+        output.append(f"- {next_hint or hint_ladder[1]}")
 
-    teaching_points = _coerce_list(getattr(result, "teaching_points", []))
-    if teaching_points and (verbosity >= 0.55 or hint_stage >= 2):
+    if common_traps and verbosity >= 0.65:
         output.append("")
-        output.append("Key teaching points:")
-        for item in _limit_steps(teaching_points, verbosity, minimum=2):
+        output.append("Watch out for:")
+        for item in common_traps[:3]:
             output.append(f"- {item}")
 
-    topic = _extract_topic_from_text(
-        f"{summary} {' '.join(teaching_points)}",
-        getattr(result, "topic", None),
-    )
-
-    if transparency >= 0.8:
-        output.append("")
-        output.append(_why_line(topic))
-
-    return "\n".join(_dedupe_lines(output)).strip()
+    return output