j-js commited on
Commit
40b145a
·
verified ·
1 Parent(s): 088b8eb

Update question_fallback_router.py

Browse files
Files changed (1) hide show
  1. question_fallback_router.py +229 -268
question_fallback_router.py CHANGED
@@ -37,8 +37,10 @@ class QuestionFallbackRouter:
37
  q = (question_text or "").lower()
38
  t = (topic or "").strip().lower()
39
 
40
- if t and t not in {"general", "unknown", "general_quant"}:
41
  return t
 
 
42
  if "%" in q or "percent" in q:
43
  return "percent"
44
  if "ratio" in q or re.search(r"\b\d+\s*:\s*\d+\b", q):
@@ -49,7 +51,7 @@ class QuestionFallbackRouter:
49
  return "number_theory"
50
  if any(k in q for k in ["triangle", "circle", "angle", "area", "perimeter", "rectangle", "circumference"]):
51
  return "geometry"
52
- if any(k in q for k in ["mean", "median", "average", "standard deviation", "variability"]):
53
  return "statistics"
54
  if "=" in q or re.search(r"\b[xyzabn]\b", q):
55
  return "algebra"
@@ -79,6 +81,43 @@ class QuestionFallbackRouter:
79
  def _extract_percent_values(self, question_text: str) -> List[str]:
80
  return re.findall(r"\d+\.?\d*\s*%", question_text or "")
81
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
82
  def _topic_defaults(self, topic: str, question_text: str, options_text: Optional[List[str]]) -> Dict[str, Any]:
83
  preview = self._preview_question(question_text)
84
  equation = self._extract_equation(question_text)
@@ -113,231 +152,205 @@ class QuestionFallbackRouter:
113
  }
114
 
115
  if topic == "algebra":
116
- first_step = (
117
- f"Start with the equation: {equation}"
118
- if equation
119
- else "Write the equation exactly as given and identify the operation attached to the variable."
120
- )
121
- hint_1 = "Focus on isolating the variable."
122
- hint_2 = "Undo addition or subtraction before undoing multiplication or division."
123
- hint_3 = "Do the same operation to both sides each time so the equation stays balanced."
124
-
125
- generic.update(
126
- {
127
- "first_step": first_step,
128
- "hint_1": hint_1,
129
- "hint_2": hint_2,
130
- "hint_3": hint_3,
131
- "hint_ladder": [hint_1, hint_2, hint_3],
132
- "walkthrough_steps": [
133
- first_step,
134
- "Use inverse operations to undo what is attached to the variable.",
135
- "Do the same thing to both sides each time.",
136
- "Once the variable is isolated, compare with the answer choices if there are any.",
137
- ],
138
- "method_steps": [
139
- "Algebra questions are about preserving balance while isolating the unknown.",
140
- "Treat each operation in reverse order to peel the equation back.",
141
- ],
142
- "answer_path": [
143
- first_step,
144
- "Reverse the operations in a sensible order.",
145
- "Simplify only after keeping both sides balanced.",
146
- ],
147
- "common_trap": "Changing only one side of the equation or reversing the order of operations badly.",
148
- }
149
- )
 
 
 
 
 
150
 
151
  elif topic == "percent":
152
  first_step = "Identify the base quantity before doing any percent calculation."
153
  if percent_values:
154
  first_step = f"Track the percentage relationship carefully here: {' then '.join(percent_values[:2]) if len(percent_values) > 1 else percent_values[0]}"
155
-
156
- hint_1 = "Decide what quantity the percent is of."
157
- hint_2 = "Rewrite the percent as a decimal or fraction if that makes the relationship clearer."
158
- hint_3 = "Set up part = percent × base, or reverse that relationship if the base is unknown."
159
-
160
- generic.update(
161
- {
162
- "first_step": first_step,
163
- "hint_1": hint_1,
164
- "hint_2": hint_2,
165
- "hint_3": hint_3,
166
- "hint_ladder": [hint_1, hint_2, hint_3],
167
- "walkthrough_steps": [
168
- first_step,
169
- "Find the base quantity the percent refers to.",
170
- "Translate the wording into a percent relationship.",
171
- "Solve for the missing quantity.",
172
- "Check whether the question asks for the part, the whole, or a percent change.",
173
- ],
174
- "method_steps": [
175
- "Percent questions become easier once you identify the correct base.",
176
- "Do not apply the percent to the wrong quantity.",
177
- ],
178
- "answer_path": [
179
- first_step,
180
- "Turn the wording into a percent equation.",
181
- "Then solve for the missing part of the relationship.",
182
- ],
183
- "common_trap": "Using the wrong base quantity.",
184
- }
185
- )
186
 
