Update formatting.py

formatting.py

@@ -1,3 +1,228 @@
+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,
@@ -23,7 +248,6 @@ def _staged_scaffold_lines(
     hint_ladder = _coerce_list(getattr(scaffold, "hint_ladder", []))
     key_operations = _coerce_list(getattr(scaffold, "key_operations", []))
 
-    # STAGE 0 = full scaffold / walkthrough
     if stage == 0:
         if concept and transparency >= 0.75:
             output.append("Core idea:")
@@ -82,7 +306,6 @@ def _staged_scaffold_lines(
 
         return output
 
-    # STAGE 1 = short hint only
     if stage == 1:
         if ask:
             output.append("What to identify first:")
@@ -100,7 +323,6 @@ def _staged_scaffold_lines(
 
         return output
 
-    # STAGE 2 = deeper structure only
     if stage == 2:
         if setup_actions:
             output.append("Set-up path:")
@@ -127,7 +349,6 @@ def _staged_scaffold_lines(
 
         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):
@@ -168,4 +389,67 @@ def _staged_scaffold_lines(
         for item in common_traps[:3]:
             output.append(f"- {item}")
 
-    return output
+    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)
+
+    stage = max(0, int(getattr(result, "hint_stage", hint_stage) or 0))
+
+    summary = _coerce_string(getattr(result, "summary", ""))
+    teaching_points = _coerce_list(getattr(result, "teaching_points", []))
+
+    if stage == 0 and summary:
+        if output:
+            output.append("")
+        output.append(summary)
+
+    scaffold_lines = _staged_scaffold_lines(
+        result=result,
+        hint_stage=stage,
+        verbosity=verbosity,
+        transparency=transparency,
+    )
+    if scaffold_lines:
+        if output:
+            output.append("")
+        output.extend(scaffold_lines)
+
+    if teaching_points and (stage == 0 or stage >= 3) and verbosity >= 0.55:
+        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 transparency >= 0.8 and stage not in {1, 2}:
+        output.append("")
+        output.append(_why_line(topic))
+
+    cleaned: List[str] = []
+    previous_blank = False
+    for line in output:
+        is_blank = not line.strip()
+        if is_blank and previous_blank:
+            continue
+        cleaned.append(line)
+        previous_blank = is_blank
+
+    return "\n".join(cleaned).strip()