Upload 7 files

explainers/Percent Explainer

@@ -0,0 +1,49 @@
+# explainer_percent
+
+import re
+from models import ExplainerResult
+
+def explain_percent_question(text: str) -> ExplainerResult | None:
+    t = text.lower()
+
+    if "%" not in t and "percent" not in t:
+        return None
+
+    # basic detection
+    numbers = re.findall(r'\d+', t)
+
+    givens = []
+    relationships = []
+
+    if "of" in t:
+        relationships.append("This is a part-of-whole relationship")
+
+    if "%" in t:
+        givens.append("A percentage is given")
+
+    asks_for = None
+    if "what is" in t or "find" in t:
+        asks_for = "the unknown quantity (likely the whole or part)"
+
+    return ExplainerResult(
+        understood=True,
+        topic="percent",
+
+        asks_for=asks_for,
+        givens=givens,
+        constraints=[],
+
+        relationships=relationships,
+        needed_concepts=[
+            "percent equation (part = percent × whole)"
+        ],
+
+        trap_notes=[
+            "Do not confuse the part and the whole",
+            "Check whether you are solving forward or backward"
+        ],
+
+        strategy_hint="Translate the sentence into a percent equation before solving.",
+
+        plain_english="The question describes a percentage relationship and is asking you to identify the missing value in that relationship."
+    )

explainers/__init__.py

@@ -0,0 +1 @@
+.

explainers/explainer_result

@@ -0,0 +1,21 @@
+# models.py
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+@dataclass
+class ExplainerResult:
+    understood: bool
+    topic: Optional[str]
+
+    asks_for: Optional[str]              # what is the target
+    givens: List[str]                   # extracted facts
+    constraints: List[str]              # conditions / limits
+
+    relationships: List[str]            # how things connect (key insight)
+    needed_concepts: List[str]          # what math idea is required
+
+    trap_notes: List[str]               # common mistakes
+    strategy_hint: Optional[str]        # how you'd approach (no solving)
+
+    plain_english: Optional[str]        # simplified restatement

explainers/explainer_router

@@ -0,0 +1,17 @@
+# explainer_router.py
+
+from explainer_percent import explain_percent_question
+from explainer_ratio import explain_ratio_question
+from explainer_algebra import explain_algebra_question
+
+def route_explainer(text: str):
+    for fn in [
+        explain_percent_question,
+        explain_ratio_question,
+        explain_algebra_question,
+    ]:
+        result = fn(text)
+        if result:
+            return result
+
+    return None

explainers/formatters

@@ -0,0 +1,23 @@
+def format_explainer_response(result, sliders):
+    lines = []
+
+    if result.plain_english:
+        lines.append(result.plain_english)
+
+    if sliders.transparency > 0.5:
+        if result.asks_for:
+            lines.append(f"\n👉 The question is asking for: {result.asks_for}")
+
+        if result.relationships:
+            lines.append("\n🔗 Key relationship:")
+            lines.extend(f"- {r}" for r in result.relationships)
+
+        if result.needed_concepts:
+            lines.append("\n🧠 Concepts you'll need:")
+            lines.extend(f"- {c}" for c in result.needed_concepts)
+
+        if result.trap_notes:
+            lines.append("\n⚠️ Watch out:")
+            lines.extend(f"- {t}" for t in result.trap_notes)
+
+    return "\n".join(lines)

explainers/integrate to convo logic

@@ -0,0 +1,13 @@
+def is_explainer_request(text: str) -> bool:
+    t = text.lower()
+
+    triggers = [
+        "what is this asking",
+        "what does this mean",
+        "explain the question",
+        "what do i need to find",
+        "decode this",
+        "what is being asked"
+    ]
+
+    return any(p in t for p in triggers)

explainers/main flow

@@ -0,0 +1,5 @@
+if is_explainer_request(user_text):
+    explainer_result = route_explainer(user_text)
+
+    if explainer_result:
+        return format_explainer_response(explainer_result, sliders)