187
  elif topic == "ratio":
188
  first_step = "Keep the ratio order consistent and assign one shared multiplier."
189
  if ratio_text:
190
  first_step = f"Use the ratio {ratio_text} as parts of one whole."
191
-
192
- hint_1 = "Write each part of the ratio using the same multiplier."
193
- hint_2 = "Use the total or known part to solve for that shared multiplier."
194
- hint_3 = "Substitute back into the specific part you actually need."
195
-
196
  generic.update(
197
  {
198
  "first_step": first_step,
199
- "hint_1": hint_1,
200
- "hint_2": hint_2,
201
- "hint_3": hint_3,
202
- "hint_ladder": [hint_1, hint_2, hint_3],
 
 
 
 
203
  "walkthrough_steps": [
204
  first_step,
205
- "Translate the ratio into algebraic parts with one common scale factor.",
206
- "Use the total or given piece to solve for the factor.",
207
- "Find the required part and check the order of the ratio.",
208
  ],
209
  "method_steps": [
210
- "Ratio questions are controlled by one shared multiplier.",
211
- "Preserve the ratio order all the way through.",
212
- ],
213
- "answer_path": [
214
- first_step,
215
- "Convert the ratio into parts of a total.",
216
- "Solve for the shared scale factor before finding the requested part.",
217
  ],
218
- "common_trap": "Reversing the ratio order or using different multipliers for different parts.",
219
  }
220
  )
221
 
222
  elif topic == "probability":
223
- hint_1 = "Decide exactly what counts as a successful outcome."
224
- hint_2 = "Count all possible outcomes under the same rules."
225
- hint_3 = "Write probability as successful over total, then simplify if needed."
226
-
227
  generic.update(
228
  {
229
- "first_step": "Count successful outcomes and total outcomes separately.",
230
- "hint_1": hint_1,
231
- "hint_2": hint_2,
232
- "hint_3": hint_3,
233
- "hint_ladder": [hint_1, hint_2, hint_3],
 
 
 
 
234
  "walkthrough_steps": [
235
- "Identify the event the question cares about.",
236
- "Count the successful outcomes.",
237
- "Count the full sample space.",
238
- "Form the probability and simplify carefully.",
239
  ],
240
  "method_steps": [
241
- "Probability is a comparison of favorable outcomes to all valid outcomes.",
242
- "Make sure the numerator and denominator come from the same setup.",
243
- ],
244
- "answer_path": [
245
- "Define the event clearly.",
246
- "Count favorable outcomes and total outcomes from the same sample space.",
247
- "Then simplify the fraction if possible.",
248
- ],
249
- "common_trap": "Counting the right numerator with the wrong denominator.",
250
- }
251
- )
252
-
253
- elif topic == "number_theory":
254
- generic.update(
255
- {
256
- "first_step": "Identify which number property matters most: factors, multiples, divisibility, or remainders.",
257
- "hint_1": "Look for the number property the question is testing.",
258
- "hint_2": "Use that rule directly instead of trying random arithmetic.",
259
- "hint_3": "Check the candidate values against the exact condition in the question.",
260
- "hint_ladder": [
261
- "Look for the number property the question is testing.",
262
- "Use that rule directly instead of trying random arithmetic.",
263
- "Check the candidate values against the exact condition in the question.",
264
- ],
265
- "common_trap": "Using arithmetic intuition instead of the actual number-property rule being tested.",
266
- }
267
- )
268
-
269
- elif topic == "geometry":
270
- generic.update(
271
- {
272
- "first_step": "Identify the shape and the formula or relationship that belongs to it.",
273
- "hint_1": "Work out which measurement is given and which one you need.",
274
- "hint_2": "Choose the correct geometry formula before substituting numbers.",
275
- "hint_3": "Substitute carefully and keep track of what the question asks for.",
276
- "hint_ladder": [
277
- "Work out which measurement is given and which one you need.",
278
- "Choose the correct geometry formula before substituting numbers.",
279
- "Substitute carefully and keep track of what the question asks for.",
280
  ],
281
- "common_trap": "Using the wrong formula or solving for the wrong geometric quantity.",
282
  }
283
  )
 
 
 
 
 
 
 
