Update conversation_logic.py

conversation_logic.py

@@ -71,6 +71,7 @@ FOLLOWUP_ONLY_INPUTS = {
     "help",
 }
 
+
 def _clean_text(text: Optional[str]) -> str:
     return (text or "").strip()
 
@@ -255,7 +256,7 @@ def _build_topic_query_reply(question_text: str, fallback_topic: str, classified
     if specific == "algebra":
         return (
             "- This is an algebra question.\n"
-            "- The key skill is rewriting the relationship cleanly, then simplifying the expression the question actually asks for."
+            "- The key skill is undoing the operations around the variable in a logical order."
         )
     if specific == "ratio":
         return (
@@ -270,7 +271,7 @@ def _build_topic_query_reply(question_text: str, fallback_topic: str, classified
     if specific == "probability":
         return (
             "- This is a probability question.\n"
-            "- The key skill is deciding what counts as a successful outcome and then comparing favorable outcomes with the total possible outcomes."
+            "- The key skill is deciding what counts as a successful outcome and then comparing favorable outcomes with total outcomes."
         )
 
     label = specific if specific != "general" else (cat.lower() if cat else "quantitative reasoning")
@@ -283,6 +284,19 @@ def _classify_input_type(raw_user_text: str) -> str:
         return "empty"
     if _is_topic_query(raw_user_text):
         return "topic_query"
+
+    if any(
+        p in text
+        for p in [
+            "what do i do first",
+            "what should i do first",
+            "first step",
+            "where do i start",
+            "how should i start",
+        ]
+    ):
+        return "hint"
+
     if text in {"hint", "a hint", "give me a hint", "can i have a hint"} or text.startswith("hint:"):
         return "hint"
     if text in {"next hint", "another hint", "more hint", "more hints", "next step", "continue", "go on"} or text.startswith("next hint:"):
@@ -299,6 +313,8 @@ def _classify_input_type(raw_user_text: str) -> str:
             "help me understand",
             "method",
             "explain",
+            "how do i solve",
+            "how do i do this",
         ]
     ):
         return "confusion"
@@ -392,7 +408,7 @@ def _compute_hint_stage(input_type: str, prior_hint_stage: int, fallback_history
     if input_type == "next_hint":
         return min((base if base > 0 else 1) + 1, 3)
     if input_type == "confusion":
-        return 3
+        return 1
     return min(base, 3)
 
 
@@ -580,6 +596,15 @@ def _parse_numeric_option_set(option: str) -> Optional[List[float]]:
     return parts if len(parts) >= 2 else None
 
 
+def _looks_like_simple_linear_equation(question_text: str) -> bool:
+    q = _clean_text(question_text).lower()
+    return bool(
+        "=" in q
+        and re.search(r"\bwhat is\s+[a-z]\b", q)
+        and re.search(r"\b\d+[a-z]\b|\b[a-z]\b", q)
+    )
+
+
 def _question_specific_ratio_reply(question_text: str) -> str:
     q = _clean_text(question_text)
     low = q.lower()
@@ -611,12 +636,21 @@ def _question_specific_variability_reply(options_text: Optional[List[str]]) -> s
     )
 
 
-def _question_specific_percent_reply(question_text: str) -> str:
+def _question_specific_percent_reply(question_text: str, user_text: str = "") -> str:
     clean = _clean_text(question_text)
     low = clean.lower()
+    user_low = _clean_text(user_text).lower()
     nums = re.findall(r"-?\d+(?:\.\d+)?", clean)
 
+    wants_first = any(p in user_low for p in ["what should i do first", "what do i do first", "first step", "where do i start", "how should i start"])
+    wants_method = any(p in user_low for p in ["how do i solve", "how do i do this", "method", "walkthrough", "step by step", "explain"])
+
     if "increased by" in low and "decreased by" in low:
+        if wants_first:
+            return (
+                "- First turn each percent change into a multiplier instead of combining the percentages directly.\n"
+                "- Apply the increase multiplier to the original amount, then apply the decrease multiplier to the updated amount."
+            )
         return (
             "- For back-to-back percent changes, turn the changes into multipliers instead of trying to combine the percentages directly.\n"
             "- Apply the increase multiplier first, then the decrease multiplier to that new amount.\n"
@@ -625,6 +659,17 @@ def _question_specific_percent_reply(question_text: str) -> str:
 
     if "out of" in low and len(nums) >= 2:
         part, whole = nums[0], nums[1]
+        if wants_first:
+            return (
+                f"- First write the relationship as the fraction {part}/{whole}.\n"
+                f"- Use {whole} as the total and {part} as the part before doing any percent conversion."
+            )
+        if wants_method:
+            return (
+                f"- This is a part-over-whole percent question, so start by writing {part}/{whole}.\n"
+                f"- Use {whole} as the base because it is the total, and {part} as the part that matches the condition.\n"
+                "- Then convert that fraction to a percent by simplifying or turning it into a decimal and multiplying by 100."
+            )
         return (
             f"- This is a part-over-whole percent question: start by writing the fraction as {part}/{whole}.\n"
             f"- Use {whole} as the base because it is the total, and {part} as the part that chose the option.\n"
@@ -632,6 +677,11 @@ def _question_specific_percent_reply(question_text: str) -> str:
         )
 
     if any(k in low for k in ["of", "what percent", "%"]):
+        if wants_first:
+            return (
+                "- First ask 'percent of what?' so you identify the correct base quantity.\n"
+                "- Then put the part over the whole before converting anything to a percent."
+            )
         return (
             "- Ask 'percent of what?' first so you identify the correct base quantity.\n"
             "- Put the part over the whole before doing any percent conversion.\n"
@@ -644,12 +694,34 @@ def _question_specific_percent_reply(question_text: str) -> str:
     )
 
 
-
-def _question_specific_probability_reply(question_text: str, options_text: Optional[List[str]] = None) -> str:
+def _question_specific_probability_reply(question_text: str, user_text: str = "", options_text: Optional[List[str]] = None) -> str:
     q = _clean_text(question_text)
     low = q.lower()
+    user_low = _clean_text(user_text).lower()
     option_count = len(options_text or [])
 
+    wants_first = any(
+        phrase in user_low
+        for phrase in [
+            "what should i do first",
+            "what do i do first",
+            "first step",
+            "where do i start",
+            "how should i start",
+        ]
+    )
+    wants_method = any(
+        phrase in user_low
+        for phrase in [
+            "how do i solve",
+            "how do i do this",
+            "method",
+            "walkthrough",
+            "step by step",
+            "explain",
+        ]
+    )
+
     single_draw_markers = [
         "chosen at random",
         "select one",
@@ -660,6 +732,8 @@ def _question_specific_probability_reply(question_text: str, options_text: Optio
         "one object",
         "selected at random",
         "picked at random",
+        "one ball is chosen",
+        "one card is drawn",
     ]
     container_markers = [
         "box contains",
@@ -673,9 +747,21 @@ def _question_specific_probability_reply(question_text: str, options_text: Optio
         "coin",
     ]
 
-    if any(m in low for m in single_draw_markers) or (
-        "probability" in low and any(m in low for m in container_markers)
-    ):
+    if any(m in low for m in single_draw_markers) or ("probability" in low and any(m in low for m in container_markers)):
+        if wants_first:
+            return (
+                "- First decide what counts as a successful outcome.\n"
+                "- Then count the total number of possible outcomes in the box, bag, or sample space."
+            )
+        if wants_method:
+            lines = [
+                "- For a one-draw probability question, use favorable outcomes over total outcomes.",
+                "- Count how many outcomes match the condition, then count the total number of possible outcomes.",
+                "- Build the fraction favorable/total before matching it to an answer choice.",
+            ]
+            if option_count:
+                lines.append("- Once the fraction is set up, compare it directly with the options.")
+            return "\n".join(lines)
         lines = [
             "- Start by deciding what counts as a successful outcome in this question.",
             "- Then count the total number of possible outcomes in the container or sample space.",
@@ -686,6 +772,11 @@ def _question_specific_probability_reply(question_text: str, options_text: Optio
         return "\n".join(lines)
 
     if "at least" in low:
+        if wants_first:
+            return (
+                "- First check whether the complement is easier than counting the requested cases directly.\n"
+                "- For 'at least' problems, the opposite event is often simpler to compute first."
+            )
         return (
             "- Start by deciding whether the complement is easier than counting the requested cases directly.\n"
             "- For an 'at least' question, it is often simpler to find the probability of the opposite event first.\n"
@@ -693,17 +784,133 @@ def _question_specific_probability_reply(question_text: str, options_text: Optio
         )
 
     if any(k in low for k in ["and", "both", "then", "after"]) and any(k in low for k in ["probability", "chosen", "random"]):
+        if wants_first:
+            return (
+                "- First decide whether the events happen together or separately.\n"
+                "- Then work out whether you need multiplication, addition, or the complement rule."
+            )
         return (
             "- First identify whether the events happen together or separately.\n"
             "- Then decide whether you should multiply probabilities, add them, or use the complement.\n"
             "- Keep track of whether the total outcomes change after each step."
         )
 
+    if wants_first:
+        return (
+            "- First identify the favorable outcomes.\n"
+            "- Then identify the total possible outcomes before simplifying anything."
+        )
+
     return (
         "- Start by identifying the favorable outcomes and the total possible outcomes.\n"
         "- Then build the probability as favorable over total before simplifying or matching an answer choice."
     )
 
+
+def _question_specific_algebra_reply(question_text: str, user_text: str = "") -> str:
+    q = _clean_text(question_text)
+    low = q.lower()
+    user_low = _clean_text(user_text).lower()
+
+    wants_first = any(
+        phrase in user_low
+        for phrase in [
+            "what should i do first",
+            "what do i do first",
+            "first step",
+            "where do i start",
+            "how should i start",
+        ]
+    )
+
+    if _looks_like_simple_linear_equation(q):
+        if wants_first:
+            return (
+                "- First look at the variable side and ask which operation is furthest away from the variable.\n"
+                "- Undo that outside addition or subtraction on both sides before touching the coefficient."
+            )
+        return (
+            "- Treat this as a linear equation and undo the operations around the variable in reverse order.\n"
+            "- First remove the constant attached to the variable side by doing the opposite operation on both sides.\n"
+            "- Then undo the multiplication or division on the variable to isolate it."
+        )
+
+    if re.search(r"\b[a-z]\s*/\s*[a-z]\s*=\s*\d+\s*/\s*\d+", low):
+        return _question_specific_ratio_reply(q)
+
+    if "what is" in low and "(" in low and ")" in low and any(sym in low for sym in ["a+b", "x+y", "a-b", "x-y"]):
+        return (
+            "- Start by rewriting one variable in terms of the other using the relationship you were given.\n"
+            "- Then substitute into the exact expression in parentheses, rather than trying to solve for actual numbers.\n"
+            "- Simplify only after the whole target expression has been rewritten in one variable or in matching parts."
+        )
+
+    if wants_first:
+        return (
+            "- First turn the wording into one clean equation.\n"
+            "- Then decide which operation around the variable should be undone first."
+        )
+
+    return (
+        "- Turn the wording into one clean equation first.\n"
+        "- Then undo the operations around the variable in reverse order until the variable stands alone."
+    )
+
+
+def _question_specific_hint_ladder(
+    *,
+    question_text: str,
+    options_text: Optional[List[str]],
+    classified_topic: str,
+) -> List[str]:
+    q = _clean_text(question_text)
+    low = q.lower()
+    topic = (classified_topic or "general").lower()
+
+    if _looks_like_simple_linear_equation(q) or topic == "algebra":
+        return [
+            "Look at the variable side and ask which operation is furthest away from the variable.",
+            "Undo the addition or subtraction first by doing the opposite on both sides.",
+            "Once the variable term is alone, undo the multiplication or division on the variable.",
+        ]
+
+    if topic == "probability" or any(k in low for k in ["probability", "chance", "odds", "at random", "chosen at random"]):
+        return [
+            "What counts as a successful outcome here?",
+            "How many total possible outcomes are there?",
+            "Set up the probability as favorable over total before comparing answer choices.",
+        ]
+
+    if topic == "percent" or "%" in low or "percent" in low:
+        if "out of" in low:
+            return [
+                "Which number is the part and which number is the total?",
+                "Write the relationship as part over whole before converting anything.",
+                "Once the fraction is correct, convert it to a percent.",
+            ]
+        return [
+            "Ask 'percent of what?' first.",
+            "Put the part over the base quantity.",
+            "Only multiply by 100 after the fraction or equation is set up correctly.",
+        ]
+
+    if any(k in low for k in ["variability", "spread", "standard deviation"]):
+        return [
+            "This is about spread, not average.",
+            "Compare how far the outer values sit from the middle value in each set.",
+            "The set with the widest spread has the greatest variability.",
+        ]
+
+    if re.search(r"\b[a-z]\s*/\s*[a-z]\s*=\s*\d+\s*/\s*\d+", low):
+        return [
+            "Rewrite the ratio using matching parts such as 3k and 4k.",
+            "Substitute those matching parts into the expression the question asks for.",
+            "Simplify after substitution by cancelling the common factor.",
+        ]
+
+    return []
+
+
 def _build_question_specific_reply(
     *,
     question_text: str,
@@ -743,20 +950,13 @@ def _build_question_specific_reply(
     if topic == "probability" or any(
         k in low for k in ["probability", "chance", "odds", "at random", "chosen at random"]
     ):
-        return _question_specific_probability_reply(q, options_text)
+        return _question_specific_probability_reply(q, user_low, options_text)
 
     if topic in {"ratio", "algebra"}:
-        if re.search(r"\b[a-z]\s*/\s*[a-z]\s*=\s*\d+\s*/\s*\d+", low):
-            return _question_specific_ratio_reply(q)
-        if "what is" in low and "(" in low and ")" in low and any(sym in low for sym in ["a+b", "x+y", "a-b", "x-y"]):
-            return (
-                "- Start by rewriting one variable in terms of the other using the relationship you were given.\n"
-                "- Then substitute into the exact expression in parentheses, rather than trying to solve for actual numbers.\n"
-                "- Simplify only after the whole target expression has been rewritten in one variable or in matching parts."
-            )
+        return _question_specific_algebra_reply(q, user_low)
 
     if topic == "percent" or "%" in low or "percent" in low:
-        return _question_specific_percent_reply(q)
+        return _question_specific_percent_reply(q, user_low)
 
     if topic == "statistics" and any(k in low for k in ["dataset", "table", "chart", "graph"]):
         return (
@@ -764,17 +964,7 @@ def _build_question_specific_reply(
             "- Use the structure of the choices to compare them efficiently instead of computing unnecessary extra values."
         )
 
-    if topic == "algebra":
-        return (
-            "- Turn the wording into one clean relationship first.\n"
-            "- Then focus on the exact expression the question asks for, rather than solving more than you need to."
-        )
-
     if explicit_help_ask:
-        if topic == "percent":
-            return _question_specific_percent_reply(q)
-        if topic == "probability":
-            return _question_specific_probability_reply(q, options_text)
         return "- Start by identifying the main relationship in the question, then use that relationship to set up the first step."
 
     return ""
@@ -905,7 +1095,7 @@ class ConversationEngine:
         if input_type in {"hint", "next_hint"}:
             resolved_intent = "hint"
         elif input_type == "confusion":
-            resolved_intent = "walkthrough"
+            resolved_intent = "method"
         elif input_type in {"solve", "question"} and resolved_intent in {"hint", "walkthrough", "step_by_step"}:
             resolved_intent = "answer"
 
@@ -913,7 +1103,7 @@ class ConversationEngine:
         if input_type in {"hint", "next_hint"}:
             resolved_help_mode = "hint"
         elif input_type == "confusion":
-            resolved_help_mode = "walkthrough"
+            resolved_help_mode = "explain"
         elif resolved_help_mode == "step_by_step":
             resolved_help_mode = "walkthrough"
 
@@ -979,25 +1169,24 @@ class ConversationEngine:
             user_text=user_text,
         )
 
-        # Merge solver result into base result only if it agrees with the classified topic.
         if solver_result is not None:
             result.meta = result.meta or {}
             solver_topic = getattr(solver_result, "topic", None) or "unknown"
-            
+
             compatible_topics = {
                 question_topic,
                 "general_quant",
                 "general",
                 "unknown",
             }
-            # allow a few sensible cross-matches
+
             if question_topic == "algebra":
                 compatible_topics.update({"ratio"})
             elif question_topic == "ratio":
                 compatible_topics.update({"algebra"})
             elif question_topic == "percent":
                 compatible_topics.update({"ratio", "algebra"})
-            
+
             if solver_topic in compatible_topics:
                 result = solver_result
                 result.domain = "quant"
@@ -1096,16 +1285,78 @@ class ConversationEngine:
                         "- Compare how far the smallest and largest values sit from the middle value in each dataset.\n"
                         "- The set with the widest spread has the greatest variability."
                     )
-        # Source selection priority:
-        # 1) topic query (returned earlier)
-        # 2) question-specific guidance for help-first asks when available
-        # 3) question-support / explainer fallback
-        # 4) solver steps for direct solve / walkthrough
-        # 5) generic fallback
-        if question_specific_reply_core and (
-            _is_help_first_mode(resolved_help_mode)
-            or input_type in {"other", "confusion", "hint", "next_hint"}
-            or any(phrase in _clean_text(user_text).lower() for phrase in ["how do i solve", "what do i do first", "what should i do first", "how should i start"])
+
+        if input_type in {"hint", "next_hint"}:
+            hint_lines: List[str] = []
+
+            custom_ladder = _question_specific_hint_ladder(
+                question_text=solver_input,
+                options_text=options_text,
+                classified_topic=question_topic,
+            )
+            if custom_ladder:
+                idx = min(max(hint_stage - 1, 0), len(custom_ladder) - 1)
+                hint_lines = [custom_ladder[idx]]
+
+            if not hint_lines and explainer_scaffold:
+                ladder = _safe_meta_list(explainer_scaffold.get("hint_ladder", []))
+                first_move = _safe_meta_text(explainer_scaffold.get("first_move"))
+                next_hint_text = _safe_meta_text(explainer_scaffold.get("next_hint"))
+
+                if hint_stage <= 1 and first_move:
+                    hint_lines = [first_move]
+                elif ladder:
+                    idx = min(max(hint_stage - 1, 0), len(ladder) - 1)
+                    hint_lines = [ladder[idx]]
+                elif next_hint_text:
+                    hint_lines = [next_hint_text]
+
+            if not hint_lines and fallback_pack:
+                fallback_hints = _safe_meta_list(fallback_pack.get("hint_ladder", []))
+                if fallback_hints:
+                    idx = min(max(hint_stage - 1, 0), len(fallback_hints) - 1)
+                    hint_lines = [fallback_hints[idx]]
+
+            if not hint_lines and fallback_reply_core:
+                split_lines = [line.strip("- ").strip() for line in fallback_reply_core.splitlines() if line.strip()]
+                if split_lines:
+                    idx = min(max(hint_stage - 1, 0), len(split_lines) - 1)
+                    hint_lines = [split_lines[idx]]
+
+            if not hint_lines:
+                hint_lines = [_minimal_generic_reply(inferred_category)]
+
+            reply_core = "\n".join(f"- {line}" for line in hint_lines if str(line).strip())
+            result.meta["response_source"] = "hint_ladder"
+            result.meta["question_support_used"] = bool(fallback_pack)
+            result.meta["question_support_source"] = fallback_pack.get("support_source") if fallback_pack else None
+            result.meta["question_support_topic"] = fallback_pack.get("topic") if fallback_pack else None
+
+            reply = format_reply(
+                reply_core,
+                tone=tone,
+                verbosity=verbosity,
+                transparency=transparency,
+                help_mode="hint",
+                hint_stage=hint_stage,
+                topic=result.topic,
+            )
+
+        elif question_specific_reply_core and (
+            input_type not in {"hint", "next_hint"}
+            and (
+                _is_help_first_mode(resolved_help_mode)
+                or input_type in {"other", "confusion"}
+                or any(
+                    phrase in _clean_text(user_text).lower()
+                    for phrase in [
+                        "how do i solve",
+                        "what do i do first",
+                        "what should i do first",
+                        "how should i start",
+                    ]
+                )
+            )
         ):
             reply_core = question_specific_reply_core
             result.meta["response_source"] = "question_specific"
@@ -1166,7 +1417,7 @@ class ConversationEngine:
         elif (
             resolved_help_mode == "answer"
             and solver_has_steps
-            and result.meta.get("solver_topic_rejected") is None
+            and solver_topic_ok
             and direct_solve_request
         ):
             reply_core = _answer_path_from_steps(solver_steps, verbosity=verbosity)
@@ -1185,7 +1436,7 @@ class ConversationEngine:
             resolved_help_mode == "walkthrough"
             and solver_has_steps
             and not prefer_question_support
-            and result.meta.get("solver_topic_rejected") is None
+            and solver_topic_ok
         ):
             reply_core = _answer_path_from_steps(solver_steps, verbosity=verbosity)
             result.meta["response_source"] = "solver_steps"
@@ -1229,14 +1480,14 @@ class ConversationEngine:
                 hint_stage=hint_stage,
                 topic=result.topic,
             )
-        # Never reveal final answers during tutoring/help modes.
+
         if resolved_help_mode in {"hint", "walkthrough", "explain", "instruction", "step_by_step"}:
             result.solved = False
             result.answer_letter = None
             result.answer_value = None
             result.internal_answer = None
             result.meta["internal_answer"] = None
-        # Only allow answer metadata to survive for true direct solve requests.
+
         can_reveal_answer = bool(result.solved and direct_solve_request and not _is_help_first_mode(resolved_help_mode))
         result.meta["can_reveal_answer"] = can_reveal_answer
         if not can_reveal_answer:
@@ -1257,6 +1508,7 @@ class ConversationEngine:
             topic=result.topic,
             category=inferred_category,
         )
+
         result.reply = reply
         result.help_mode = resolved_help_mode
         result.meta["help_mode"] = resolved_help_mode