Update explainers/explainer_percent.py

explainers/explainer_percent.py

@@ -2,246 +2,283 @@ import re
 from .explainer_types import ExplainerResult, ExplainerScaffold
 
 
-_ALGEBRA_PATTERNS = [
-    r"=",
-    r"\bsolve\b",
-    r"\bequation\b",
-    r"\bexpression\b",
-    r"\bvalue of\b",
-    r"\bwhat is x\b",
-    r"\bwhat is y\b",
-    r"\bvariable\b",
+_PERCENT_PATTERNS = [
+    r"\bpercent\b",
+    r"\bpercentage\b",
+    r"\bwhat percent\b",
+    r"\bpercent of\b",
+    r"\bpercent greater than\b",
+    r"\bpercent less than\b",
+    r"\bincrease(?:d)? by \d+ ?%\b",
+    r"\bdecrease(?:d)? by \d+ ?%\b",
+    r"\bdiscount\b",
+    r"\bmarkup\b",
+    r"\binterest\b",
+    r"\btax\b",
+    r"\btip\b",
+    r"\bprofit margin\b",
+    r"\bcommission\b",
+    r"\bpart of\b",
+    r"\bof a number\b",
 ]
 
 
-def _looks_like_algebra_question(text: str) -> bool:
+def _looks_like_percent_question(text: str) -> bool:
     low = (text or "").lower()
-
-    if re.search(r"\b[xyzab]\b", low) and "=" in low:
-        return True
-    if any(re.search(p, low) for p in _ALGEBRA_PATTERNS):
+    if "%" in low:
         return True
-    return False
+    return any(re.search(p, low) for p in _PERCENT_PATTERNS)
 
 
-def _infer_algebra_subtype(text: str) -> str:
+def _infer_percent_subtype(text: str) -> str:
     low = (text or "").lower()
 
-    if any(k in low for k in ["system", "simultaneous", "x and y", "two equations"]):
-        return "system"
-    if any(k in low for k in ["inequality", "<", ">", "at least", "at most", "no more than"]):
-        return "inequality"
-    if any(k in low for k in ["quadratic", "squared", "^2", "x2", "root", "factor"]):
-        return "quadratic"
-    if any(k in low for k in ["expression", "value of 2x", "value of x +", "in terms of"]):
-        return "expression_evaluation"
-    if "=" in low:
-        return "linear_equation"
-    return "generic_algebra"
-
-
-def explain_algebra_question(text: str):
-    if not _looks_like_algebra_question(text):
+    if any(k in low for k in ["increase", "decrease", "increased", "decreased", "percent change", "changed by"]):
+        return "percent_change"
+    if any(k in low for k in ["discount", "sale", "off", "markdown"]):
+        return "discount"
+    if any(k in low for k in ["interest", "simple interest", "compound interest"]):
+        return "interest"
+    if any(k in low for k in ["tax", "vat", "tip", "gratuity"]):
+        return "tax_tip"
+    if any(k in low for k in ["what percent", "is what percent of", "as a percent of"]):
+        return "percent_of_percent"
+    if any(k in low for k in ["percent of", "of a number", "% of"]):
+        return "basic_percent"
+    return "generic_percent"
+
+
+def explain_percent_question(text: str):
+    if not _looks_like_percent_question(text):
         return None
 
-    subtype = _infer_algebra_subtype(text)
-    low = (text or "").lower()
+    subtype = _infer_percent_subtype(text)
 
     result = ExplainerResult(
         understood=True,
-        topic="algebra",
-        summary="This is an algebra problem. The main goal is to translate the wording into a clean symbolic relationship and isolate the requested quantity step by step.",
-        asks_for="the value of the variable or the requested expression built from it",
-        plain_english="Algebra questions usually become easier once you write one clean equation and then reverse the operations in order.",
+        topic="percent",
+        summary="This is a percent problem. The key is to identify which quantity is the base, which is the compared amount, and what role the percent is playing.",
+        asks_for="the missing value, the percent itself, or the final changed total",
+        plain_english="Percent means per hundred, so the safest route is to identify the base first and then match the wording to the correct percent template.",
     )
 
     scaffold = ExplainerScaffold(
-        concept="Algebra represents unknown quantities symbolically, then uses valid transformations to isolate or compare them.",
-        ask="Identify the unknown, identify the governing relationship, and check whether the question wants the variable itself or an expression built from it.",
-        target="Set up the simplest correct equation or relation before manipulating it.",
+        concept="Percent problems are built around a base amount, a compared amount, and a rate per hundred.",
+        ask="Decide which quantity is the whole/base, which quantity is the part or changed amount, and whether the question is asking for a percent, a value, or a new total.",
+        target="Translate the wording into the correct percent relationship before doing any arithmetic.",
         answer_hidden=True,
         solution_path_type=subtype,
     )
 
+    result.teaching_points = [
+        "Percent means per hundred, so it should usually be converted to a decimal or fraction before setting up the relationship.",
+        "Most percent questions reduce to one of a small number of templates, so identifying the template matters more than rushing into calculation.",
+        "The biggest source of error is choosing the wrong base quantity.",
+    ]
     result.givens = [
-        "A symbolic relationship or equation is implied by the wording.",
+        "A percent, base, part, or changed amount is implied by the wording.",
     ]
-    if "=" in low:
-        result.givens.append("An equals sign or equation structure is present.")
-
     result.relationships = [
-        "Both sides of an equation must stay balanced.",
-        "Each algebra step should simplify or isolate the target quantity.",
+        "Percent relationships depend on correctly matching part, whole, and rate.",
     ]
     result.needed_concepts = [
-        "equation balancing",
-        "inverse operations",
-        "checking what the question actually asks for",
+        "base vs part",
+        "percent as a decimal or fraction",
+        "choosing the correct percent template",
     ]
     result.trap_notes = [
-        "Moving terms across the equals sign incorrectly.",
-        "Trying to isolate the variable before simplifying.",
-        "Finding x and forgetting the question asks for something like 2x or x + 3.",
-    ]
-    result.strategy_hint = "Rewrite the relationship as one clean equation before doing any manipulation."
-
-    result.teaching_points = [
-        "Most algebra errors happen before the solving starts: either the variable is misdefined, or the equation is set up incorrectly.",
-        "A clean equation makes the solving steps much easier.",
-        "You should always check whether the question asks for x itself or for something derived from x.",
+        "Choosing the wrong base quantity.",
+        "Using 40 instead of 0.40.",
+        "Confusing a basic percent-of problem with a percent-change problem.",
     ]
+    result.strategy_hint = "Start by asking: percent of what?"
 
-    if subtype == "linear_equation":
+    if subtype == "basic_percent":
         scaffold.setup_actions = [
-            "Identify the unknown and write the equation cleanly.",
-            "Simplify each side if needed.",
-            "Undo operations in a logical order to isolate the variable.",
+            "Label the known quantities as part, whole, and percent.",
+            "Convert the percent to a decimal or fraction.",
+            "Match the statement to the relationship: part = percent × whole.",
         ]
         scaffold.intermediate_steps = [
-            "Combine like terms first when possible.",
-            "Move variable terms and constant terms carefully.",
-            "Check whether the final result should be the variable or a substituted expression.",
+            "If the whole is unknown, assign it a variable.",
+            "Substitute the known values into the relationship.",
+            "Solve only after the structure is correct.",
         ]
-        scaffold.first_move = "Rewrite the relationship as one clean equation if it is not already in that form."
-        scaffold.next_hint = "Simplify both sides before isolating the variable."
+        scaffold.first_move = "Start by identifying the whole and the part."
+        scaffold.next_hint = "Once those roles are clear, write one equation connecting part, percent, and whole."
         scaffold.variables_to_define = [
-            "Let the unknown quantity be x if the question has not already named it.",
+            "Let x represent the unknown quantity if either the part or whole is missing.",
+        ]
+        scaffold.equations_to_form = [
+            "part = percent × whole",
         ]
+        scaffold.key_operations = [
+            "identify the base",
+            "convert percent to decimal",
+            "build one equation",
+        ]
+        scaffold.hint_ladder = [
+            "Which quantity is the whole?",
+            "What is the percent as a decimal?",
+            "Can you write part = percent × whole?",
+        ]
+
+    elif subtype == "percent_of_percent":
+        scaffold.setup_actions = [
+            "Identify the comparison being made.",
+            "Place the compared quantity over the base quantity.",
+            "Convert the resulting fraction to a percent.",
+        ]
+        scaffold.intermediate_steps = [
+            "Make sure the denominator is the reference/base amount.",
+            "Simplify the fraction if helpful.",
+            "Only convert to percent at the end.",
+        ]
+        scaffold.first_move = "Ask: percent of what?"
+        scaffold.next_hint = "Use the base quantity as the denominator in the fraction before converting."
         scaffold.equations_to_form = [
-            "Build one equation from the stated relationship.",
+            "percent = (part / whole) × 100",
         ]
         scaffold.key_operations = [
-            "Simplify",
-            "undo addition/subtraction",
-            "undo multiplication/division",
+            "form the fraction",
+            "use the base as denominator",
+            "convert to percent",
         ]
         scaffold.hint_ladder = [
-            "What operation is attached to the variable?",
-            "What inverse operation would undo it?",
-            "Apply that same operation to both sides.",
+            "What is the reference amount?",
+            "Which number belongs in the denominator?",
+            "Multiply by 100 only after the fraction is correct.",
         ]
 
-    elif subtype == "system":
+    elif subtype == "percent_change":
         scaffold.setup_actions = [
-            "Identify the separate equations and unknowns.",
-            "Decide whether substitution or elimination is the cleaner method.",
-            "Reduce the system to one variable before solving completely.",
+            "Identify the original value and the new value.",
+            "Find the amount of change first.",
+            "Use the original value as the base in the percent-change formula.",
         ]
         scaffold.intermediate_steps = [
-            "Make one variable easy to substitute, or align coefficients for elimination.",
-            "After finding one variable, substitute back carefully.",
-            "Check whether the question asks for one variable, both variables, or a combination of them.",
+            "Compute change = new − original.",
+            "Place that change over the original value.",
+            "Convert the result to a percent.",
         ]
-        scaffold.first_move = "Choose one variable to eliminate or substitute."
-        scaffold.next_hint = "Turn the system into a single-variable equation before solving."
+        scaffold.first_move = "Find the amount of increase or decrease before thinking about the percent."
+        scaffold.next_hint = "After that, divide by the original amount, not the new amount."
         scaffold.equations_to_form = [
-            "Use the two given equations together to reduce to one unknown.",
+            "percent change = (new − original) / original × 100",
         ]
         scaffold.key_operations = [
-            "substitute",
-            "eliminate",
-            "back-substitute",
+            "find the change",
+            "divide by the original",
+            "convert to percent",
         ]
         scaffold.hint_ladder = [
-            "Which variable looks easier to isolate?",
-            "Can you align coefficients for elimination?",
-            "After finding one variable, plug it back into the other equation.",
+            "Which value is original?",
+            "What is the amount of change?",
+            "Which quantity belongs in the denominator?",
         ]
 
-    elif subtype == "inequality":
+    elif subtype == "discount":
         scaffold.setup_actions = [
-            "Translate the condition into an inequality.",
-            "Manipulate it like an equation, but track the inequality direction carefully.",
-            "Reverse the sign only if multiplying or dividing by a negative number.",
+            "Identify the original price and the discount rate.",
+            "Find the discount amount from the original price.",
+            "Subtract the discount from the original price if the question asks for the sale price.",
         ]
         scaffold.intermediate_steps = [
-            "Simplify both sides first if possible.",
-            "Isolate the variable systematically.",
-            "Interpret the final solution set in the form the question wants.",
+            "Treat the listed price as the base.",
+            "Compute the discount amount separately from the final price.",
+            "Check whether the question asks for discount amount or discounted price.",
+        ]
+        scaffold.first_move = "Use the original price as the percent base."
+        scaffold.next_hint = "Find the discount amount first, then decide whether to stop or subtract."
+        scaffold.equations_to_form = [
+            "discount = rate × original price",
+            "sale price = original price − discount",
         ]
-        scaffold.first_move = "Set up the inequality carefully from the wording."
-        scaffold.next_hint = "Solve it step by step, watching for any operation that would reverse the sign."
         scaffold.key_operations = [
-            "translate wording to an inequality",
-            "simplify",
-            "watch for sign reversal with negatives",
+            "identify the original price",
+            "find discount amount",
+            "subtract if needed",
         ]
         scaffold.hint_ladder = [
-            "What phrase tells you the direction of the inequality?",
-            "Can you simplify both sides first?",
-            "Did you divide or multiply by a negative at any point?",
+            "What is the original price?",
+            "What percent of that price is the discount?",
+            "Does the question want the discount or the final price?",
         ]
 
-    elif subtype == "quadratic":
+    elif subtype == "interest":
         scaffold.setup_actions = [
-            "Rewrite the equation so one side is zero if needed.",
-            "Look for factoring, structure, or another simplifying method.",
-            "Treat each factor or case carefully once the equation is structured properly.",
+            "Identify principal, rate, and time.",
+            "Determine whether the question is simple interest or compound interest.",
+            "Set up the matching formula structure.",
         ]
         scaffold.intermediate_steps = [
-            "Factor if the form allows it.",
-            "Otherwise identify another clean solving route.",
-            "Check whether all resulting values are allowed in the original context.",
+            "For simple interest, keep the principal fixed.",
+            "For compound interest, recognize that the base changes from period to period.",
+            "Check whether the question asks for interest earned or final amount.",
         ]
-        scaffold.first_move = "Put the expression into a standard structured form before solving."
-        scaffold.next_hint = "Then look for a factorable pattern or another clean route."
+        scaffold.first_move = "Work out whether the interest is simple or compound."
+        scaffold.next_hint = "Then identify which quantity stays fixed and which quantity grows."
         scaffold.key_operations = [
-            "standardize the expression",
-            "factor or use structure",
-            "check all roots back in context",
+            "identify principal, rate, and time",
+            "match simple vs compound",
+            "check whether the target is interest or total amount",
         ]
         scaffold.hint_ladder = [
-            "Can you move everything to one side first?",
-            "Does the expression factor neatly?",
-            "Do all candidate solutions actually fit the original question?",
+            "Is the base changing each period?",
+            "Which quantity is the principal?",
+            "Does the question want interest earned or the total balance?",
         ]
 
-    elif subtype == "expression_evaluation":
+    elif subtype == "tax_tip":
         scaffold.setup_actions = [
-            "Find the variable or relationship first.",
-            "Only then substitute into the requested expression.",
-            "Simplify the final expression carefully.",
+            "Identify the pre-tax or pre-tip amount.",
+            "Use that original amount as the base.",
+            "Compute the tax or tip amount before adding if a total is required.",
         ]
         scaffold.intermediate_steps = [
-            "Do not stop when you find the variable unless that is exactly what the question asks.",
-            "Preserve parentheses during substitution.",
-            "Check whether there is a shortcut using the given relationship directly.",
+            "Separate the added charge from the final amount.",
+            "Check whether multiple percentages are applied independently or sequentially.",
+            "Make sure the question wants the fee amount or the full total.",
+        ]
+        scaffold.first_move = "Use the original listed amount as the base unless the wording clearly says otherwise."
+        scaffold.next_hint = "Find the added percent amount first, then combine only if the question asks for the total."
+        scaffold.equations_to_form = [
+            "added amount = rate × base amount",
+            "total = base amount + added amount",
         ]
-        scaffold.first_move = "Work out whether you need to solve for the variable first or can rewrite the target expression directly."
-        scaffold.next_hint = "Once the relationship is clear, substitute only into the exact expression the question asks for."
         scaffold.key_operations = [
-            "solve or rewrite the relationship",
-            "substitute carefully",
-            "simplify the requested expression",
+            "identify the original amount",
+            "find the added charge",
+            "add only if the question asks for the total",
         ]
         scaffold.hint_ladder = [
-            "What expression does the question actually want?",
-            "Do you already have enough information to rewrite that expression?",
-            "Only substitute after the target expression is clear.",
+            "What is the amount before tax or tip?",
+            "How much is the added percent of that base?",
+            "Does the question stop at the fee or ask for the total bill?",
         ]
 
     else:
         scaffold.setup_actions = [
-            "Define the unknown clearly.",
-            "Translate the wording into a symbolic relationship.",
-            "Manipulate the relationship only after the setup is clean.",
+            "Identify the base quantity.",
+            "Identify the compared quantity or changed amount.",
+            "Match the wording to a standard percent relationship.",
         ]
         scaffold.intermediate_steps = [
-            "Simplify before isolating.",
-            "Keep track of what the question actually asks for.",
-            "Check the final quantity against the prompt.",
+            "Convert the percent appropriately.",
+            "Build one clear relationship before solving.",
+            "Check whether the question asks for a value, a rate, or a final amount.",
         ]
-        scaffold.first_move = "Start by translating the words into one clean symbolic statement."
-        scaffold.next_hint = "Then simplify the structure before solving."
+        scaffold.first_move = "Work out what the percent is being taken of."
+        scaffold.next_hint = "Once the base quantity is clear, write the relationship before calculating."
         scaffold.key_operations = [
-            "translate",
-            "simplify",
-            "isolate",
+            "identify the base",
+            "convert the percent",
+            "match the correct template",
         ]
         scaffold.hint_ladder = [
-            "What is the unknown?",
-            "What relationship connects the quantities?",
-            "What is the cleanest first algebra step?",
+            "What quantity is the base?",
+            "What role does the percent play here?",
+            "Which standard percent relationship matches this wording?",
         ]
 
     result.scaffold = scaffold