284
 
285
  elif topic == "statistics":
286
- qlow = (question_text or "").lower()
287
-
288
  if any(k in qlow for k in ["variability", "spread", "standard deviation"]):
289
  generic.update(
290
  {
291
- "first_step": "This is about spread, so compare how far the values sit from the center.",
292
- "hint_1": "Check which dataset has values furthest from its middle value.",
293
- "hint_2": "Since each set has three numbers, compare how spread out the smallest and largest values are.",
294
- "hint_3": "The set with the biggest overall spread has the greatest variability here.",
295
  "hint_ladder": [
296
- "Check which dataset has values furthest from its middle value.",
297
- "Compare the distance from the middle to the outer numbers in each set.",
298
- "The set with the largest spread has the greatest variability.",
299
- ],
300
- "walkthrough_steps": [
301
- "Notice that the question is about variability, not the average.",
302
- "For each dataset, identify the middle value.",
303
- "Compare how far the outer values sit from that middle value.",
304
- "The dataset with the widest spread is the most variable.",
305
- ],
306
- "method_steps": [
307
- "For short answer choices like these, you can often compare spread visually instead of computing a full standard deviation.",
308
- "Look at how tightly clustered or widely spaced the numbers are.",
309
- ],
310
- "answer_path": [
311
- "Identify that the question is testing spread rather than center.",
312
- "Compare how far the values extend away from the middle in each dataset.",
313
- "Choose the dataset with the widest spread.",
314
  ],
315
- "common_trap": "Comparing means instead of comparing spread.",
316
  }
317
  )
318
  else:
319
  generic.update(
320
  {
321
- "first_step": "Identify which measure the question wants before calculating anything.",
322
- "hint_1": "Check whether this is asking for mean, median, range, or another measure.",
323
- "hint_2": "Set up the data in a clean order if needed.",
324
- "hint_3": "Use the correct formula or definition for that exact measure.",
325
- "hint_ladder": [
326
- "Check whether this is asking for mean, median, range, or another measure.",
327
- "Set up the data in a clean order if needed.",
328
- "Use the correct formula or definition for that exact measure.",
329
- ],
330
- "common_trap": "Using the wrong statistical measure because the wording was skimmed too quickly.",
331
  }
332
  )
333
 
334
  if has_options:
335
  generic["answer_path"] = list(generic.get("answer_path", [])) + [
336
- "Use the choices to check which one matches your setup instead of guessing."
337
  ]
338
 
339
  return generic
340
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
341
  def get_support_pack(
342
  self,
343
  *,
@@ -347,43 +360,35 @@ class QuestionFallbackRouter:
347
  topic: Optional[str],
348
  category: Optional[str],
349
  ) -> Dict[str, Any]:
350
- stored = question_support_bank.get(question_id=question_id, question_text=question_text)
351
  resolved_topic = self._normalize_topic(topic, question_text)
352
-
353
- if stored:
354
- pack = dict(stored)
355
- pack.setdefault("question_id", question_id)
356
- pack.setdefault("question_text", question_text)
357
- pack.setdefault("options_text", list(options_text or []))
358
- pack.setdefault("topic", resolved_topic)
359
- pack.setdefault("category", category or "General")
360
- pack.setdefault("support_source", "question_bank")
361
- return pack
362
-
363
  generated = self._topic_defaults(resolved_topic, question_text, options_text)
364
- generated.update(
365
- {
366
- "question_id": question_id,
367
- "question_text": question_text,
368
- "options_text": list(options_text or []),
369
- "topic": resolved_topic,
370
- "category": category or "General",
371
- "support_source": "generated_question_specific",
372
- }
373
  )
374
- return generated
 
 
 
 
 
 
 
 
 
375
 
376
  def _hint_ladder_from_pack(self, pack: Dict[str, Any]) -> List[str]:
377
  hints: List[str] = []
378
-
 
 
379
  for key in ("hint_1", "hint_2", "hint_3"):
380
  value = self._clean(pack.get(key))
381
  if value:
382
  hints.append(value)
383
-
384
  hints.extend(self._listify(pack.get("hint_ladder")))
385
  hints.extend(self._listify(pack.get("hints")))
386
-
387
  return self._dedupe(hints)
388
 
389
  def _walkthrough_from_pack(self, pack: Dict[str, Any]) -> List[str]:
@@ -396,11 +401,13 @@ class QuestionFallbackRouter:
396
 
397
  def _method_from_pack(self, pack: Dict[str, Any]) -> List[str]:
398
  lines: List[str] = []
399
- lines.extend(self._listify(pack.get("method_steps")))
400
- lines.extend(self._listify(pack.get("method_explanation")))
401
  concept = self._clean(pack.get("concept"))
402
  if concept:
403
- lines.insert(0, concept)
 
 
 
 
404
  return self._dedupe(lines)
405
 
406
  def _answer_path_from_pack(self, pack: Dict[str, Any]) -> List[str]:
@@ -439,7 +446,7 @@ class QuestionFallbackRouter:
439
  )
440
 
441
  mode = (help_mode or "answer").lower()
442
- stage = max(1, min(int(hint_stage or 1), 3))
443
 
444
  first_step = self._clean(pack.get("first_step"))
445
  hint_ladder = self._hint_ladder_from_pack(pack)
@@ -451,84 +458,38 @@ class QuestionFallbackRouter:
451
  lines: List[str] = []
452
 
453
  if mode == "hint":
454
- selected: List[str] = []
455
-
456
- if stage == 1:
457
- if first_step:
458
- selected.append(first_step)
459
- if hint_ladder:
460
- selected.append(hint_ladder[0])
461
-
462
- if verbosity >= 0.65 and len(hint_ladder) >= 2:
463
- selected.append(hint_ladder[1])
464
-
465
- elif stage == 2:
466
- if len(hint_ladder) >= 2:
467
- selected.append(hint_ladder[1])
468
- elif hint_ladder:
469
- selected.append(hint_ladder[0])
470
-
471
- if verbosity >= 0.45 and first_step:
472
- selected.insert(0, first_step)
473
-
474
- if verbosity >= 0.65 and len(hint_ladder) >= 3:
475
- selected.append(hint_ladder[2])
476
-
477
  else:
478
- if len(hint_ladder) >= 3:
479
- selected.append(hint_ladder[2])
480
- elif hint_ladder:
481
- selected.append(hint_ladder[-1])
482
-
483
- if verbosity >= 0.45 and first_step:
484
- selected.insert(0, first_step)
485
-
486
- if verbosity >= 0.7 and common_trap:
487
- selected.append(f"Watch out for this trap: {common_trap}")
488
-
489
- lines = self._dedupe(selected) or [first_step or "Start by identifying the structure of the question."]
490
 
491
  elif mode in {"walkthrough", "step_by_step", "instruction"}:
492
- if walkthrough_steps:
493
- limit = self._verbosity_limit(verbosity, low=2, mid=4, high=6)
494
- lines = walkthrough_steps[:limit]
495
- elif answer_path:
496
- limit = self._verbosity_limit(verbosity, low=2, mid=3, high=5)
497
- lines = answer_path[:limit]
498
- elif hint_ladder:
499
- limit = self._verbosity_limit(verbosity, low=1, mid=2, high=3)
500
- lines = hint_ladder[:limit]
501
- else:
502
- lines = [first_step or "Start by setting up the problem."]
503
-
504
  if verbosity >= 0.7 and common_trap:
505
  lines = list(lines) + [f"Watch out for this trap: {common_trap}"]
506
 
507
  elif mode in {"method", "explain", "concept", "definition"}:
508
  source = method_steps or walkthrough_steps or answer_path or hint_ladder
509
- if source:
510
- limit = self._verbosity_limit(verbosity, low=1, mid=2, high=4)
511
- lines = source[:limit]
512
- else:
513
- lines = [first_step or "Start from the problem structure."]
514
-
515
  if verbosity >= 0.65 and common_trap:
516
  lines = list(lines) + [f"Common trap: {common_trap}"]
517
 
518
  else:
519
  source = answer_path or walkthrough_steps or hint_ladder
520
- if source:
521
- limit = self._verbosity_limit(verbosity, low=2, mid=3, high=5)
522
- lines = source[:limit]
523
- else:
524
- lines = [first_step or "Start by identifying the relationship in the question."]
525
 
526
  lines = self._dedupe(lines)
527
-
528
- return {
529
- "lines": lines,
530
- "pack": pack,
531
- }
532
 
533
 
534
  question_fallback_router = QuestionFallbackRouter()
 
37
  q = (question_text or "").lower()
38
  t = (topic or "").strip().lower()
39
 
40
+ if t and t not in {"general", "unknown", "general_quant", "quant"}:
41
  return t
42
+ if t == "quant":
43
+ t = ""
44
  if "%" in q or "percent" in q:
45
  return "percent"
46
  if "ratio" in q or re.search(r"\b\d+\s*:\s*\d+\b", q):
 
51
  return "number_theory"
52
  if any(k in q for k in ["triangle", "circle", "angle", "area", "perimeter", "rectangle", "circumference"]):
53
  return "geometry"
54
+ if any(k in q for k in ["mean", "median", "average", "standard deviation", "variability", "spread"]):
55
  return "statistics"
56
  if "=" in q or re.search(r"\b[xyzabn]\b", q):
57
  return "algebra"
 
81
  def _extract_percent_values(self, question_text: str) -> List[str]:
82
  return re.findall(r"\d+\.?\d*\s*%", question_text or "")
83
 
84
+ def _looks_like_linear_equation(self, question_text: str) -> bool:
85
+ q = self._clean(question_text)
86
+ low = q.lower()
87
+ return bool(
88
+ "=" in q
89
+ and re.search(r"\bwhat is\s+[a-z]\b", low)
90
+ and re.search(r"\d+[a-z]\b|\b[a-z]\b", q)
91
+ )
92
+
93
+ def _pack_looks_generic(self, pack: Dict[str, Any], topic: str) -> bool:
94
+ if not pack:
95
+ return True
96
+ joined = " ".join(
97
+ [
98
+ self._clean(pack.get("first_step")),
99
+ self._clean(pack.get("hint_1")),
100
+ self._clean(pack.get("hint_2")),
101
+ self._clean(pack.get("hint_3")),
102
+ " ".join(self._listify(pack.get("walkthrough_steps"))),
103
+ " ".join(self._listify(pack.get("method_explanation"))),
104
+ ]
105
+ ).lower()
106
+ generic_signals = [
107
+ "write the equation clearly and identify the variable",
108
+ "undo operations in reverse order",
109
+ "keep both sides balanced",
110
+ "break the question into known and unknown parts",
111
+ "what is being asked?",
112
+ "what information is given?",
113
+ "translate words into math",
114
+ ]
115
+ if any(signal in joined for signal in generic_signals):
116
+ return True
117
+ if topic == "algebra" and "look at the structure" in joined:
118
+ return True
119
+ return False
120
+
121
  def _topic_defaults(self, topic: str, question_text: str, options_text: Optional[List[str]]) -> Dict[str, Any]:
122
  preview = self._preview_question(question_text)
123
  equation = self._extract_equation(question_text)
 
152
  }
153
 
154
  if topic == "algebra":
155
+ if self._looks_like_linear_equation(question_text):
156
+ generic.update(
157
+ {
158
+ "first_step": "Look at the variable side and identify the outermost operation attached to the variable.",
159
+ "hint_1": "Undo the outside addition or subtraction on both sides before touching the coefficient.",
160
+ "hint_2": "Once only the variable term remains, undo the multiplication or division.",
161
+ "hint_3": "After isolating the variable, compare carefully with what the question actually asks for.",
162
+ "hint_ladder": [
163
+ "Look at the variable side and identify the outermost operation attached to the variable.",
164
+ "Undo the outside addition or subtraction on both sides before touching the coefficient.",
165
+ "Once only the variable term remains, undo the multiplication or division.",
166
+ ],
167
+ "walkthrough_steps": [
168
+ "Write the equation cleanly and focus on the side containing the variable.",
169
+ "Undo the constant attached to that side using the opposite operation on both sides.",
170
+ "Then undo the coefficient attached to the variable.",
171
+ "Only then compare the isolated value with the answer choices or requested expression.",
172
+ ],
173
+ "method_steps": [
174
+ "Linear equations are solved by reversing operations in the opposite order from how they were built.",
175
+ "Keep the equation balanced by doing the same thing to both sides each time.",
176
+ ],
177
+ "answer_path": [
178
+ "Undo the constant on the variable side first.",
179
+ "Then undo the coefficient attached to the variable.",
180
+ "Check whether the question asks for the variable itself or for an expression built from it.",
181
+ ],
182
+ "common_trap": "Dividing by the coefficient too early before removing the constant term.",
183
+ }
184
+ )
185
+ elif equation:
186
+ generic.update(
187
+ {
188
+ "first_step": f"Start from the equation {equation} and decide which operation should be reversed first.",
189
+ "hint_1": "Preserve balance by doing the same operation to both sides.",
190
+ "hint_2": "Reverse the operations in a sensible order instead of trying to simplify everything at once.",
191
+ "hint_3": "Only evaluate the target expression after the variables are in a usable form.",
192
+ }
193
+ )
194
 
195
  elif topic == "percent":
196
  first_step = "Identify the base quantity before doing any percent calculation."
197
  if percent_values:
198
  first_step = f"Track the percentage relationship carefully here: {' then '.join(percent_values[:2]) if len(percent_values) > 1 else percent_values[0]}"
199
+ if "increased by" in question_text.lower() and "decreased by" in question_text.lower():
200
+ generic.update(
201
+ {
202
+ "first_step": "Turn each percentage change into its own multiplier before combining anything.",
203
+ "hint_1": "An increase and a decrease of the same percent do not cancel because they apply to different bases.",
204
+ "hint_2": "Apply the first multiplier, then apply the second multiplier to the updated amount.",
205
+ "hint_3": "Compare the final amount with the original amount only at the end.",
206
+ "hint_ladder": [
207
+ "Turn each percentage change into its own multiplier before combining anything.",
208
+ "Apply the first multiplier, then apply the second multiplier to the updated amount.",
209
+ "Compare the final amount with the original amount only at the end.",
210
+ ],
211
+ }
212
+ )
213
+ else:
214
+ generic.update(
215
+ {
216
+ "first_step": first_step,
217
+ "hint_1": "Ask 'percent of what?' so you choose the correct base quantity.",
218
+ "hint_2": "Rewrite the percent as a decimal or fraction if that makes the relationship clearer.",
219
+ "hint_3": "Set up part = percent × base, or reverse that relationship if the base is unknown.",
220
+ "hint_ladder": [
221
+ "Ask 'percent of what?' so you choose the correct base quantity.",
222
+ "Rewrite the percent as a decimal or fraction if that makes the relationship clearer.",
223
+ "Set up part = percent × base, or reverse that relationship if the base is unknown.",
224
+ ],
225
+ }
226
+ )
 
 
 
227
 
228
  elif topic == "ratio":
229
  first_step = "Keep the ratio order consistent and assign one shared multiplier."
230
  if ratio_text:
231
  first_step = f"Use the ratio {ratio_text} as parts of one whole."
 
 
 
 
 
232
  generic.update(
233
  {
234
  "first_step": first_step,
235
+ "hint_1": "Write each part of the ratio using the same multiplier.",
236
+ "hint_2": "Use the total or known part to solve for that shared multiplier.",
237
+ "hint_3": "Substitute back into the exact quantity the question asks for.",
238
+ "hint_ladder": [
239
+ "Write each part of the ratio using the same multiplier.",
240
+ "Use the total or known part to solve for that shared multiplier.",
241
+ "Substitute back into the exact quantity the question asks for.",
242
+ ],
243
  "walkthrough_steps": [
244
  first_step,
245
+ "Represent each ratio part in terms of one common variable such as k.",
246
+ "Use the given total or condition to find k.",
247
+ "Build the requested expression from those ratio parts.",
248
  ],
249
  "method_steps": [
250
+ "Ratio problems usually become easier once you turn the ratio into matching parts.",
251
+ "Avoid treating ratio numbers as the actual values unless the problem tells you they are.",
 
 
 
 
 
252
  ],
253
+ "common_trap": "Using the raw ratio numbers as real values before solving for the common multiplier.",
254
  }
255
  )
256
 
257
  elif topic == "probability":
 
 
 
 
258
  generic.update(
259
  {
260
+ "first_step": "Decide what counts as a successful outcome before you count anything.",
261
+ "hint_1": "Count the favorable outcomes that satisfy the condition.",
262
+ "hint_2": "Count the total possible outcomes in the sample space.",
263
+ "hint_3": "Build the probability as favorable over total, then simplify if needed.",
264
+ "hint_ladder": [
265
+ "Decide what counts as a successful outcome before you count anything.",
266
+ "Count the favorable outcomes that satisfy the condition.",
267
+ "Count the total possible outcomes in the sample space.",
268
+ ],
269
  "walkthrough_steps": [
270
+ "Define the event the question cares about.",
271
+ "Count or construct the favorable cases.",
272
+ "Count the total cases in the sample space.",
273
+ "Write the probability as favorable over total.",
274
  ],
275
  "method_steps": [
276
+ "Probability questions become clearer once the event and the sample space are both explicit.",
277
+ "Many errors come from counting the wrong denominator, not the numerator.",
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
278
  ],
279
+ "common_trap": "Changing the denominator incorrectly or forgetting which cases are actually favorable.",
280
  }
281
  )
282
+ if "at least" in question_text.lower():
283
+ generic["hint_2"] = "Check whether the complement is easier to count than the requested event."
284
+ generic["hint_ladder"] = [
285
+ generic["hint_1"],
286
+ "Check whether the complement is easier to count than the requested event.",
287
+ generic["hint_3"],
288
+ ]
289
 
290
  elif topic == "statistics":
291
+ qlow = question_text.lower()
 
292
  if any(k in qlow for k in ["variability", "spread", "standard deviation"]):
293
  generic.update(
294
  {
295
+ "first_step": "Notice that this is about spread, not average.",
296
+ "hint_1": "Use the middle value as a centre and compare how far the outer values sit from it.",
297
+ "hint_2": "A set with values clustered tightly has lower variability than a set spread farther apart.",
298
+ "hint_3": "Choose the set with the widest spread, not the largest mean.",
299
  "hint_ladder": [
300
+ "Notice that this is about spread, not average.",
301
+ "Use the middle value as a centre and compare how far the outer values sit from it.",
302
+ "Choose the set with the widest spread, not the largest mean.",
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
303
  ],
 
304
  }
305
  )
306
  else:
307
  generic.update(
308
  {
309
+ "first_step": "Identify which statistical measure the question wants before calculating anything.",
310
+ "hint_1": "Check whether the task is asking for mean, median, range, or another measure.",
311
+ "hint_2": "Organise the data in a clean order if that helps reveal the measure.",
312
+ "hint_3": "Use the exact definition of the requested measure rather than a nearby one.",
 
 
 
 
 
 
313
  }
314
  )
315
 
316
  if has_options:
317
  generic["answer_path"] = list(generic.get("answer_path", [])) + [
318
+ "Use the answer choices to check which setup fits the question instead of guessing."
319
  ]
320
 
321
  return generic
322
 
323
+ def _merge_support_pack(self, generated: Dict[str, Any], stored: Optional[Dict[str, Any]], topic: str) -> Dict[str, Any]:
324
+ if not stored:
325
+ merged = dict(generated)
326
+ merged["support_source"] = "generated_question_specific"
327
+ return merged
328
+
329
+ merged = dict(generated)
330
+ merged.update(dict(stored))
331
+
332
+ if self._pack_looks_generic(stored, topic):
333
+ for key in [
334
+ "first_step",
335
+ "hint_1",
336
+ "hint_2",
337
+ "hint_3",
338
+ "hint_ladder",
339
+ "walkthrough_steps",
340
+ "method_steps",
341
+ "answer_path",
342
+ "common_trap",
343
+ ]:
344
+ if key in generated:
345
+ merged[key] = generated[key]
346
+ merged["support_source"] = "question_bank_refined"
347
+ else:
348
+ merged.setdefault("support_source", "question_bank")
349
+
350
+ merged.setdefault("method_steps", generated.get("method_steps", []))
351
+ merged.setdefault("answer_path", generated.get("answer_path", []))
352
+ return merged
353
+
354
  def get_support_pack(
355
  self,
356
  *,
 
360
  topic: Optional[str],
361
  category: Optional[str],
362
  ) -> Dict[str, Any]:
 
363
  resolved_topic = self._normalize_topic(topic, question_text)
 
 
 
 
 
 
 
 
 
 
 
364
  generated = self._topic_defaults(resolved_topic, question_text, options_text)
365
+ stored = question_support_bank.get(
366
+ question_id=question_id,
367
+ question_text=question_text,
368
+ options_text=options_text,
 
 
 
 
 
369
  )
370
+
371
+ pack = self._merge_support_pack(generated, stored, resolved_topic)
372
+ pack.setdefault("question_id", question_id)
373
+ pack.setdefault("question_text", question_text)
374
+ pack.setdefault("stem", question_text)
375
+ pack.setdefault("options_text", list(options_text or []))
376
+ pack.setdefault("choices", list(options_text or []))
377
+ pack.setdefault("topic", resolved_topic)
378
+ pack.setdefault("category", category or "General")
379
+ return pack
380
 
381
  def _hint_ladder_from_pack(self, pack: Dict[str, Any]) -> List[str]:
382
  hints: List[str] = []
383
+ first_step = self._clean(pack.get("first_step"))
384
+ if first_step:
385
+ hints.append(first_step)
386
  for key in ("hint_1", "hint_2", "hint_3"):
387
  value = self._clean(pack.get(key))
388
  if value:
389
  hints.append(value)
 
390
  hints.extend(self._listify(pack.get("hint_ladder")))
391
  hints.extend(self._listify(pack.get("hints")))
 
392
  return self._dedupe(hints)
393
 
394
  def _walkthrough_from_pack(self, pack: Dict[str, Any]) -> List[str]:
 
401
 
402
  def _method_from_pack(self, pack: Dict[str, Any]) -> List[str]:
403
  lines: List[str] = []
 
 
404
  concept = self._clean(pack.get("concept"))
405
  if concept:
406
+ lines.append(concept)
407
+ lines.extend(self._listify(pack.get("method_steps")))
408
+ lines.extend(self._listify(pack.get("method_explanation")))
409
+ if not lines:
410
+ lines.extend(self._walkthrough_from_pack(pack)[:3])
411
  return self._dedupe(lines)
412
 
413
  def _answer_path_from_pack(self, pack: Dict[str, Any]) -> List[str]:
 
446
  )
447
 
448
  mode = (help_mode or "answer").lower()
449
+ stage = max(1, min(int(hint_stage or 1), 4))
450
 
451
  first_step = self._clean(pack.get("first_step"))
452
  hint_ladder = self._hint_ladder_from_pack(pack)
 
458
  lines: List[str] = []
459
 
460
  if mode == "hint":
461
+ if hint_ladder:
462
+ idx = min(stage - 1, len(hint_ladder) - 1)
463
+ selected = [hint_ladder[idx]]
464
+ if verbosity >= 0.7 and idx + 1 < len(hint_ladder):
465
+ selected.append(hint_ladder[idx + 1])
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
466
  else:
467
+ selected = [first_step or "Start by identifying the structure of the question."]
468
+ if verbosity >= 0.75 and stage >= 3 and common_trap:
469
+ selected.append(f"Watch out for this trap: {common_trap}")
470
+ lines = self._dedupe(selected)
 
 
 
 
 
 
 
 
471
 
472
  elif mode in {"walkthrough", "step_by_step", "instruction"}:
473
+ source = walkthrough_steps or answer_path or hint_ladder
474
+ limit = self._verbosity_limit(verbosity, low=2, mid=4, high=6)
475
+ lines = source[:limit] if source else [first_step or "Start by setting up the problem."]
 
 
 
 
 
 
 
 
 
476
  if verbosity >= 0.7 and common_trap:
477
  lines = list(lines) + [f"Watch out for this trap: {common_trap}"]
478
 
479
  elif mode in {"method", "explain", "concept", "definition"}:
480
  source = method_steps or walkthrough_steps or answer_path or hint_ladder
481
+ limit = self._verbosity_limit(verbosity, low=1, mid=2, high=4)
482
+ lines = source[:limit] if source else [first_step or "Start from the problem structure."]
 
 
 
 
483
  if verbosity >= 0.65 and common_trap:
484
  lines = list(lines) + [f"Common trap: {common_trap}"]
485
 
486
  else:
487
  source = answer_path or walkthrough_steps or hint_ladder
488
+ limit = self._verbosity_limit(verbosity, low=2, mid=3, high=5)
489
+ lines = source[:limit] if source else [first_step or "Start by identifying the relationship in the question."]
 
 
 
490
 
491
  lines = self._dedupe(lines)
492
+ return {"lines": lines, "pack": pack}
 
 
 
 
493
 
494
 
495
  question_fallback_router = QuestionFallbackRouter()