feat: Universal Logic V2.0 — Ground Truth Architecture [22/22 tests]

backend/__init__.py

@@ -0,0 +1,2 @@
+# backend/__init__.py
+# BuddyMath V2.0 backend package

backend/extractor.py

@@ -0,0 +1,127 @@
+# backend/extractor.py
+# BuddyMath V2.0 — Stage 1: Extraction LLM
+#
+# RULES (from spec):
+# 1. Extract ONLY. Never solve.
+# 2. If a value is unclear from OCR/text → return null. NO guessing.
+# 3. `find` must list what the question asks, not intermediate steps.
+# 4. `constraints` must list verbal/diagram constraints verbatim.
+# ─────────────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any, Optional
+
+import google.generativeai as genai
+
+from backend.math_schema import MathProblemSchema
+
+logger = logging.getLogger(__name__)
+
+# ── Extraction-only system prompt ────────────────────────────────────────
+_EXTRACTION_SYSTEM_PROMPT = """
+You are a MATH DATA EXTRACTOR. Your ONLY job is to parse the problem and output a strict JSON object.
+
+ABSOLUTE RULES:
+1. DO NOT solve the problem. DO NOT calculate anything.
+2. If a value is unclear, ambiguous, or the OCR image is blurry → use JSON null for that field.
+   null ≠ "field not in problem". null = "field exists in problem but value is unreadable/unclear".
+3. Every field in `given` that the problem mentions must appear — even if its value is null.
+4. `find` must list exactly what the question asks to find/prove/calculate.
+5. `constraints` must list verbal/diagram rules (e.g. "M is the midpoint of AD").
+
+OUTPUT FORMAT (strict JSON, no markdown, no explanation):
+{
+  "problem_type": "<geometry|algebra|probability|statistics|trigonometry|calculus>",
+  "sub_type": "<e.g. circle, quadratic, normal_distribution>",
+  "given": {
+    "<label>": <value_or_null>
+  },
+  "find": ["<what to find 1>", "<what to find 2>"],
+  "constraints": ["<constraint 1>", "<constraint 2>"]
+}
+""".strip()
+
+
+class Extractor:
+    """
+    Calls Gemini Flash to extract structured data from a math problem.
+    Never solves — only parses.
+    """
+
+    def __init__(self, model_name: str = "gemini-2.0-flash"):
+        self._model = genai.GenerativeModel(
+            model_name=model_name,
+            system_instruction=_EXTRACTION_SYSTEM_PROMPT,
+        )
+
+    def extract(
+        self,
+        problem_text: str,
+        image_data: Optional[bytes] = None,
+    ) -> MathProblemSchema:
+        """
+        Extract structured data from a math problem (text + optional image).
+
+        Args:
+            problem_text: The problem as plain text (from OCR or direct input).
+            image_data:   Raw image bytes if the problem came from a photo.
+
+        Returns:
+            MathProblemSchema with verification_status="pending".
+        """
+        logger.info("📥 [EXTRACTOR] Starting extraction...")
+
+        # Build the prompt parts
+        parts: list[Any] = [problem_text]
+        if image_data:
+            parts.append({"mime_type": "image/jpeg", "data": image_data})
+
+        try:
+            response = self._model.generate_content(parts)
+            raw_text = response.text.strip()
+            logger.debug("📄 [EXTRACTOR] Raw LLM output:\n%s", raw_text)
+
+            parsed = self._parse_response(raw_text)
+            schema = MathProblemSchema(**parsed)
+
+            # Log null fields as warnings
+            null_keys = schema.null_fields()
+            if null_keys:
+                for k in null_keys:
+                    msg = f"Null field after extraction: '{k}' — OCR unclear or ambiguous"
+                    schema.warnings.append(msg)
+                    logger.warning("⚠️  [EXTRACTOR] %s", msg)
+
+            logger.info(
+                "✅ [EXTRACTOR] Done. Type=%s/%s | Given=%d fields | Nulls=%s | Find=%s",
+                schema.problem_type,
+                schema.sub_type,
+                len(schema.given),
+                null_keys or "none",
+                schema.find,
+            )
+            return schema
+
+        except Exception as e:
+            logger.error("❌ [EXTRACTOR] Failed: %s", e)
+            raise
+
+    def _parse_response(self, raw: str) -> dict:
+        """
+        Strip markdown fences if present and parse JSON.
+        Raises ValueError on invalid JSON.
+        """
+        # Strip ```json ... ``` if the model wrapped it
+        clean = re.sub(r"^```(?:json)?\s*", "", raw, flags=re.IGNORECASE)
+        clean = re.sub(r"\s*```$", "", clean).strip()
+
+        try:
+            data = json.loads(clean)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Extractor returned invalid JSON: {e}\nRaw:\n{raw}") from e
+
+        return data

backend/math_schema.py

@@ -0,0 +1,97 @@
+# backend/math_schema.py
+# BuddyMath V2.0 — The "Truth Anchor" Architecture
+# Data Contract: MATH_PROBLEM_SCHEMA (Approved by Dotan, 2026-03-19)
+#
+# RULES:
+# - `given` fields are set by the Extractor only. Never by the Verifier.
+# - `verified` is set by the Verifier only. Never by the Extractor.
+# - `null` in `given` means "field was expected but OCR was unclear" — NOT "field doesn't exist".
+# - Only the pipeline (orchestrator) may change `verification_status`.
+# ─────────────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class MathProblemSchema(BaseModel):
+    """
+    The single source of truth for a parsed math problem.
+    Flows through: Extractor → Verifier → Pinner → LLM.
+    """
+
+    # ── What type of problem ────────────────────────────────────────────
+    problem_type: Literal[
+        "geometry",
+        "algebra",
+        "probability",
+        "statistics",
+        "trigonometry",
+        "calculus",
+    ]
+    sub_type: str  # e.g. "circle", "quadratic", "normal_distribution"
+
+    # ── What is given (Extractor fills this) ────────────────────────────
+    # null value = "was expected but OCR/text was unclear" (not the same as absent key)
+    given: Dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Key=label, Value=extracted value or null. "
+            "null means unclear, NOT missing from the problem."
+        ),
+        examples=[
+            {"A": [0, 1], "D": [0, 9], "radius": None},
+            {"equation": "x^2 - 5x + 6 = 0", "domain": None},
+        ],
+    )
+
+    # ── What the question asks to find ──────────────────────────────────
+    find: List[str] = Field(
+        default_factory=list,
+        description="What the question explicitly asks to calculate or prove.",
+        examples=[["center of circle", "radius"], ["roots of equation"]],
+    )
+
+    # ── Verbal constraints (from text / diagram labels) ─────────────────
+    constraints: List[str] = Field(
+        default_factory=list,
+        examples=[["AD is a diameter", "M is the center of the circle"]],
+    )
+
+    # ── Populated ONLY by the Verifier ──────────────────────────────────
+    verified: Dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Algebraically proven values. "
+            "These are Ground Truth — the LLM must not re-derive them."
+        ),
+    )
+
+    # ── Pipeline status ─────────────────────────────────────────────────
+    verification_status: Literal[
+        "verified",        # all `find` targets are algebraically confirmed
+        "partial",         # some targets verified, others not
+        "contradiction",   # algebraic result contradicts extracted data
+        "insufficient_data",  # too many null fields to verify
+        "pending",         # default before Verifier runs
+    ] = "pending"
+
+    warnings: List[str] = Field(
+        default_factory=list,
+        description="Non-fatal issues: OCR gaps, null substitutions, etc.",
+    )
+
+    class Config:
+        # Allow None values in `given` dict (explicit null support)
+        arbitrary_types_allowed = True
+
+    def null_fields(self) -> List[str]:
+        """Returns list of keys in `given` that are explicitly null."""
+        return [k for k, v in self.given.items() if v is None]
+
+    def is_ready_to_verify(self) -> bool:
+        """True if no critical null fields block verification."""
+        # Verifier can still run on partial data; it will set status accordingly
+        return True  # Always try; Verifier decides the status

backend/pipeline.py

@@ -0,0 +1,102 @@
+# backend/pipeline.py
+# BuddyMath V2.0 — Task 5: Pipeline Integration
+#
+# The full pipeline: OCR → EXTRACT → VERIFY → PIN → LLM
+# All 4 stages are logged to console for every question.
+#
+# RED LINES (from spec):
+# - Never deploy without logs from all pipeline stages.
+# - The Solver is the existing LLM; this module only prepares its input.
+# ─────────────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Optional
+
+from backend.extractor import Extractor
+from backend.math_schema import MathProblemSchema
+from backend.universal_verifier import UniversalVerifier
+from backend.variable_pinner import VariablePinner
+
+logger = logging.getLogger(__name__)
+
+# Singletons — instantiated once, reused across requests
+_extractor = Extractor()
+_verifier = UniversalVerifier()
+_pinner = VariablePinner()
+
+
+@dataclass
+class PipelineResult:
+    """The complete output of one pipeline run, ready for the LLM."""
+    schema: MathProblemSchema
+    pin_block: str          # inject this into the LLM prompt
+    stage_log: list[str] = field(default_factory=list)
+
+
+def run_v2_pipeline(
+    problem_text: str,
+    image_data: Optional[bytes] = None,
+) -> PipelineResult:
+    """
+    Execute the full V2.0 Truth-Anchor pipeline.
+
+    Args:
+        problem_text: The math problem as plain text (post-OCR or raw).
+        image_data:   Optional raw image bytes for OCR-aware extraction.
+
+    Returns:
+        PipelineResult with schema, pin_block, and stage_log.
+
+    Spec requirement:
+        Console log must show all 4 stages for every question.
+    """
+    log: list[str] = []
+
+    def _log(stage: int, name: str, detail: str) -> None:
+        msg = f"[PIPELINE] Stage {stage}/4 — {name}: {detail}"
+        log.append(msg)
+        logger.info(msg)
+
+    # ── Stage 1: OCR (already done upstream; we receive problem_text) ──
+    _log(1, "OCR/INPUT", f"Received problem ({len(problem_text)} chars, image={'yes' if image_data else 'no'})")
+
+    # ── Stage 2: EXTRACT ──────────────────────────────────────────────
+    schema = _extractor.extract(problem_text, image_data=image_data)
+    null_fields = schema.null_fields()
+    _log(
+        2, "EXTRACT",
+        f"type={schema.problem_type}/{schema.sub_type} | given={list(schema.given.keys())} | "
+        f"nulls={null_fields or 'none'} | find={schema.find}"
+    )
+
+    # ── Stage 3: VERIFY ───────────────────────────────────────────────
+    schema = _verifier.verify(schema)
+    _log(
+        3, "VERIFY",
+        f"status={schema.verification_status} | verified={list(schema.verified.keys())} | "
+        f"warnings={len(schema.warnings)}"
+    )
+    if schema.warnings:
+        for w in schema.warnings:
+            logger.warning("[PIPELINE] ⚠️  %s", w)
+
+    # ── Stage 4: PIN ──────────────────────────────────────────────────
+    pin_block = _pinner.build_pin_block(schema)
+    _log(
+        4, "PIN",
+        f"pin_block_len={len(pin_block)} chars | status={schema.verification_status}"
+    )
+
+    # ── Summary log ───────────────────────────────────────────────────
+    logger.info(
+        "✅ [PIPELINE] Complete — %s | null=%s | pinned=%s | status=%s",
+        f"{schema.problem_type}/{schema.sub_type}",
+        null_fields or "none",
+        list(schema.verified.keys()),
+        schema.verification_status,
+    )
+
+    return PipelineResult(schema=schema, pin_block=pin_block, stage_log=log)

backend/tests/test_pipeline.py

@@ -0,0 +1,397 @@
+# backend/tests/test_pipeline.py
+# BuddyMath V2.0 — Acceptance Tests (v2 — Post Priority Fix)
+#
+# CRITICAL RULE (from review):
+# M=(0,5) via midpoint of chord AD is the HALLUCINATION we are preventing.
+# M=(3,5) via intersection of diameter lines is the ONLY correct answer.
+#
+# Run with: python -m pytest backend/tests/test_pipeline.py -v
+# ─────────────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+import logging
+import sys
+import os
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(__file__))))
+
+from backend.math_schema import MathProblemSchema
+from backend.universal_verifier import UniversalVerifier
+from backend.variable_pinner import VariablePinner
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+verifier = UniversalVerifier()
+pinner = VariablePinner()
+
+
+# ============================================================
+# Task 2/3: Verifier robustness — always returns valid schema
+# ============================================================
+class TestVerifierRobustness(unittest.TestCase):
+
+    def test_circle_insufficient_data(self):
+        """All-null geometry → insufficient_data, never crashes."""
+        schema = MathProblemSchema(
+            problem_type="geometry",
+            sub_type="circle",
+            given={"A": None, "D": None, "radius": None},
+            find=["center of circle"],
+            constraints=["AD is a diameter"],
+        )
+        result = verifier.verify(schema)
+        self.assertIn(result.verification_status,
+                      ["insufficient_data", "partial", "contradiction"])
+        self.assertIsInstance(result.warnings, list)
+
+    def test_circle_chord_midpoint_fallback(self):
+        """
+        FALLBACK ONLY test: A(0,1), D(0,9) named as diameter chord (no lines given).
+        Result must be M=(0.0, 5.0).
+        NOTE: This is the CORRECT result for this specific input.
+              It is WRONG to use midpoint when diameter lines are also available.
+        """
+        schema = MathProblemSchema(
+            problem_type="geometry",
+            sub_type="circle",
+            given={"A": [0, 1], "D": [0, 9]},
+            find=["center of circle", "radius"],
+            constraints=["AD is a diameter"],
+        )
+        result = verifier.verify(schema)
+        # Chord midpoint fallback is always partial — center is unconfirmed without line eqs
+        self.assertEqual(result.verification_status, "partial")
+        center = result.verified.get("center")
+        self.assertIsNotNone(center, "Center must be in verified")
+        self.assertAlmostEqual(center[0], 0.0, places=4)
+        self.assertAlmostEqual(center[1], 5.0, places=4)
+        self.assertAlmostEqual(result.verified.get("radius"), 4.0, places=4)
+        self.assertEqual(result.verified.get("verification_method"), "chord_midpoint_fallback")
+
+    def test_algebra_insufficient_data(self):
+        schema = MathProblemSchema(
+            problem_type="algebra",
+            sub_type="quadratic",
+            given={"equation": None},
+            find=["roots"],
+            constraints=[],
+        )
+        result = verifier.verify(schema)
+        self.assertEqual(result.verification_status, "insufficient_data")
+
+    def test_algebra_quadratic(self):
+        schema = MathProblemSchema(
+            problem_type="algebra",
+            sub_type="quadratic",
+            given={"equation": "x**2 - 5*x + 6"},
+            find=["roots"],
+            constraints=[],
+        )
+        result = verifier.verify(schema)
+        self.assertEqual(result.verification_status, "verified")
+        solutions = result.verified.get("solutions", [])
+        self.assertIn("2", solutions)
+        self.assertIn("3", solutions)
+
+    def test_probability_sum_to_one(self):
+        schema = MathProblemSchema(
+            problem_type="probability",
+            sub_type="basic",
+            given={"probabilities": [0.2, 0.3, 0.5]},
+            find=["verify distribution"],
+            constraints=[],
+        )
+        result = verifier.verify(schema)
+        self.assertEqual(result.verification_status, "verified")
+
+    def test_probability_contradiction(self):
+        schema = MathProblemSchema(
+            problem_type="probability",
+            sub_type="basic",
+            given={"probabilities": [0.5, 0.6]},
+            find=["verify distribution"],
+            constraints=[],
+        )
+        result = verifier.verify(schema)
+        self.assertEqual(result.verification_status, "contradiction")
+
+    def test_statistics_verified(self):
+        schema = MathProblemSchema(
+            problem_type="statistics",
+            sub_type="descriptive",
+            given={"data": [2, 4, 6]},
+            find=["mean"],
+            constraints=[],
+        )
+        result = verifier.verify(schema)
+        self.assertAlmostEqual(result.verified.get("mean"), 4.0, places=4)
+
+    def test_calculus_derivative(self):
+        schema = MathProblemSchema(
+            problem_type="calculus",
+            sub_type="differentiation",
+            given={"function": "x**2", "point": 3},
+            find=["derivative at x=3"],
+            constraints=[],
+        )
+        result = verifier.verify(schema)
+        self.assertAlmostEqual(result.verified.get("derivative_at_point"), 6.0, places=4)
+
+
+# ============================================================
+# THE KEY TEST — Task 4 "M=3,5" Acceptance Criterion
+# ============================================================
+class TestDiameterLineIntersection(unittest.TestCase):
+    """
+    This is THE acceptance test.
+
+    Problem: A(0,1), D(0,9)
+    Two diameters: y = 4/3*x + 1  and  y = -4/3*x + 9
+    Algebraic intersection: x=3, y=5 → M=(3,5)
+
+    ❌ WRONG (hallucination): M=(0,5) — midpoint of chord AD
+    ✅ CORRECT (algebraic):   M=(3,5) — intersection of diameter lines
+    """
+
+    def _make_schema(self) -> MathProblemSchema:
+        return MathProblemSchema(
+            problem_type="geometry",
+            sub_type="circle",
+            given={
+                "A": [0, 1],
+                "D": [0, 9],
+                "diameter_lines": ["y=4/3*x+1", "y=-4/3*x+9"],
+            },
+            find=["center of circle M"],
+            constraints=["AC and DB are diameters", "M is the center"],
+        )
+
+    def test_center_is_3_5_not_0_5(self):
+        """
+        ACCEPTANCE TEST: M must be (3,5) — intersection of diameters.
+        M=(0,5) means the verifier used midpoint of chord AD. This is the hallucination.
+        """
+        schema = self._make_schema()
+        result = verifier.verify(schema)
+
+        M = result.verified.get("M")
+        self.assertIsNotNone(M, "M must be in verified dict")
+        self.assertAlmostEqual(M[0], 3.0, places=4,
+                               msg=f"M.x should be 3.0 (got {M[0]}) — midpoint fallback not allowed here")
+        self.assertAlmostEqual(M[1], 5.0, places=4,
+                               msg=f"M.y should be 5.0 (got {M[1]})")
+
+        # Explicitly assert the WRONG answer doesn't appear
+        self.assertFalse(
+            abs(M[0] - 0.0) < 0.01 and abs(M[1] - 5.0) < 0.01,
+            "CRITICAL FAILURE: M=(0,5) detected — this is the chord midpoint hallucination!"
+        )
+
+    def test_center_method_is_line_intersection(self):
+        """Verify the method field is set correctly."""
+        schema = self._make_schema()
+        result = verifier.verify(schema)
+        method = result.verified.get("center_method")
+        self.assertEqual(method, "diameter_line_intersection")
+
+    def test_verification_status_is_verified(self):
+        schema = self._make_schema()
+        result = verifier.verify(schema)
+        self.assertIn(result.verification_status, ["verified", "partial"])
+
+    def test_pin_block_contains_correct_center(self):
+        """The PIN block must show M=(3.0, 5.0), not (0.0, 5.0)."""
+        schema = self._make_schema()
+        result = verifier.verify(schema)
+        block = pinner.build_pin_block(result)
+
+        self.assertIn("GROUND TRUTH", block)
+        self.assertIn("3.0", block, "Pin block must contain x=3.0 for center M")
+        self.assertIn("5.0", block, "Pin block must contain y=5.0 for center M")
+
+    def test_pin_block_aggressive_on_contradiction(self):
+        """Pin block flags CONTRADICTION when center_method = chord_midpoint with lines available."""
+        schema = MathProblemSchema(
+            problem_type="geometry",
+            sub_type="circle",
+            given={
+                "A": [0, 1],
+                "D": [0, 9],
+                "diameter_lines": ["y=4/3*x+1", "y=-4/3*x+9"],
+            },
+            find=["center"],
+            constraints=["AC and DB are diameters"],
+            # Simulate the hallucination being injected from outside
+            verified={"M": (0.0, 5.0), "center_method": "diameter_chord_midpoint"},
+            verification_status="contradiction",
+            warnings=["CRITICAL CONTRADICTION: LLM assumed M(0,5) from chord, correct is M(3,5)"],
+        )
+        block = pinner.build_pin_block(schema)
+        self.assertIn("CONTRADICTION", block)
+
+
+# ============================================================
+# Task 4: Pin block structure
+# ============================================================
+class TestVariablePinner(unittest.TestCase):
+
+    def test_pin_block_contains_ground_truth_header(self):
+        schema = MathProblemSchema(
+            problem_type="geometry",
+            sub_type="circle",
+            given={"A": [0, 1], "D": [0, 9]},
+            find=["center"],
+            constraints=["AD is a diameter"],
+            verified={"center": (0.0, 5.0), "radius": 4.0},
+            verification_status="verified",
+        )
+        block = pinner.build_pin_block(schema)
+        self.assertIn("GROUND TRUTH", block)
+        self.assertIn("center", block)
+        self.assertIn("radius", block)
+
+    def test_pin_block_null_warning(self):
+        schema = MathProblemSchema(
+            problem_type="geometry",
+            sub_type="circle",
+            given={"radius": None},
+            find=["center"],
+            constraints=[],
+            verification_status="insufficient_data",
+        )
+        block = pinner.build_pin_block(schema)
+        self.assertIn("INSUFFICIENT_DATA", block)
+        self.assertIn("radius", block)
+
+    def test_pin_block_contradiction_warning(self):
+        schema = MathProblemSchema(
+            problem_type="algebra",
+            sub_type="quadratic",
+            given={"equation": "x**2 - 5*x + 6", "solution": 99},
+            find=["roots"],
+            constraints=[],
+            verification_status="contradiction",
+        )
+        block = pinner.build_pin_block(schema)
+        self.assertIn("CONTRADICTION", block)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)
+
+
+# ============================================================
+# Phase C — 5-Domain Acceptance Suite
+# Each test verifies: (1) correct result, (2) verification_method field
+# ============================================================
+class TestPhaseCDomainCoverage(unittest.TestCase):
+    """
+    Phase C acceptance criterion:
+    Each domain must report WHAT was verified AND HOW (verification_method).
+    5 exam-style exercises, one per remaining domain.
+    """
+
+    # 🔴 ALGEBRA: substitution into original equation
+    def test_algebra_cubic_roots_and_method(self):
+        """x^3 - 6x^2 + 11x - 6 = 0 → roots [1, 2, 3]"""
+        schema = MathProblemSchema(
+            problem_type="algebra",
+            sub_type="cubic",
+            given={"equation": "x**3 - 6*x**2 + 11*x - 6"},
+            find=["roots"],
+            constraints=[],
+        )
+        result = verifier.verify(schema)
+        self.assertEqual(result.verification_status, "verified")
+        solutions = result.verified.get("solutions", [])
+        self.assertIn("1", solutions)
+        self.assertIn("2", solutions)
+        self.assertIn("3", solutions)
+        self.assertEqual(result.verified.get("verification_method"), "sympy_solve_substitution")
+        print(f"  [algebra] method={result.verified.get('verification_method')}")
+
+    # 🔴 GEOMETRY: diameter line intersection (already covered, here as Phase C entry)
+    def test_geometry_circle_diameter_intersection_and_method(self):
+        """y=2x+1 ∩ y=-2x+9 → center (2, 5)"""
+        schema = MathProblemSchema(
+            problem_type="geometry",
+            sub_type="circle",
+            given={"diameter_lines": ["y=2*x+1", "y=-2*x+9"]},
+            find=["center"],
+            constraints=["given lines are diameters"],
+        )
+        result = verifier.verify(schema)
+        self.assertIn(result.verification_status, ["verified", "partial"])
+        M = result.verified.get("M")
+        self.assertIsNotNone(M)
+        self.assertAlmostEqual(M[0], 2.0, places=3)
+        self.assertAlmostEqual(M[1], 5.0, places=3)
+        self.assertEqual(result.verified.get("verification_method"), "diameter_line_intersection")
+        print(f"  [geometry] M={M} method={result.verified.get('verification_method')}")
+
+    # 🟡 PROBABILITY: sum-to-1 check
+    def test_probability_three_event_distribution_and_method(self):
+        """P(A)=1/3, P(B)=1/2, P(C)=1/6 → sum=1"""
+        schema = MathProblemSchema(
+            problem_type="probability",
+            sub_type="discrete_distribution",
+            given={"probabilities": ["1/3", "1/2", "1/6"]},
+            find=["verify distribution is valid"],
+            constraints=["A, B, C are mutually exclusive and exhaustive"],
+        )
+        result = verifier.verify(schema)
+        self.assertEqual(result.verification_status, "verified")
+        self.assertAlmostEqual(result.verified.get("sum"), 1.0, places=9)
+        self.assertEqual(result.verified.get("verification_method"), "sympy_rational_sum")
+        print(f"  [probability] sum={result.verified.get('sum')} method={result.verified.get('verification_method')}")
+
+    # 🟡 STATISTICS: mean and std via NumPy
+    def test_statistics_exam_scores_and_method(self):
+        """Scores [70, 80, 90, 100] → mean=85, std=11.18"""
+        schema = MathProblemSchema(
+            problem_type="statistics",
+            sub_type="descriptive",
+            given={"data": [70, 80, 90, 100]},
+            find=["mean", "standard deviation"],
+            constraints=[],
+        )
+        result = verifier.verify(schema)
+        self.assertEqual(result.verification_status, "verified")
+        self.assertAlmostEqual(result.verified.get("mean"), 85.0, places=4)
+        self.assertAlmostEqual(result.verified.get("std"), 11.1803, places=3)
+        self.assertEqual(result.verified.get("verification_method"), "numpy_population_stats")
+        print(f"  [statistics] mean={result.verified.get('mean')} method={result.verified.get('verification_method')}")
+
+    # 🟢 CALCULUS: derivative at a point
+    def test_calculus_polynomial_derivative_and_method(self):
+        """f(x) = x^3 - 4x → f'(2) = 3*4 - 4 = 8"""
+        schema = MathProblemSchema(
+            problem_type="calculus",
+            sub_type="differentiation",
+            given={"function": "x**3 - 4*x", "point": 2},
+            find=["derivative at x=2"],
+            constraints=[],
+        )
+        result = verifier.verify(schema)
+        self.assertEqual(result.verification_status, "verified")
+        self.assertAlmostEqual(result.verified.get("derivative_at_point"), 8.0, places=4)
+        self.assertEqual(result.verified.get("verification_method"), "sympy_differentiation")
+        print(f"  [calculus] f'(2)={result.verified.get('derivative_at_point')} method={result.verified.get('verification_method')}")
+
+    # 🟢 TRIGONOMETRY: identity verification
+    def test_trigonometry_pythagorean_identity_and_method(self):
+        """sin(x)**2 + cos(x)**2 = 1 → must simplify to 0 symbolically"""
+        schema = MathProblemSchema(
+            problem_type="trigonometry",
+            sub_type="identity",
+            given={"identity": "sin(x)**2 + cos(x)**2 = 1"},
+            find=["verify Pythagorean identity"],
+            constraints=[],
+        )
+        result = verifier.verify(schema)
+        self.assertEqual(result.verification_status, "verified")
+        self.assertTrue(result.verified.get("identity_valid"))
+        self.assertEqual(result.verified.get("verification_method"), "sympy_symbolic_simplification")
+        print(f"  [trig] identity_valid={result.verified.get('identity_valid')} method={result.verified.get('verification_method')}")

backend/universal_verifier.py

@@ -0,0 +1,480 @@
+# backend/universal_verifier.py
+# BuddyMath V2.0 — Stage 2: SymPy-based Universal Verifier
+#
+# PRIORITY ORDER FOR CIRCLE CENTER (non-negotiable):
+# 1. diameter_lines in given → center = algebraic intersection (ALWAYS preferred)
+# 2. Midpoint of named diameter chord → FALLBACK ONLY (no lines available)
+#
+# A chord midpoint is NOT a center unless it is proven to be a diameter.
+# If diameter line equations exist, they override ALL midpoint calculations.
+# ─────────────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+import sympy as sp
+
+from backend.math_schema import MathProblemSchema
+
+logger = logging.getLogger(__name__)
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────
+def _to_point(value: Any) -> Optional[sp.Point2D]:
+    """Convert [x, y] list → sympy.Point2D, or None if invalid."""
+    if isinstance(value, (list, tuple)) and len(value) == 2:
+        try:
+            return sp.Point2D(sp.Rational(value[0]), sp.Rational(value[1]))
+        except Exception:
+            pass
+    return None
+
+
+def _to_rational(value: Any) -> Optional[sp.Rational]:
+    """Convert numeric value → sympy.Rational, or None."""
+    if value is None:
+        return None
+    try:
+        return sp.Rational(value)
+    except Exception:
+        return None
+
+
+# ── Domain dispatchers ────────────────────────────────────────────────────
+class UniversalVerifier:
+    """
+    Routes a MathProblemSchema to the appropriate domain verifier.
+    Guaranteed to never raise an exception to the caller.
+    """
+
+    _DISPATCH: Dict[str, str] = {
+        "geometry":     "_verify_geometry",
+        "algebra":      "_verify_algebra",
+        "probability":  "_verify_probability",
+        "statistics":   "_verify_statistics",
+        "trigonometry": "_verify_trigonometry",
+        "calculus":     "_verify_calculus",
+    }
+
+    def verify(self, schema: MathProblemSchema) -> MathProblemSchema:
+        """Entry point. Always returns a valid schema."""
+        logger.info(
+            "🔍 [VERIFIER] Starting. type=%s/%s | find=%s",
+            schema.problem_type, schema.sub_type, schema.find,
+        )
+        null_keys = schema.null_fields()
+        if null_keys:
+            logger.warning("⚠️  [VERIFIER] Null fields: %s", null_keys)
+
+        try:
+            method_name = self._DISPATCH.get(schema.problem_type)
+            if method_name:
+                getattr(self, method_name)(schema)
+            else:
+                schema.warnings.append(f"No verifier for problem_type='{schema.problem_type}'")
+                schema.verification_status = "partial"
+        except Exception as e:
+            logger.error("❌ [VERIFIER] Unexpected error: %s", e)
+            schema.warnings.append(f"Verifier internal error: {e}")
+            schema.verification_status = "partial"
+
+        logger.info(
+            "✅ [VERIFIER] Done. status=%s | verified=%s | warnings=%d",
+            schema.verification_status,
+            list(schema.verified.keys()),
+            len(schema.warnings),
+        )
+        return schema
+
+    # ── GEOMETRY ─────────────────────────────────────────────────────────
+    def _verify_geometry(self, schema: MathProblemSchema) -> None:
+        g = schema.given
+        verified = {}
+        sub = schema.sub_type.lower()
+        if "circle" in sub:
+            self._verify_circle(schema, g, verified)
+        elif any(k in sub for k in ("line", "linear", "segment")):
+            self._verify_linear(schema, g, verified)
+        else:
+            schema.warnings.append(f"No geometry handler for sub_type='{schema.sub_type}'")
+            schema.verification_status = "partial"
+
+    def _verify_circle(self, schema: MathProblemSchema, g: dict, verified: dict) -> None:
+        """
+        PRIORITY 1: diameter_lines → center = algebraic intersection.
+        PRIORITY 2: diameter chord → midpoint (only if no lines given).
+        """
+        import re as _re
+
+        # ═══════════════════════════════════════════════════════════════
+        # PRIORITY 1: Diameter line equations — MANDATORY if present
+        # ═════════════════════════════════════════════════════��═════════
+        diameter_lines = g.get("diameter_lines")
+        if diameter_lines and len(diameter_lines) >= 2:
+            logger.info(
+                "🔑 [VERIFIER/circle] diameter_lines detected — using intersection method"
+            )
+            center, method = _find_center_from_diameter_lines(diameter_lines, schema)
+            if center is not None:
+                cx, cy = float(center.x), float(center.y)
+                verified["M"] = (cx, cy)
+                verified["center"] = (cx, cy)
+                verified["center_method"] = "diameter_line_intersection"
+                verified["verification_method"] = "diameter_line_intersection"
+                schema.verified.update(verified)
+                logger.info(
+                    "✅ [VERIFIER/circle] M = (%s, %s) via %s (method=diameter_line_intersection)",
+                    cx, cy, method,
+                )
+
+                # Verify radius from a known point
+                _compute_radius_from_center(g, center, verified, schema)
+                schema.verified.update(verified)
+
+                # Cross-check if radius also given
+                given_r = g.get("radius")
+                if given_r and "radius" in verified:
+                    if abs(float(given_r) - verified["radius"]) > 1e-6:
+                        schema.warnings.append(
+                            f"CONTRADICTION: given radius={given_r} vs "
+                            f"computed={verified['radius']:.4f}"
+                        )
+                        schema.verification_status = "contradiction"
+                        return
+
+                schema.verification_status = "partial" if schema.null_fields() else "verified"
+                return
+            else:
+                schema.warnings.append(
+                    f"diameter_lines parsing/solve failed: {method} — falling back to chord"
+                )
+
+        # ═══════════════════════════════════════════════════════════════
+        # PRIORITY 2: Midpoint of diameter chord (FALLBACK)
+        # ═══════════════════════════════════════════════════════════════
+        points = {}
+        for k, v in g.items():
+            if v is None:
+                continue
+            p = _to_point(v)
+            if p:
+                points[k] = p
+
+        radius_raw = g.get("radius")
+        radius = _to_rational(radius_raw)
+
+        diameter_pairs: List[Tuple[str, str]] = []
+        has_diameter_constraint = False
+        for c in schema.constraints:
+            if "diameter" in c.lower():
+                has_diameter_constraint = True
+                labels = _re.findall(r"\b([A-Za-z]{1,2})\b", c)
+                matched = [lbl for lbl in labels if lbl in points]
+                if len(matched) >= 2:
+                    diameter_pairs.append((matched[0], matched[1]))
+
+        # Auto-pick first 2 points if labels ambiguous
+        if not diameter_pairs and has_diameter_constraint and len(points) >= 2:
+            keys = list(points.keys())
+            diameter_pairs.append((keys[0], keys[1]))
+            logger.info(
+                "📐 [VERIFIER/circle/fallback] Using points %s, %s as diameter chord",
+                keys[0], keys[1],
+            )
+
+        if not diameter_pairs:
+            msg = "No diameter_lines and no named diameter chord — insufficient data"
+            schema.warnings.append(msg)
+            schema.verification_status = "insufficient_data"
+            return
+
+        for p1_label, p2_label in diameter_pairs:
+            p1, p2 = points[p1_label], points[p2_label]
+            cx = (p1.x + p2.x) / 2
+            cy = (p1.y + p2.y) / 2
+            center = sp.Point2D(cx, cy)
+            computed_radius = p1.distance(p2) / 2
+
+            verified["center"] = (float(cx), float(cy))
+            verified["M"] = (float(cx), float(cy))
+            verified["radius"] = float(computed_radius)
+            verified["center_method"] = "chord_midpoint_fallback"
+            verified["verification_method"] = "chord_midpoint_fallback"
+            schema.verified.update(verified)
+
+            logger.info(
+                "📐 [VERIFIER/circle/fallback] midpoint(%s,%s) → center=%s radius=%s [FALLBACK — status=partial]",
+                p1_label, p2_label, center, computed_radius,
+            )
+
+            if radius is not None and abs(float(computed_radius) - float(radius)) > 1e-6:
+                msg = (
+                    f"CONTRADICTION: given radius={radius_raw} but "
+                    f"computed from chord {p1_label}{p2_label}={float(computed_radius):.4f}"
+                )
+                schema.warnings.append(msg)
+                logger.error("🚨 [VERIFIER/circle] %s", msg)
+                schema.verification_status = "contradiction"
+                return
+
+            for label, pt in points.items():
+                if label in (p1_label, p2_label):
+                    continue
+                dist = float(pt.distance(center))
+                r = float(computed_radius)
+                if abs(dist - r) < 1e-6:
+                    verified[f"{label}_on_circle"] = True
+                else:
+                    schema.warnings.append(
+                        f"Point {label} NOT on circle (dist={dist:.4f}, r={r:.4f})"
+                    )
+
+        schema.verified.update(verified)
+        # Chord midpoint fallback is always partial — center is unconfirmed without lines
+        if schema.verified.get("center_method") == "chord_midpoint_fallback":
+            schema.verification_status = "partial"
+        else:
+            schema.verification_status = "partial" if schema.null_fields() else "verified"
+
+    def _verify_linear(self, schema: MathProblemSchema, g: dict, verified: dict) -> None:
+        schema.warnings.append("Linear geometry verifier: basic — extend as needed")
+        schema.verification_status = "partial"
+
+    # ── ALGEBRA ──────────────────────────────────────────────────────────
+    def _verify_algebra(self, schema: MathProblemSchema) -> None:
+        g = schema.given
+        verified = schema.verified
+        equation_str = g.get("equation")
+        if equation_str is None:
+            schema.warnings.append("Algebra: 'equation' is null")
+            schema.verification_status = "insufficient_data"
+            return
+        try:
+            if "=" in str(equation_str):
+                lhs_s, rhs_s = str(equation_str).split("=", 1)
+                x = sp.Symbol("x")
+                expr = sp.sympify(lhs_s.strip()) - sp.sympify(rhs_s.strip())
+            else:
+                x = sp.Symbol("x")
+                expr = sp.sympify(str(equation_str))
+            solutions = sp.solve(expr, x)
+            verified["solutions"] = [str(s) for s in solutions]
+            verified["verification_method"] = "sympy_solve_substitution"
+            logger.info("📐 [VERIFIER/algebra] Solutions: %s (method=sympy_solve_substitution)", solutions)
+            given_solution = g.get("solution")
+            if given_solution is not None:
+                given_val = sp.Rational(given_solution)
+                if given_val not in solutions:
+                    schema.warnings.append(
+                        f"CONTRADICTION: given solution={given_solution} not in {solutions}"
+                    )
+                    schema.verification_status = "contradiction"
+                    return
+            schema.verification_status = "partial" if schema.null_fields() else "verified"
+        except Exception as e:
+            schema.warnings.append(f"Algebra verifier error: {e}")
+            schema.verification_status = "partial"
+
+    # ── PROBABILITY ───────────────────────────────────────────────────────
+    def _verify_probability(self, schema: MathProblemSchema) -> None:
+        g = schema.given
+        verified = schema.verified
+        probs = g.get("probabilities")
+        if probs is None:
+            schema.warnings.append("Probability: 'probabilities' is null")
+            schema.verification_status = "insufficient_data"
+            return
+        try:
+            total = sum(sp.Rational(str(p)) for p in probs)
+            verified["sum"] = float(total)
+            verified["verification_method"] = "sympy_rational_sum"
+            logger.info("📐 [VERIFIER/probability] sum=%s (method=sympy_rational_sum)", float(total))
+            if total != 1:
+                schema.warnings.append(
+                    f"CONTRADICTION: probabilities sum to {float(total):.4f}, not 1.0"
+                )
+                schema.verification_status = "contradiction"
+            else:
+                schema.verification_status = "verified"
+        except Exception as e:
+            schema.warnings.append(f"Probability verifier error: {e}")
+            schema.verification_status = "partial"
+
+    # ── STATISTICS ────────────────────────────────────────────────────────
+    def _verify_statistics(self, schema: MathProblemSchema) -> None:
+        import numpy as np
+        g = schema.given
+        verified = schema.verified
+        data = g.get("data")
+        if data is None:
+            schema.warnings.append("Statistics: 'data' is null")
+            schema.verification_status = "insufficient_data"
+            return
+        try:
+            arr = np.array([float(x) for x in data])
+            verified["mean"] = float(np.mean(arr))
+            verified["std"] = float(np.std(arr, ddof=0))
+            verified["verification_method"] = "numpy_population_stats"
+            logger.info(
+                "📐 [VERIFIER/statistics] mean=%.4f std=%.4f (method=numpy_population_stats)",
+                verified["mean"], verified["std"],
+            )
+            for key in ("mean", "std"):
+                given_val = g.get(key)
+                if given_val is not None and abs(float(given_val) - verified[key]) > 1e-6:
+                    schema.warnings.append(
+                        f"CONTRADICTION: given {key}={given_val} vs computed={verified[key]:.6f}"
+                    )
+                    schema.verification_status = "contradiction"
+                    return
+            schema.verification_status = "verified"
+        except Exception as e:
+            schema.warnings.append(f"Statistics verifier error: {e}")
+            schema.verification_status = "partial"
+
+    # ── TRIGONOMETRY ──────────────────────────────────────────────────────
+    def _verify_trigonometry(self, schema: MathProblemSchema) -> None:
+        g = schema.given
+        verified = schema.verified
+        identity = g.get("identity")
+        angle_deg = g.get("angle_deg")
+        if identity is None:
+            schema.warnings.append("Trigonometry: 'identity' is null")
+            schema.verification_status = "insufficient_data"
+            return
+        try:
+            theta = sp.Symbol("theta")
+            lhs_s, rhs_s = str(identity).split("=", 1)
+            lhs = sp.sympify(lhs_s.strip())
+            rhs = sp.sympify(rhs_s.strip())
+            diff = sp.simplify(lhs - rhs)
+            if diff == 0:
+                verified["identity_valid"] = True
+                verified["verification_method"] = "sympy_symbolic_simplification"
+                logger.info("✅ [VERIFIER/trig] Identity valid (method=sympy_symbolic_simplification)")
+                schema.verification_status = "verified"
+            elif angle_deg is not None:
+                angle_rad = sp.Rational(angle_deg) * sp.pi / 180
+                val = float(diff.subs(theta, angle_rad))
+                verified["identity_at_angle"] = (abs(val) < 1e-9)
+                schema.verification_status = "partial" if abs(val) < 1e-9 else "contradiction"
+            else:
+                schema.warnings.append("Trig identity could not be simplified to zero")
+                schema.verification_status = "partial"
+        except Exception as e:
+            schema.warnings.append(f"Trigonometry verifier error: {e}")
+            schema.verification_status = "partial"
+
+    # ── CALCULUS ──────────────────────────────────────────────────────────
+    def _verify_calculus(self, schema: MathProblemSchema) -> None:
+        g = schema.given
+        verified = schema.verified
+        func_str = g.get("function")
+        point_raw = g.get("point")
+        if func_str is None:
+            schema.warnings.append("Calculus: 'function' is null")
+            schema.verification_status = "insufficient_data"
+            return
+        try:
+            x = sp.Symbol("x")
+            f = sp.sympify(str(func_str))
+            deriv = sp.diff(f, x)
+            verified["derivative"] = str(deriv)
+            verified["verification_method"] = "sympy_differentiation"
+            logger.info("📐 [VERIFIER/calculus] f'(x)=%s (method=sympy_differentiation)", deriv)
+            if point_raw is not None:
+                pt = _to_rational(point_raw)
+                val = float(deriv.subs(x, pt))
+                verified["derivative_at_point"] = val
+                given_dv = g.get("derivative_at_point")
+                if given_dv is not None and abs(float(given_dv) - val) > 1e-9:
+                    schema.warnings.append(
+                        f"CONTRADICTION: given f'({point_raw})={given_dv} vs computed={val:.6f}"
+                    )
+                    schema.verification_status = "contradiction"
+                    return
+            schema.verification_status = "verified"
+        except Exception as e:
+            schema.warnings.append(f"Calculus verifier error: {e}")
+            schema.verification_status = "partial"
+
+
+# ── Module-level helpers ──────────────────────────────────────────────────
+def _find_center_from_diameter_lines(
+    diameter_lines: list,
+    schema: "MathProblemSchema",
+) -> Tuple[Optional[sp.Point2D], str]:
+    """
+    Solve the intersection of two diameter line equations.
+    Returns (sp.Point2D, description) or (None, reason).
+    """
+    if len(diameter_lines) < 2:
+        return None, "need at least 2 diameter lines"
+
+    x, y = sp.symbols("x y")
+
+    def _parse_line(eq_str: str) -> Optional[sp.Eq]:
+        eq_str = str(eq_str).strip().replace(" ", "")
+        if "=" not in eq_str:
+            return None
+        lhs_s, rhs_s = eq_str.split("=", 1)
+        try:
+            return sp.Eq(sp.sympify(lhs_s), sp.sympify(rhs_s))
+        except Exception as e:
+            logger.error("❌ [VERIFIER/diameters] Cannot parse '%s': %s", eq_str, e)
+            return None
+
+    eq1 = _parse_line(diameter_lines[0])
+    eq2 = _parse_line(diameter_lines[1])
+
+    if eq1 is None or eq2 is None:
+        return None, "line parsing failed"
+
+    logger.info(
+        "📐 [VERIFIER/diameters] Solving:\n  L1=%s\n  L2=%s", eq1, eq2
+    )
+
+    try:
+        sol = sp.solve([eq1, eq2], [x, y])
+        if not sol:
+            schema.warnings.append("Diameter lines are parallel — no intersection")
+            return None, "parallel lines"
+
+        if isinstance(sol, dict):
+            cx, cy = sol[x], sol[y]
+        elif isinstance(sol, (list, tuple)) and sol:
+            first = sol[0]
+            cx, cy = first[0], first[1]
+        else:
+            return None, "unexpected solution format"
+
+        center = sp.Point2D(cx, cy)
+        logger.info("✅ [VERIFIER/diameters] Center = (%s, %s)", cx, cy)
+        return center, f"intersection of {diameter_lines[0]} ∩ {diameter_lines[1]}"
+
+    except Exception as e:
+        logger.error("❌ [VERIFIER/diameters] Solve error: %s", e)
+        return None, f"solve error: {e}"
+
+
+def _compute_radius_from_center(
+    g: dict, center: sp.Point2D, verified: dict, schema: "MathProblemSchema"
+) -> None:
+    """Compute radius as distance from center to the first known point."""
+    for k, v in g.items():
+        if k in ("diameter_lines", "radius"):
+            continue
+        if v is None:
+            continue
+        p = _to_point(v)
+        if p:
+            r = float(p.distance(center))
+            verified["radius"] = r
+            logger.info("📐 [VERIFIER/circle] radius = dist(%s, center) = %.4f", k, r)
+            return
+    # Fallback: use given radius
+    given_r = g.get("radius")
+    if given_r is not None:
+        verified["radius"] = float(given_r)

backend/variable_pinner.py

@@ -0,0 +1,113 @@
+# backend/variable_pinner.py
+# BuddyMath V2.0 — Stage 3: Variable Pinning
+#
+# PURPOSE:
+# Converts verified data from MathProblemSchema into a hard constraint block
+# that is injected into the LLM's prompt as GROUND TRUTH.
+#
+# THE MESSAGE TO THE LLM (verbatim from spec):
+# "The values below were verified algebraically. They are Ground Truth.
+#  Do NOT recalculate them. If your intuition contradicts them — the table is correct."
+# ─────────────────────────────────────────────────────────────────────────
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from backend.math_schema import MathProblemSchema
+
+logger = logging.getLogger(__name__)
+
+_PIN_HEADER = """
+╔══════════════════════════════════════════════════════════════════════╗
+║           🔒  ALGEBRAICALLY VERIFIED — GROUND TRUTH                 ║
+║   The values below were computed deterministically (SymPy).         ║
+║   DO NOT recalculate them. DO NOT trust visual intuition over them. ║
+║   If your reasoning contradicts any value here — the table wins.    ║
+╚══════════════════════════════════════════════════════════════════════╝
+""".strip()
+
+_NULL_WARNING = """
+⚠️  INSUFFICIENT_DATA WARNING:
+    The following fields could NOT be verified due to unclear OCR/input:
+{null_list}
+    For these fields, reason carefully from the available constraints.
+    DO NOT invent values. State explicitly that these are assumed/estimated.
+""".strip()
+
+_CONTRADICTION_WARNING = """
+🚨  CONTRADICTION DETECTED:
+    The verifier found inconsistencies between the extracted data and
+    algebraic facts. Proceed with the ALGEBRAICALLY COMPUTED values,
+    NOT the extracted ones.
+""".strip()
+
+
+class VariablePinner:
+    """
+    Generates the pinning block that is injected into the LLM prompt
+    BEFORE the main pedagogical reasoning begins.
+    """
+
+    def build_pin_block(self, schema: MathProblemSchema) -> str:
+        """
+        Build the full pinning block string.
+
+        This string must be injected into the LLM prompt verbatim,
+        before the main solver / explainer instruction.
+
+        Returns:
+            str: Formatted pinning block ready for prompt injection.
+        """
+        lines: list[str] = [_PIN_HEADER, ""]
+
+        # ── Status-specific header ────────────────────────────────────
+        if schema.verification_status == "contradiction":
+            lines.append(_CONTRADICTION_WARNING)
+            lines.append("")
+        elif schema.verification_status == "insufficient_data":
+            null_keys = schema.null_fields()
+            null_list = "\n".join(f"    • {k}" for k in null_keys)
+            lines.append(_NULL_WARNING.format(null_list=null_list))
+            lines.append("")
+
+        # ── Verified facts table ──────────────────────────────────────
+        if schema.verified:
+            lines.append("📌 PINNED VALUES (Ground Truth):")
+            for key, val in schema.verified.items():
+                lines.append(f"   {key:30s} = {val}")
+            lines.append("")
+
+        # ── What to find ─────────────────────────────────────────────
+        if schema.find:
+            lines.append("🎯 QUESTION TARGETS (what to find):")
+            for target in schema.find:
+                lines.append(f"   • {target}")
+            lines.append("")
+
+        # ── Constraints ───────────────────────────────────────────────
+        if schema.constraints:
+            lines.append("📋 PROBLEM CONSTRAINTS:")
+            for c in schema.constraints:
+                lines.append(f"   • {c}")
+            lines.append("")
+
+        # ── Non-fatal warnings ────────────────────────────────────────
+        if schema.warnings:
+            lines.append("⚠️  WARNINGS (for LLM awareness):")
+            for w in schema.warnings:
+                lines.append(f"   ! {w}")
+            lines.append("")
+
+        pin_block = "\n".join(lines)
+
+        logger.info(
+            "📌 [PINNER] Built pin block | status=%s | pinned_keys=%s | null_fields=%s",
+            schema.verification_status,
+            list(schema.verified.keys()),
+            schema.null_fields(),
+        )
+        logger.debug("📌 [PINNER] Full block:\n%s", pin_block)
+
+        return pin_block

docs/legacy_prompts_backup.txt

@@ -0,0 +1,937 @@
+# prompts.py - V275.0 (Enhanced OCR for Nested Fractions)
+# Based on BUDDYMATH_COMPLETE_GUIDE V230.8 §1.3, §4.1, §6.1
+import json
+
+
+def _get_grade_features(grade: str, category: str = "") -> dict:
+    """התאמת רמת הפירוט לפי יחידות לימוד (§5.1)"""
+    is_investigation = (category == "INVESTIGATION")
+    
+    if "5 יח\"ל" in grade:
+        style = "הוכחה דקדקנית של כל מעבר, כולל נגזרות שנייה, קמירות ואסימפטוטות" if is_investigation else "הוכחה דקדקנית של כל מעבר ודיוק אלגברי מירבי"
+        return {
+            "depth": "אקדמי ומעמיק",
+            "style": style,
+            "tone": "מעצים ומאתגר, כביר של בגרות 5 יח\"ל"
+        }
+    elif "4 יח\"ל" in grade:
+        style = "הסבר ברור של חוקי האלגברה עם דגש על כלל שרשרת" if is_investigation else "הסבר ברור של חוקי האלגברה ופירוט תהליכי הפתרון"
+        return {
+            "depth": "מפורט ותומך",
+            "style": style,
+            "tone": "מעודד ומפורט, שלב אחר שלב"
+        }
+    else:
+        return {
+            "depth": "פשוט, ברור ומדובר 'בגובה העיניים' (מבחן הילד בן ה-16)",
+            "style": "צעד אחר צעד, בקריאה שוטפת. חובה להשתמש במשפטי קישור ומעבר מילוליים (כמו 'נציב את הנתונים בנוסחה:', 'כעת נבדוק את תחום ההגדרה:'). אסור להרצות.",
+            "tone": "חם, סבלני, מלא התלהבות ועידוד תמידי. כמו מורה אהובה שעוזרת באופן פרטי."
+        }
+
+def _detect_relevant_rules(text: str, category: str = "") -> list:
+    """זיהוי כללים רלוונטיים לפי קטגוריה — מבוסס-הקשר (§4.1, V231.1)"""
+    rules = []
+    t = text.lower()
+    
+    # === GEOMETRY rules (only for GEOMETRY category) ===
+    if category != "INVESTIGATION":
+        if any(x in t for x in ["מעגל", "מרכז", "רדיוס", "מקום גיאומטרי"]):
+            rules.append(r"משוואת מעגל: $(x-a)^2 + (y-b)^2 = r^2$")
+            rules.append(r"היקף מעגל: $2\\pi r$")
+        if "מרחק" in t or "d =" in t or "מקום גיאומטרי" in t:
+            rules.append(r"דיסטנס: $d = \\sqrt{(x_2-x_1)^2 + (y_2-y_1)^2}$")
+        if any(x in t for x in ["ישר", "שיפוע"]):
+            rules.append(r"משוואת ישר: $y = mx + b$")
+        if any(x in t for x in ["משולש", "שטח"]):
+            rules.append(r"שטח משולש: $S = \\frac{1}{2} \\cdot a \\cdot h$")
+        if any(x in t for x in ["משיק", "אנך"]):
+            rules.append(r"שיפועים אנכיים: $m_1 \\cdot m_2 = -1$")
+        if "מקום גיאומטרי" in t:
+             rules.append(r"פרבולה: מרחק מנקודה שווה למרחק מישר.")
+             rules.append(r"אליפסה: סכום מרחקים מ-2 נקודות קבוע ($d_1+d_2=k$).")
+             rules.append(r"היפרבולה: הפרש מרחקים מ-2 נקודות קבוע ($|d_1-d_2|=k$).")
+        if "מקום גיאומטרי" in t:
+             rules.append(r"⚠️ הנחיה קריטית: אל תנחש את הצורה! פיתוח המשוואה חייב להיעשות צעד-אחר-צעד מההגדרה המילולית.")
+             rules.append(r"דוגמה לשימוש בהגדרה: אם רשום שמרחק נקודה $P(x,y)$ ממיקום א' שווה למרחקה ממיקום ב', רשום משוואה מהצורה $d_1 = d_2$. הצב את נוסחאות המרחק, העלה בריבוע ופשט.")
+             rules.append(r"בביטויים עם שורשים: בודד שורש אחד -> עלה בריבוע -> בודד את השורש השני -> עלה בריבוע שוב.")
+    
+        # === PROOF-specific rules (V282.0) ===
+        if any(x in t for x in ["הוכח", "הוכיח", "הוכיחו", "הראה כי", "הראי כי", "הוכח כי", "הוכיחי"]):
+            rules.append(r"⚠️ זוהי שאלת הוכחה! חובה להראות את כל שרשרת ההיגיון, לא רק את התוצאה.")
+            rules.append(r"מבנה הוכחה: נתון -> מסקנה ביניים (+ נימוק/משפט) -> מסקנה הבאה -> ... -> מ.ש.ל.")
+            rules.append(r"לכל מעבר לוגי חובה לציין את הנימוק: שם המשפט, התכונה, או הכלל.")
+            rules.append(r"משולש שווה שוקיים -> זוויות בסיס שוות, חוצה זווית = תיכון = גובה לבסיס.")
+            rules.append(r"משולשים חופפים: צ.צ.צ / צ.ז.צ / ז.צ.ז - ציין איזה קריטריון נבחר ולמה.")
+            rules.append(r"אם צריך להוכיח שוויון קטעים - חפש משולשים חופפים, או תכ��נות של צורות מיוחדות.")
+
+        rules.append(r"בגיאומטריה אנליטית: לפני חישוב, בצע 'בדיקת שפיות' (Sanity Check).")
+        rules.append(r"אם נתון ש-AC קוטר, המרכז M *חייב* להיות האמצע שלו. אם החישוב מראה אחרת - הנתונים שהוצאת שגויים! נסה לקרוא שוב.")
+        rules.append(r"עדיפות לנתונים: טקסט כתוב > משוואות > שרטוט ויזואלי.")
+        rules.append(r"הימנע משימוש ב-\\\\ בתוך בלוקים של מתמטיקה, השתמש בצעדים נפרדים.")
+        
+    # V8.6.3: Contextual Logic Guardrails
+    if category == "GEOMETRY":
+        rules.append(r"ZERO ASSUMPTIONS RULE: NEVER assume, guess, or invent ANY geometric property (e.g., 'this segment is a diameter', 'this angle is 90 degrees', 'this triangle is isosceles') unless it is EXPLICITLY WRITTEN in the provided text. You are strictly forbidden from fabricating data or relationships just because the coordinates look convenient. Work ONLY with the exact facts stated in the OCR text and Data Anchor.")
+        rules.append(r"CRITICAL GEOMETRY RULE: You MUST strictly adhere to the geometric layout described in the problem text. If your calculation leads to a paradox (e.g., length 0, points colliding, or negative area), YOUR assumption is wrong. Recalculate based strictly on the given explicit constraints. DO NOT change the given equations.")
+
+    if category in ["CALCULUS", "FUNCTION_ANALYSIS", "INVESTIGATION"]:
+        rules.append(r"GRAPH MATCHING PROTOCOL: When asked to select a correct graph from multiple options (I, II, III, IV), you MUST first perform a visual scan: explicitly describe what you see in EACH given graph (e.g., 'Graph I shows asymptotes at... Graph II shows a hole at...'). Only AFTER describing all options, match your mathematical deductions to the correct visual description and select the final answer.")
+
+    if category == "CALCULUS":
+        if any(x in t for x in ["נגזרת", "גזור", "f'", "חקור"]):
+            rules.append(r"כלל החזקה: $(x^n)' = nx^{n-1}$")
+            if any(x in t for x in ["/", "frac", "מנה", "חילוק"]):
+                rules.append(r"נגזרת מנה: $(\\frac{u}{v})' = \\frac{u'v - uv'}{v^2}$")
+            if any(x in t for x in ["מכפלה", "כפל"]):
+                rules.append(r"נגזרת מכפלה: $(u \\cdot v)' = u'v + uv'$")
+            if any(x in t for x in ["שרשרת", "הרכבה", "sin", "cos"]):
+                rules.append(r"כלל שרשרת: $[f(g(x))]' = f'(g(x)) \\cdot g'(x)$")
+        if any(x in t for x in ["אינטגרל", "שטח מתחת"]):
+            rules.append(r"אינטגרל חזקה: $\\int x^n dx = \\frac{x^{n+1}}{n+1} + C$")
+        if any(x in t for x in ["דיפרנציאלית", "y'", "dy/dx"]):
+            rules.append(r"משוואה דיפרנציאלית: הפרד משתנים, אינטגרל משני הצדדים.")
+
+    # === SEQUENCES rules ===
+    if any(x in t for x in ["סדרה", "חשבונית", "הנדסית", "סכום חלקי", "הפרש"]):
+        rules.append(r"סדרה חשבונית: $a_n = a_1 + (n-1)d$, סכום: $S_n = \\frac{n}{2}(a_1 + a_n)$")
+        rules.append(r"סדרה הנדסית: $a_n = a_1 \\cdot q^{n-1}$, סכום: $S_n = a_1 \\cdot \\frac{q^n - 1}{q - 1}$")
+        if "אינסופי" in t or "גבול" in t:
+            rules.append(r"סכום סדרה הנדסית אינסופית ($|q|<1$): $S = \\frac{a_1}{1-q}$")
+
+    # === COMPLEX NUMBERS rules ===
+    if any(x in t for x in ["מרוכב", "מדומה", "i²", "i^2"]):
+        rules.append(r"$i^2 = -1$, מספר מרוכב: $z = a + bi$")
+        rules.append(r"מודולוס: $|z| = \\sqrt{a^2 + b^2}$, צמוד: $\\bar{z} = a - bi$")
+        if any(x in t for x in ["קוטבי", "דה-מואבר", "טריגונומטרי"]):
+            rules.append(r"צורה טריגונומטרית: $z = r(\\cos\\theta + i\\sin\\theta)$")
+            rules.append(r"דה-מואבר: $z^n = r^n(\\cos(n\\theta) + i\\sin(n\\theta))$")
+
+    # === VECTORS rules ===
+    if any(x in t for x in ["וקטור", "וקטורים"]):
+        rules.append(r"$\\vec{u} = (a,b)$, $|\\vec{u}| = \\sqrt{a^2+b^2}$")
+        rules.append(r"מכפלה סקלרית: $\\vec{u}\\cdot\\vec{v} = a_1 a_2 + b_1 b_2 = |u||v|\\cos\\alpha$")
+        rules.append(r"וקטורים מאונכים: $\\vec{u}\\cdot\\vec{v} = 0$")
+        # V286.0: 3D Vectors (5 יח"ל)
+        if any(x in t for x in ["מרחב", "מישור", "תלת", "z", "פרמטרי", "ניצב למישור"]):
+            rules.append(r"וקטור במרחב: $\vec{u} = (a,b,c)$, $|\vec{u}| = \sqrt{a^2+b^2+c^2}$")
+            rules.append(r"מכפלה סקלרית 3D: $\vec{u}\cdot\vec{v} = a_1 a_2 + b_1 b_2 + c_1 c_2 = |u||v|\cos\alpha$")
+            rules.append(r"מכפלה וקטורית (Cross Product): $\vec{u}\times\vec{v} = (b_1 c_2 - c_1 b_2,\; c_1 a_2 - a_1 c_2,\; a_1 b_2 - b_1 a_2)$. הוק��ור שמתקבל ניצב לשני הוקטורים המקוריים.")
+            rules.append(r"מציאת נורמלי למישור: השתמש במכפלה וקטורית של שני וקטורי כיוון הפורשים את המישור.")
+            rules.append(r"משוואת מישור: $Ax + By + Cz + D = 0$. הנורמלי הוא $\vec{n} = (A,B,C)$.")
+            rules.append(r"ישר במרחב (הצגה פרמטרית): $\vec{r} = \vec{p} + t\vec{v}$")
+            rules.append(r"מרחק נקודה $(x_0,y_0,z_0)$ ממישור $Ax+By+Cz+D=0$: $d = \frac{|Ax_0+By_0+Cz_0+D|}{\sqrt{A^2+B^2+C^2}}$")
+            rules.append(r"זווית $\alpha$ בין שני מישורים: $\cos\alpha = \frac{|\vec{n_1}\cdot\vec{n_2}|}{|\vec{n_1}||\vec{n_2}|}$")
+            rules.append(r"זווית $\beta$ בין ישר למישור: $\sin\beta = \frac{|\vec{v}\cdot\vec{n}|}{|\vec{v}||\vec{n}|}$ (כאשר $\vec{n}$ הוא נורמלי למישור).")
+            rules.append(r"מכפלה משולשת (נפח מקבילון): $V = |\vec{a}\cdot(\vec{b}\times\vec{c})|$")
+
+    # === STATISTICS rules ===
+    if any(x in t for x in ["ממוצע", "חציון", "שכיח", "סטיית תקן", "שונות"]):
+        rules.append(r"ממוצע: $\\bar{x} = \\frac{\\sum x_i}{n}$")
+        rules.append(r"שונות: $\\sigma^2 = \\frac{\\sum(x_i - \\bar{x})^2}{n}$, סטיית תקן: $\\sigma = \\sqrt{\\sigma^2}$")
+    if any(x in t for x in ["התפלגות", "נורמלית", "בינומית"]):
+        rules.append(r"התפלגות בינומית: $P(X=k) = \\binom{n}{k}p^k(1-p)^{n-k}$")
+        rules.append(r"התפלגות נורמלית: כלל 68-95-99.7 (אחוזים בטווח 1-2-3 סטיות תקן)")
+
+    # === INDUCTION rules ===
+    if any(x in t for x in ["אינדוקציה", "הוכח כי לכל", "n טבעי"]):
+        rules.append(r"שלב 1 (בסיס): הוכח עבור $n=1$. שלב 2 (הנחה): הנח עבור $n=k$. שלב 3 (צעד): הוכח עבור $n=k+1$.")
+        rules.append(r"⚠️ חובה לרשום בפירוש: 'מה צריך להוכיח', 'הנחת האינדוקציה', 'מ.ש.ל'.")
+
+    # === TRIGONOMETRY LAW rules ===
+    if any(x in t for x in ["סינוסים", "קוסינוסים", "משולש", "זווית"]):
+        if "סינוסים" in t:
+            rules.append(r"משפט הסינוסים: $\\frac{a}{\\sin A} = \\frac{b}{\\sin B} = \\frac{c}{\\sin C}$")
+        if "קוסינוסים" in t:
+            rules.append(r"משפט הקוסינוסים: $c^2 = a^2 + b^2 - 2ab\\cos C$")
+        rules.append(r"שטח משולש לפי שתי צלעות וזווית: $S = \\frac{1}{2}ab\\sin C$")
+    if any(x in t for x in ["זהות", "טריגונומטרית"]):
+        rules.append(r"$\\sin^2(x) + \\cos^2(x) = 1$")
+        rules.append(r"$\\sin(2x) = 2\\sin(x)\\cos(x)$, $\\cos(2x) = \\cos^2(x) - \\sin^2(x)$")
+    # V286.0: Advanced Trigonometry (5 יח"ל)
+    if any(x in t for x in ["sin", "cos", "tan", "trig", "טריגונומטר", "sin(", "cos("]):
+        if any(x in t for x in ["סכום", "הפרש", "α+β", "α-β", "alpha"]):
+            rules.append(r"$\\sin(\\alpha \\pm \\beta) = \\sin\\alpha\\cos\\beta \\pm \\cos\\alpha\\sin\\beta$")
+            rules.append(r"$\\cos(\\alpha \\pm \\beta) = \\cos\\alpha\\cos\\beta \\mp \\sin\\alpha\\sin\\beta$")
+            rules.append(r"$\\tan(\\alpha + \\beta) = \\frac{\\tan\\alpha + \\tan\\beta}{1 - \\tan\\alpha\\tan\\beta}$")
+        if any(x in t for x in ["חצי זווית", "sin²", "cos²"]):
+            rules.append(r"$\\sin^2\\frac{x}{2} = \\frac{1-\\cos x}{2}$, $\\cos^2\\frac{x}{2} = \\frac{1+\\cos x}{2}$")
+    if any(x in t for x in ["פתור משוואה טריגונומטרית", "sinx=", "cosx=", "sin x =", "cos x ="]):
+        rules.append(r"$\\sin x = a \\Rightarrow x = (-1)^n \\arcsin a + \\pi n$, $n \\in \\mathbb{Z}$")
+        rules.append(r"$\\cos x = a \\Rightarrow x = \\pm \\arccos a + 2\\pi n$, $n \\in \\mathbb{Z}$")
+        rules.append(r"$\\tan x = a \\Rightarrow x = \\arctan a + \\pi n$, $n \\in \\mathbb{Z}$")
+
+    # === VOLUME & SURFACE AREA rules ===
+    if any(x in t for x in ["נפח", "שטח פנים", "גליל", "חרוט", "כדור"]):
+        rules.append(r"נפח גליל: $V = \\pi r^2 h$, נפח חרוט: $V = \\frac{1}{3}\\pi r^2 h$")
+        rules.append(r"נפח כדור: $V = \\frac{4}{3}\\pi r^3$, שטח פנים כדור: $S = 4\\pi r^2$")
+
+    # V286.0: Solid Geometry (גיאומטריה מרחבית — 5 יח"ל)
+    if any(x in t for x in ["פירמידה", "מנסרה", "תיבה", "חתך", "אפותם", "מקצוע צדדי", "פאות"]):
+        rules.append(r"נפח פירמידה: $V = \frac{1}{3} S_{base} \cdot h$")
+        rules.append(r"נפח מנסרה: $V = S_{base} \cdot h$")
+        rules.append(r"שטח פנים של פירמידה: $S = S_{base} + \sum S_{faces}$")
+        rules.append(r"זווית $\alpha$ בין מקצוע צדדי לבסיס: זווית במשולש ישר-זווית הנוצר ע\"י המקצוע, הטלו על הבסיס והגובה.")
+        rules.append(r"זווית $\beta$ בין פאה צדדית לבסיס: זווית במשולש ישר-זווית הנוצר ע\"י האפותם של הפאה, הטלו על הבסיס והגובה.")
+        rules.append(r"חישובים מרחביים: השתמש תמיד במשפט פיתגורס וטריגונומטריה בתוך משולשים ישרי-זווית המקשרים פנים וחוץ.")
+
+    # === INEQUALITY rules ===
+    if any(x in t for x in ["אי-שוויון", "אי שוויון"]):
+        rules.append(r"⚠️ בכפל/חילוק באי-שוויון במספר שלילי — הפוך את כיוון הסימן!")
+        if "ריבועי" in t:
+            rules.append(r"אי-שוויון ריבועי: פתור כמשוואה, בדוק סימן בקטעים.")
+
+    # V286.0: Logarithms & Exponentials (לוגריתמים — 5 יח"ל)
+    if any(x in t for x in ["לוגריתם", "log", "ln", "מעריכי", "e^"]):
+        rules.append(r"$\\log_a(xy) = \\log_a x + \\log_a y$")
+        rules.append(r"$\\log_a\\left(\\frac{x}{y}\\right) = \\log_a x - \\log_a y$")
+        rules.append(r"$\\log_a(x^n) = n\\log_a x$")
+        rules.append(r"החלפת בסיס: $\\log_a b = \\frac{\\ln b}{\\ln a}$")
+        rules.append(r"$a^x = e^{x\\ln a}$, $\\log_a a = 1$, $\\log_a 1 = 0$")
+        rules.append(r"$\\ln e = 1$, $e^{\\ln x} = x$, $\\ln(e^x) = x$")
+
+    # V286.0: Optimization Problems (בעיות קיצון — 5 יח"ל)
+    if any(x in t for x in ["קיצון", "מקסימום", "מינימום", "שטח גדול ביותר", "נפח מקס", "ערך מרבי", "ערך מזערי", "אופטימיזציה"]):
+        rules.append(r"אסטרטגיה לבעיות אופטימיזציה (5 יח\"ל):")
+        rules.append(r"1) הגדר משתנה (x) ובטא את כל הגדלים האחרים בעזרתו.")
+        rules.append(r"2) בנה פונקציית מטרה $f(x)$ עבור הגודל שצריך למקסם/למזער.")
+        rules.append(r"3) השתמש באילוצים כדי להגיע לפונקציה של משתנה אחד בלבד.")
+        rules.append(r"4) גזור את פונקציית המטרה, השווה ל-0 ומצא את הנקודות החשודות.")
+        rules.append(r"5) הוכח את סוג הקיצון (Max/Min) בעזרת טבלה או נגזרת שנייה.")
+        rules.append(r"6) בדוק תמיד נקודות קצה של התחום אם הבעיה מוגדרת בקטע סגור.")
+
+    # V286.0: Probability & Combinatorics (הסתברות וקומבינטוריקה — 5 יח"ל)
+    if any(x in t for x in ["הסתברות", "קומבינטור", "עצי", "עץ", "תמורה", "צירוף", "בייס", "מותנה", "בלתי תלוי"]):
+        rules.append(r"$P(A \\cup B) = P(A) + P(B) - P(A \\cap B)$")
+        rules.append(r"הסתברות מותנית: $P(A|B) = \\frac{P(A \\cap B)}{P(B)}$")
+        rules.append(r"נוסחת בייס: $P(B_i|A) = \\frac{P(A|B_i)P(B_i)}{\\sum_j P(A|B_j)P(B_j)}$")
+        rules.append(r"חוק ההסתברות השלמה: $P(A) = \\sum_i P(A|B_i)P(B_i)$")
+        rules.append(r"תמורות: $P(n,k) = \\frac{n!}{(n-k)!}$, צירופים: $\\binom{n}{k} = \\frac{n!}{k!(n-k)!}$")
+        rules.append(r"אירועים בלתי תלויים: $P(A \\cap B) = P(A) \\cdot P(B)$")
+
+    # V286.0: Advanced Calculus (חדו"א מתקדם — 5 יח"ל)
+    if any(x in t for x in ["אינטגרל", "שטח מתחת", "נפח סיבוב", "אינטגרציה"]):
+        if any(x in t for x in ["חלקי", "חלקים", "by parts"]):
+            rules.append(r"אינטגרציה בחלקים: $\\int u\\,dv = uv - \\int v\\,du$")
+        if any(x in t for x in ["הצבה", "substitution"]):
+            rules.append(r"אינטגרציה בהצבה: $\\int f(g(x))g'(x)dx = \\int f(u)du$ כאשר $u=g(x)$")
+        rules.append(r"שטח בין שני גרפים: $S = \\int_a^b |f(x) - g(x)|\\,dx$")
+        if any(x in t for x in ["סיבוב", "גוף סיבוב"]):
+            rules.append(r"נפח גוף סיבוב סביב ציר $x$: $V = \\pi\\int_a^b [f(x)]^2\\,dx$")
+        if any(x in t for x in ["לא אמיתי", "מוכלל", "improper"]):
+            rules.append(r"אינטגרל מוכלל: $\\int_a^{\\infty} f(x)dx = \\lim_{b\\to\\infty} \\int_a^b f(x)dx$")
+
+    # V286.0: Limits (גבולות — 5 יח"ל)
+    if any(x in t for x in ["גבול", "lim", "שואף", "אינסוף", "לופיטל"]):
+        rules.append(r"גבולות נחשבים: $\\lim_{x\\to 0}\\frac{\\sin x}{x} = 1$")
+        rules.append(r"$\\lim_{x\\to\\infty}\\left(1+\\frac{1}{x}\\right)^x = e$")
+        rules.append(r"כלל לופיטל: אם $\\frac{0}{0}$ או $\\frac{\\infty}{\\infty}$, אז $\\lim\\frac{f(x)}{g(x)} = \\lim\\frac{f'(x)}{g'(x)}$")
+        rules.append(r"אסטרטגיה ל-$\\frac{0}{0}$: פרק לגורמים, רציונליזציה, או לופיטל.")
+        rules.append(r"אסטרטגיה ל-$\\frac{\\infty}{\\infty}$ עם פולינומים: חלק במעלה הגבוהה ביותר.")
+    
+    return rules
+
+def get_data_extraction_prompt(problem_text: str) -> str:
+    """V231.15: Template-based extraction to avoid f-string escape hell."""
+    template = r"""
+### [SACRED TRUTH: IMAGE OVER OCR]
+You are provided with an IMAGE and its rough OCR transcription.
+⚠️ CRITICAL WARNING: The OCR text is a WEAK HINT and is often WRONG, truncated, or mangled.
+💎 SACRED TRUTH: The IMAGE is the absolute source of truth.
+
+YOUR TASK:
+1. PERCEPTUAL PRIORITY: Visually inspect the IMAGE meticulously. Every pixel of the formula counts.
+2. TOP-DOWN HIERARCHY: Start from the very top of the image. The main function (e.g., f(x)=...) is usually the first mathematical line. DO NOT MISS IT.
+3. OCR SKEPTICISM: The OCR text is often a "hallucination hint" for formulas. If the OCR text says h(x) but the IMAGE shows f(x) at the top, the IMAGE'S f(x) is the SACRED TRUTH.
+4. LTR MATHEMATICAL FLOW: Equations are NOT Hebrew. They are read horizontally LEFT-TO-RIGHT. Ensure multipliers, exponents, and fractions are extracted in their visual LTR order.
+5. NO INVENTIONS: Do not "fix" the math. If it looks incomplete, extract what is there.
+
+Extract:
+1. **function_equations**: ALL equations with '=' sign
+   - ⚠️ **ABSOLUTE PRIORITY**: Extract the primary function (f(x), y=...) first.
+   - Functions: f(x) = ..., g(x) = ...
+   - Circles: x² + y² = r², (x-a)² + (y-b)² = r²
+   - Lines: y = mx + b, ax + by = c
+   - ANY equation with '=' sign!
+
+**Mathematical Scanning Directionality (V8.9.3):**
+- **LTR PRIORITY:** Mathematical equations are STRICTLY Left-To-Right. 
+- When extracting formulas embedded in Hebrew text, IGNORE the RTL flow. 
+- Read the characters in their literal horizontal visual order from LEFT to RIGHT. 
+- Ensure multipliers, exponents, and signs are placed exactly where they appear visually.
+
+**Visual Context & Continuity (V8.9.5):**
+- **SPLIT EQUATIONS:** If an equation starts on one line and ends on another, merge them into a single coherent formula.
+- **SEGMENTED CONSTRAINTS:** Look for constraints (like x > 0) near equations; they are often visually separated by space or Hebrew words but belong to the formula.
+- **MULTI-PART ANCHORING:** Maintain consistency between sub-questions (א, ב, ג). If a variable 'm' is defined in the preamble, it applies to all sub-questions.
+
+2. **points**: Named points like A, B, M(3,5), P(x,y)
+
+3. **specific_values**: Numbers like r=5, a=3, m=2
+
+4. **constraints**: Conditions like x>0, x≠2, domain restrictions
+
+5. **sub_questions**: Parts א, ב, ג or a, b, c
+
+6. **geometric_anchors** (CRITICAL FOR VALIDATION):
+   - center: [x,y] coordinates if a circle center is given
+   - radius: numeric value if radius is given
+   - point_a, point_b: Strings like "(x,y)" if specific points are given for distance/lines
+
+JSON format (STRUCTURE ONLY - DO NOT USE THESE EXACT VALUES):
+{{
+  "function_equations": ["<equation_1>", "<equation_2>"],
+  "points": ["<point_name>", "<point_name>(<x>,<y>)"],
+  "specific_values": ["<variable>=<value>"],
+  "constraints": ["<constraint_1>"],
+  "sub_questions": ["<sub_question_1>"],
+  "center": [null, null],
+  "radius": null,
+  "point_a": "(null, null)",
+  "point_b": "(null, null)"
+}}
+
+
+**CRITICAL JSON STRUCTURE RULE (V8.9.4):**
+- You MUST output a SINGLE, flat JSON object.
+- EVERY mathematical expression, function, or parameter MUST have a UNIQUE, highly descriptive key.
+- DO NOT use a generic key like "equation" multiple times, as this will overwrite the data.
+- DO NOT output an array/list of objects.
+- **Correct Example:** { "main_function_f": "f(x)=...", "function_h": "h(x)=...", "given_extremum_x": "x=1/e" }
+- **Wrong Example:** { "equation": "f(x)=...", "equation": "h(x)=..." }
+
+CRITICAL INSTRUCTIONS:
+1. Include ALL equations with '=' sign in function_equations!
+2. **DATA INTEGRITY (V4.3.0):** Use the data below verbatim.
+3. **VARIABLE ENFORCEMENT (V4.0.1):** ALL equations must use standard single-letter mathematical variables (x, y, z, a, b, c, m, n, k). 
+   - DO NOT extract descriptive English names like "number_of_notebooks". 
+   - Map descriptive names from text to single letters (e.g., if text says "cost is x", use x. If it says "cost of notebook", map to 'c' or 'x'). 
+   - Equations with descriptive multi-letter variables will crash the calculator.
+4. DO NOT HALLUCINATE OR GUESS! 🚫 If an equation or point is NOT explicitly written in the problem, DO NOT invent it.
+5. **Mathematical Logic over OCR (V8.6.6):** In case of OCR contradictions (e.g. $e^x$ vs $e^{{-x}}$ in the same problem), use mathematical logic to choose the correct formula based on the problem's context (e.g., if a question asks for a limit at $\infty$ that only exists for $e^{{-x}}$, prefer that).
+6. Example: Do not assume `f(x) = ax - x^2` just because it looks like a standard problem. Only extract what is literally there.
+7. **SUB-QUESTION MAPPING (CRITICAL - V231.14):** You MUST map ALL sub-questions present in the OCR text (e.g., א, ב, ג, ד). Do NOT group them into one question and do NOT stop at the first one. Each sub-question letter requires its own entry in the `sub_questions` array.
+8. **DATA SCOPING (V8.6.9 - CRITICAL):** Only extract data that is truly GLOBAL (applies to all sections). If a value or constraint is explicitly tied to a specific section (e.g., "בסעיף ב' נתון כי a=1"), do NOT put it in the `specific_values` of the main anchor. The problem understanding phase will handle the local data.
+9. **CHRONOLOGICAL ISOLATION (V310.0):** If a variable is assigned a value in one sub-question, it MUST NOT be used in previous sub-questions.
+r"""
+
+def get_specialist_prompt(category, problem_text, solver_hint, grade, student_name, student_gender="M", data_anchor=None):
+    """בניית הפרומפט המלכותי — המורה למתמטיקה V231.6 (Data Anchor)"""
+    features = _get_grade_features(grade, category)
+    relevant_rules = _detect_relevant_rules(problem_text, category)
+    rules_str = "\n".join([f"    - {r}" for r in relevant_rules]) if relevant_rules else f"    (לא זוהו כללים ספציפיים — בחר רק כללים רלוונטיים לקטגוריה {category})"
+    
+    # Anchor Block — DATA INTEGRITY RULE
+    anchor_block = ""
+    geo_verified_block = ""  # V1.0: Geometric Sanity Engine output
+    if data_anchor:
+        # Extract and remove internal sanity keys before JSON serialization
+        geo_prompt_block = data_anchor.pop("_geo_prompt_block", "")
+        data_anchor.pop("_verified_facts", None)
+        data_anchor.pop("_geometry_warnings", None)
+
+        anchor_block = f"""
+    ══════════════════════════════════════════════════════
+    📜 DATA INTEGRITY RULE (ABSOLUTE TRUTH):
+    ══════════════════════════════════════════════════════
+    The data below is the ABSOLUTE TRUTH extracted from the student's image.
+    If it contains function_equations or equations — those ARE the problem's data.
+    YOU MUST use them EXACTLY AS GIVEN. Never claim data is "missing" if it is in the data.
+    Never assume, invent, or substitute a different function under ANY circumstances.
+    Violating this rule is a critical pedagogical failure.
+    ══════════════════════════════════════════════════════
+    נתוני שאלת המקור (השתמש רק בהם):
+    {json.dumps(data_anchor, indent=2, ensure_ascii=False)}
+
+    CONSTRAINT: If the data says A(0,5), use A(0,5). If it contains f(x), solve that f(x).
+    """
+        # V1.0: Inject verified geometric facts (if the sanity engine found anything)
+        if geo_prompt_block:
+            geo_verified_block = geo_prompt_block
+
+    # V231.5: Gender-aware phrases
+    if student_gender == "F":
+        g = {
+            "royal": "נסיכה",
+            "come": "בואי",
+            "ready": "מוכנה",
+            "great": "מעולה",
+            "solved": "פתרת",
+            "proud": "גאה בך",
+            "try_again": "בואי ננסה שוב יחד",
+            "example_open": f"כל הכבוד {student_name} נסיכה! 👑",
+            "example_close": f"כל הכבוד {student_name}! 👑 {{'פתרת' if student_gender == 'F' else 'פתרת'}} מעולה. אני גאה בך!"
+        }
+    else:
+        g = {
+            "royal": "נסיך",
+            "come": "בוא",
+            "ready": "מוכן",
+            "great": "מעולה",
+            "solved": "פתרת",
+            "proud": "גאה בך",
+            "try_again": "בוא ננסה שוב יחד",
+            "example_open": f"כל הכבוד {student_name} נסיך! 👑",
+            "example_close": f"כל הכבוד {student_name}! 👑 פתרת מעולה. אני גאה בך!"
+        }
+    # V282.0: Proof-specific instructions (outside f-string to avoid backslash issues in Python 3.11)
+    proof_keywords = ["הוכח", "הוכיח", "הוכיחו", "הראה כי", "הראי כי"]
+    is_proof = any(x in problem_text for x in proof_keywords)
+    proof_block = ""
+    if is_proof:
+        proof_block = """
+    ═══════════════════════════════════════════════════
+    📐 הוראות מיוחדות להוכחות (V282.0):
+    ═══════════════════════════════════════════════════
+    
+    🔴 זוהי שאלת הוכחה! החוקים הבאים הם חובה:
+    1. **אסור לקפוץ לתשובה.** ההוכחה היא הדרך, לא התוצאה. התלמיד צריך לראות כל צעד.
+    2. **מבנה חובה לכל צעד:** "נתון ש-[X]. לפי [שם המשפט/תכונה], מתקיים [Y]."
+    3. **נימוק לכל מעבר:** לכל שוויון/אי-שוויון, ציין למה הוא נכון.
+    4. **שרשרת לוגית:** כל צעד חייב להסתמך על צעד קודם או על נתון.
+    5. **ציין שיטת הוכחה:** חפוש משולשים חופפים? תכונות של שווה שוקיים? זוויות מתחלפות?
+    6. **סיום:** בסוף חובה לכתוב "ולכן הוכחנו ש-[מה שנדרש]. מ.ש.ל."
+    7. **דוגמה למבנה טוב:**
+       - "נתון שהמשולש ABC שווה שוקיים (AB = AC). לפי תכונה: זוויות בסיס שוות."
+       - "חישבנו שזווית CDF שווה לזווית DCF. לפי משפט: במשולש ששתי זוויות בו שוות, הצלעות מולן שוות, DC = CF."
+    8. **אסור:** לכתוב "DC = CF" בלי להסביר למה. חובה לבנות את כל שרשרת ההוכחה.
+    """
+    # V285.1: Investigation Table (Table UI)
+    investigation_keywords = ["חקור", "חקירת", "קיצון", "אסימפטוט", "עליה", "ירידה"]
+    is_investigation = "INVESTIGATION" in category or any(x in problem_text for x in investigation_keywords)
+    investigation_block = ""
+    if is_investigation:
+        investigation_block = """
+    ═══════════════════════════════════════════════════
+    📈 הוראות מיוחדות לחקירת פונקציה (Table UI):
+    ═══════════════════════════════════════════════════
+    
+    בנוסף לשדות הרגילים ב-JSON, באחריותך להוסיף בשורש ה-JSON את השדה "investigation" המילוני הזה:
+    "investigation": {
+      "function": "הפונקציה ב-LaTeX",
+      "derivative": "הנגזרת ב-LaTeX",
+      "second_derivative": "נגזרת שנייה ב-LaTeX (השאר ריק אם אין צורך)",
+      "domain": "תחום הגדרה עטוף ב-LaTeX",
+      "critical_points": [
+        {"x": "ערך x", "y": "ערך y", "f_prime": "0", "behavior": "מקסימום/מינימום"}
+      ],
+      "increasing": ["(a, b)", "(1, \\infty)"],
+      "decreasing": ["(-\\infty, a)"],
+      "concave_up": ["(a, b)"],
+      "concave_down": ["(b, c)"]
+    }
+    """
+    prompt = f"""
+    DEPTH: {features['depth']}
+    STYLE: {features['style']} (בנימה של '{g['royal']}').
+    TONE: {features['tone']}
+    
+    {anchor_block}
+    {geo_verified_block}
+
+    🎯 המשימה: פתור את התרגיל בצורה פדגוגית, מעצימה ובשלבים ברורים.
+    
+    📜 כללי הפדגוגיה של BuddyMath (חובה!):
+{rules_str}
+
+    {proof_block}
+    {investigation_block}
+
+    ═══════════════════════════════════════════════════
+    הנחיות לפתרון (Solver Hint):
+    {solver_hint}
+    ═══════════════════════════════════════════════════
+
+    השאלה לפתרון:
+    {problem_text}
+
+    דגימת סגנון פנייה:
+    - פתיחה: "{g['example_open']}"
+    - סיום: "{g['example_close']}"
+    """
+    return prompt
+
+
+# prompts.py - V275.1 (Safe OCR - Technique over Examples)
+def get_transcription_prompt():
+    """
+    V275.1: Safe OCR Prompt - Teaches TECHNIQUE, not specific examples.
+    
+    Why V275.1?
+    - V275.0 had specific examples like "\\frac{1}{x}(a + \\frac{(\\ln x)^n}{n})"
+    - This caused the LLM to "fit" different functions to the example
+    - Now we teach HOW to recognize patterns, not WHAT pattern to expect
+    """
+    return """
+    TRANSCRIBE the FULL text from the image. Include ALL Hebrew text and ALL mathematical expressions.
+    
+    🎯 **YOUR ONLY JOB: Copy EXACTLY what you see. Do NOT interpret, simplify, or guess.**
+    
+    📐 **TRANSCRIPTION TECHNIQUE (How to be accurate):**
+    
+    1. **ZERO TRUNCATION RULE (CRITICAL - V310.0)**
+       - **NEVER skip the beginning of an equation.** If a formula starts with `f(x) =`, `1/x`, or a constant, you MUST include it.
+       - Look at the very left edge of the image/expression. Truncating the starting terms is a FATAL ERROR.
+       - **FULL CAPTURE:** Transcribe from the first character to the last. No summaries.
+    
+    2. **VISUAL DISAMBIGUATION (V310.0 - NEW)**
+       - **1 vs a:** Double-check characters that look like a straight line or small loop. In fractions like `1/x` or `a/x`, verify via context.
+       - **2 vs z:** Look for the horizontal base of the `2` vs the sharp angles of the `z`.
+       - **0 vs o / O:** Check if it's a number (zero) or a letter (o).
+       - **5 vs s / S:** Distinguish the top bar of the `5` from the curves of the `s`.
+       - **MATH CONTEXT:** Parameter letters like `a, b, c` are usually distinct from constants like `1, 2, 3`. If a formula has both, look for subtle stylistic differences.
+    
+    3. **FRACTION & NESTING RIGOR**
+       - **WORK OUTSIDE-IN:** Identify the outermost structure (e.g., a large fraction) before transcribing the contents.
+       - **Numerator/Denominator:** Transcribe EVERYTHING above and below the line. Use `\\frac{num}{den}`.
+       - **Parentheses:** Use `\\left(` and `\\right)` for nested or large expressions.
+    
+    4. **SCAN THE EDGES**
+       - Check if the expression starts or ends very close to the Bounding Box edge. Truncation usually happens at the very start.
+    
+    ✅ **OUTPUT:** The EXACT text from the image, with proper LaTeX for math.
+    """
+
+# ==================== V260.0 PEDAGOGICAL PROMPTS ====================
+
+def get_strategy_card_prompt(problem_text: str, data_anchor: dict) -> str:
+    """V260.1: Generate high-level strategy as HINTS to encourage self-solving."""
+    return f"""
+    ROLE: Elite Math Tutor (Pedagogical Architect).
+    TASK: Analyze this problem and provide a high-level STRATEGY guide filled with HINTS.
+    
+    PROBLEM:
+    {problem_text}
+    
+    DATA (Context):
+    {json.dumps(data_anchor, ensure_ascii=False)}
+    
+    INSTRUCTIONS:
+    1. Explain the LOGIC of how to approach this problem, but frame it as hints. 
+    2. === STRATEGY CARD PEDAGOGY RULE ===
+       CRITICAL: DO NOT solve the problem here. DO NOT use actual equations or numbers.
+       Speak conceptually. Give the student the "blueprint" so they can try it themselves.
+       End the `content` section with an encouraging call to action to try it alone first! (e.g., "קחו דף ועט, נסו לפתור לבד לפי הרמזים, ואם נתקעתם - הפתרון המלא מחכה לכם למטה!").
+    3. Provide 3-4 bullet points acting as stepping stones/hints.
+    4. CRITICAL: Output MUST be in HEBREW (עברית).
+    5. Tone: Encouraging, challenging, empowering.
+    
+    OUTPUT JSON:
+    {{
+        "title": "איך ניגשים לשאלה הזו? 💡",
+        "content": "הסבר מילולי קצר המעודד עבודה עצמאית...",
+        "steps": [
+             "רמז 1: מכיוון שנתונה נקודת קיצון, נסו לחשוב מה זה אומר על הנגזרת...",
+             "רמז 2: חיתוך עם הצירים דורש מכם..."
+        ]
+    }}
+    """
+
+def get_visual_context_prompt(problem_text: str, category: str) -> str:
+    """V260.0: Generate visual description for the sketch card."""
+    return f"""
+    ROLE: Visual describer for blind students / schematic generator.
+    TASK: Describe the VISUAL SETUP of this math problem.
+    
+    PROBLEM:
+    {problem_text}
+    
+    CATEGORY: {category}
+    
+    INSTRUCTIONS:
+    1. If GEOMETRY: Describe the shapes, how they connect, what is tangent to what.
+       - **CRITICAL**: Populate "geometric_entities" with PRECISE COORDINATES for plotting.
+       - If no coordinates are given, ESTIMATE logical coordinates (e.g., A(0,0), B(3,0) for a base).
+    2. If FUNCTION: Describe the graph shape (parabola opening up/down), intersection points, asymptotes.
+       - **CRITICAL GRAPH DESCRIPTION (V300.5):** כאשר יש גרפים משורטטים בתמונה (כמו פונקציה ונגזרת), עליך לפרט ב-description את התכונות הקריטיות של כל גרף בנפרד (גרף I, גרף II וכו'). חובה לציין: האם הגרף חותך את ראשית הצירים (0,0)? האם הוא מתחיל בערך חיובי/שלילי על ציר ה-y? כמה נקודות חיתוך יש לו בערך עם ציר ה-x? האם יש לו נקודות קיצון בולטות? מידע זה קריטי כדי שהמודל הבא יוכל להתאים נכונה את המשוואות לגרפים.
+       - **MULTIPLE CHOICE GRAPHS (V310.0):** בשאלות של "התאם בין גרף לפונקציה", חובה לתת תיאור מתמטי קצר (אסימפטוטות, חיתוך עם צירים) לכל אחד מהגרפים הממוספרים בתמונה בנפרד.
+    3. Goal: Help a student "see" the problem before solving.
+    4. Keep it simple and descriptive.
+    5. CRITICAL: Output MUST be in HEBREW (עברית). Explain the visuals in Hebrew.
+    
+    OUTPUT JSON (STRUCTURE ONLY - USE ACTUAL PROBLEM DATA):
+    {{
+        "title": "המחשה חזותית ✏️",
+        "description": "הסבר מילולי קצר...",
+        "geometric_entities": {{
+            "points": [{{"label": "<point_name>", "x": 0.0, "y": 0.0}}],
+            "segments": [{{"start": "<point_name>", "end": "<point_name>", "color": "blue"}}],
+            "circles": [{{"center_x": 0.0, "center_y": 0.0, "radius": 0.0}}]
+        }},
+        "latex_input": "ONLY the raw mathematical expression. NO 'f(x)=' prefixes. You MAY use commas to separate multiple related equations if the problem involves several functions (e.g. \\\\ln(x), \\\\frac{{1}}{{x}}). Just the single expression or comma-separated expressions. If no graph is needed, leave empty string."
+    }}
+    
+    🚨 GRAPH PERSISTENCE RULES (V300.3 — CRITICAL):
+    - 'latex_input' is MANDATORY. You MUST provide it. NEVER leave it as null or empty string "".
+    - NEVER say "I cannot draw" or "no graph possible". Always provide your best equation.
+    - For GEOMETRY: use the main circle/line equation (e.g. "(x-3)^2 + (y-5)^2 = 39").
+    - For FUNCTION: use the function equation (e.g. "\\frac{{\\ln(x)}}{{x^2-4}}").
+    - For LOCUS: write the final locus equation.
+    - If you are TRULY unsure: use "x" as a placeholder — the server will handle it.
+    - The latex_input must use valid LaTeX WITHOUT $$ wrappers (e.g. "x^2 + y^2 = 25" not "$$x^2+y^2=25$$").
+    
+    🚨 HELPER SKETCH RULE (V300.3 — NEW):
+    If no image is provided (blind setup):
+    - Read the verbal description of the geometry/trigonometry problem carefully.
+    - Extract coordinates, lines, or functions from the text to generate an illustration sketch.
+    - Your goal is to CREATE the visual intuition that the student is missing.
+    - Even without an image, you MUST populate "geometric_entities" and "latex_input".
+    """
+
+
+# ==================== V8.6.8 MASTER PROMPT (THE ANCHOR STABILITY FIX) ====================
+
+def get_master_prompt_v860(category: str = "", problem_text: str = ""):
+    """
+    V8.6.9: The Anchor Stability Fix + Dynamic JSON for Graphs.
+    """
+    graph_field = ""
+    is_graph = category == "GRAPH_IDENTIFICATION" or ("גרף" in problem_text and "איזה" in problem_text)
+    if is_graph:
+        graph_field = """
+      "graph_analysis": {
+        "function_analysis": "תיאור מתמטי מפורט של הפונקציה (נקודות חיתוך, קיצון, אסימפטוטות)",
+        "graph_options": [{"id": "I", "description": "..."}, {"id": "II", "description": "..."}],
+        "matching_logic": "הסבר המקשר בין תכונות הפונקציה למאפייני הגרף הנבחר",
+        "final_match": "התשובה הסופית (למשל: גרף II)"
+      },"""
+
+    prompt_template = r"""
+    🔴 MASTER PROMPT BLOCK — VERSION V8.6.8 (THE ANCHOR STABILITY)
+    
+    CRITICAL: You MUST output ONLY valid JSON. Absolutely NO conversational text before or after the JSON block. 
+    Do NOT wrap the JSON in markdown code blocks like ```json.
+    
+    ROLE:
+    אתה מורה פרטי למתמטיקה (הטוב ביותר בארץ!). המטרה שלך היא להסביר לתלמיד לא רק *איך* פותרים, אלא *למה* עושים כל צעד. רמת ההסבר צריכה להיות כזו שגם תתלמיד שרואה את החומר פעם ראשונה יבין 100% מהדרך. הגישה שלך היא חמה, מעודדת ומעצימה (סגנון 'הנסיך/הנסיכה').
+
+    ═══════════════════════════════════════════
+    ABSOLUTE RULES (violations cause immediate rejection):
+    ═══════════════════════════════════════════
+    1. **DATA ANCHOR SUPREMACY (V8.9.2):** The equations in the JSON Data Anchor are the ABSOLUTE TRUTH. You MUST solve the exact math provided in the Anchor. Do NOT attempt to re-read the image for the main function; trust the pre-validated Data Anchor.
+    2. **ZERO MAGIC MATH (BABY STEPS):** 
+       - NEVER skip algebraic steps. Show moving sides, dividing, and expanding brackets.
+       - ALWAYS explain the mathematical rule/theorem *BEFORE* applying it. 
+         * Bad: "נגזור ונשווה לאפס: f'(x) = 2x"
+         * Good: "כדי למצוא נקודת קיצון נגזור את הפונקציה. מכיוון שזו מנה, נשתמש בכלל המנה האומר ש... נגזור את המונה בנפרד ואת המכנה בנפרד:"
+    3. **COMPLETE THE MISSION (ANTI-TRUNCATION):** Never abandon the task. You MUST reach the final numeric/algebraic answer. If asked for extrema, you must find x, y, and classify (max/min). 
+    4. **ANTI-ASCII-ART RULE (V8.8.8):** NEVER attempt to draw or sketch a graph using text characters, keyboard symbols, slashes, or ASCII art (e.g., do not use |, /, \\, -, _ to make a picture). If asked to sketch a graph, ONLY describe its mathematical properties in text (e.g., intersections, asymptotes).
+    5. **CONTENT TYPE SEPARATION (IRON LAW - V9.1.0):**
+       - All LaTeX math and steps must go inside the `block_math` list for clear UI display. 
+       - `block_math` MUST contain ONLY PURE MATH. Absolutely NO HEBREW LETTERS, no words, no explanations. 
+       - Do NOT put coordinate lists or points like `A(0,1), B(2,3)` in `block_math`. Points and their names MUST stay in `content_mixed`.
+       - EXTREME SIMPLICITY MANDATE FOR MATH BLOCKS: 
+         * `block_math` MUST contain exactly ONE mathematical operation per step.
+         * NEVER use commas (,) to separate multiple equations. 
+         * NEVER chain equations (e.g., NO `x = 2 + 2 = 4`). Break EVERY '=' into a new JSON step.
+         * MAXIMUM LENGTH: A single `block_math` string MUST NEVER exceed 40 characters. If a calculation is longer (like a complex fraction), you MUST break it down into intermediate variables across multiple steps.
+       - Descriptions and casual variables must stay in `content_mixed`.
+       - NEVER write Hebrew inside `block_math` or `final_answer`. (CRITICAL: violates the algebraic validator contract).
+    6. **ANTI-TABLE RULE & EXTREMA ANALYSIS:** 
+       - NEVER use Markdown tables (e.g., using | and -).
+       - When finding Extrema (Max/Min), DO NOT suggest using a table. Instead, use explicit text steps to test the intervals. 
+       - Example: "נבדוק את תחומי העלייה והירידה: עבור $x=\pi/4$ הנגזרת חיובית, ועבור $x=3\pi/4$ היא שלילית. לכן זו נקודת מקסימום". 
+       - You MUST complete the calculation, find the Y values ($y=f(x)$), and explicitly state the classification (Max or Min).
+    7. **STRICT JSON ONLY:** No preamble, no post-amble, no markdown.
+    7. **ANTI-PARADOX PROTOCOL (V8.6.9):**
+       - If your mathematical calculation seems to lead to a paradox (e.g., length is 0, or points C and D are the exact same), DO NOT STOP THE SOLUTION.
+       - 99% of the time, this is a calculation error on your end. RECALCULATE your steps using a different geometric or algebraic approach.
+       - NEVER give up. NEVER output "אני מזהה סתירה בנתונים". You MUST find a valid path and provide the final answer for the student.
+    8. **LATEX SYNTAX RULE (V8.6.9 — CRITICAL):**
+       - You MUST strictly use LaTeX macros for all mathematical functions. 
+       - You MUST write \ln (with a backslash) and NEVER just ln. 
+       - You MUST write \sin, \cos, \tan, \log. 
+       - Failure to use the backslash will crash the KaTeX renderer and Fail validation.
+    9. **ANTI-NEWLINE & BIDI SAFETY:**
+       - In the `final_answer` field, NEVER use `\\` or `\newline` for line breaks. 
+       - The `final_answer` field MUST BE 100% PURE MATH. Absolutely NO Hebrew letters, words, or explanations. If the answer requires a textual explanation, put the text in `content_mixed` of the final step, and leave `final_answer` with just the numbers/math, or empty.
+       - If there are multiple answers, separate them ONLY with English commas (e.g., "x=1, x=2").
+    10. **VARIABLE CONSISTENCY (V8.6.8):** 
+       - Always use standard mathematical variables ($x, y, z, m, n$) as provided in context. Never invent new variable names not found in the Data Anchor or original problem.
+    10. **STRATEGY CARD NO-SPOILER RULE (CRITICAL):**
+        - The `strategy_card` MUST NOT contain any numbers, final equations, derivatives, or solutions.
+        - It must ONLY contain high-level conceptual hints ("רמז 1: כדי למצוא קיצון, חשבו על...").
+    11. **NO HEBREW OR LOGICAL ARROWS IN LATEX:**
+        - Within `block_math` and all LaTeX parts, DO NOT use Hebrew text.
+        - DO NOT use logical arrows like `\implies`, `\Rightarrow`, or `\iff` as they cause parsing errors. Use descriptive words in `content_mixed` instead.
+    12. **PEDAGOGICAL HIGHLIGHTING:**
+        - Use `\\color{red}{...}` for highlighting ONLY inside the `content_mixed` field when explaining inline math. 
+        - NEVER use color tags inside `block_math` or `final_answer` as it will crash the backend algebraic validator.
+    13. **MULTI-IMAGE & GRADING LOGIC (V308.0 - CRITICAL)**:
+        - אם קיבלת תמונה אחת בלבד: עליך להניח שהתלמיד מבקש פתרון מלא מההתחלה, או הסבר רגיל שלבים שלבים כפי שביקש.
+        - אם קיבלת יותר מתמונה אחת: התמונה הראשונה היא השאלה המקורית. שאר התמונות הן נסיונות הפתרון של התלמיד בכתב יד. 
+        - במצב של יותר מתמונה אחת עליך לעבור ל**מצב 'בדיקת שיעורי בית' (Grading Mode)** בו אתה ראשית בודק היכן התלמיד טעה בפתרון שלו מהמחברת, מתקן אותו נקודתית וחולק לו שבחים על מה שכן הצליח, ואז מחזיר אותו למסלול הנכון להמשך התרגיל. אל תוציא מיד פתרון מלא במצב זה, תן לו להבין קודם איפה הטעות!
+    14. **AI ASSESSMENT TELEMETRY (CRITICAL FOR ANALYTICS):**
+        - בסיום הניתוח, עליך להוסיף אובייקט `assessment` חבוי ב-JSON.
+        - בחר את ה-`primary_skill` מתוך הרשימה הסגורה הבאה בלבד: ["אלגברה", "גיאומטריה", "טריגונומטריה", "הסתברות", "חשבון דיפרנציאלי"]. בשום פנים ואופן אל תמציא נושאים חדשים.
+        - `sub_skill`: תיאור חופשי קצר של תת-הנושא הספציפי בתרגיל (למשל: "חוקי חזקות").
+        - `mastery_score`: ציון מ-1 עד 100 על סמך איכות הפתרון של התלמיד בתמונה. אם אין תמונת פתרון, תן ציון על פי הבנת התרגיל או שים ציון ריק.
+        - `parent_note`: משפט אחד קצר וחיובי המיועד להוריו של התלמיד, המסכם את חוזקותיו (למשל: "התלמיד גילה הבנה טובה בבידוד משתנים").
+    15. **GRAPH ANTI-HALLUCINATION (CRITICAL - V310.0):**
+        - When asked to match a function to a graph, NEVER rely on visual size estimation or "gut feeling" from the image.
+        - You MUST find mathematical anchors: intersection points with axes ($x=0$ or $y=0$), extrema, or asymptotes.
+        - Cross-reference your algebraic findings with the provided graphs.
+        - If the image is ambiguous, state clearly: "בגלל שהשרטוט אינו חד-משמעי, עלינו לוודא את נכונות הגרף באמצעות הצבת נקודות חיתוך".
+    16. **CHRONOLOGICAL LOGIC & DATA ISOLATION (V8.6.9 - CRITICAL):**
+        - You MUST solve sub-questions strictly in order.
+        - NEVER use data, parameters (like $a=1$), or specific values that explicitly belong to a LATER sub-question (e.g., Section ב') to solve an EARLIER sub-question (e.g., Section א').
+        - Solve earlier sections algebraically using general variables unless the data is part of the global question anchor.
+        - If a student's finding in Section א' is required for Section ב', you may use it, but NEVER the other way around.
+    17. **VISUAL GRAPH ANALYSIS (V8.9.1):** When asked to identify a graph from an image containing multiple options (e.g., I, II, III, IV), you MUST explicitly describe what you see in the image for EACH option before making a choice. Base your final selection strictly on matching your mathematical deductions (domain, asymptotes, roots) to the visual features of the graphs in the image. Ensure these descriptions are in `content_mixed` to maintain logical transparency for the student.
+    18. **NO GUESSING RULE (V310.0):** אם הנתונים בתמונה אינם מספיקים כדי לקבוע בוודאות איזה גרף מתאים לאזו פונקציה, אל תנחש! הצג את הניתוח המתמטי והסבר מה חסר כדי להגיע להכרעה. ניתן להוסיף: "מומלץ לבחון את הגרף המצורף (אם קיים) כדי לראות את המאפיינים שחישבנו."
+
+
+    ═══════════════════════════════════════════════════
+    REQUIRED JSON STRUCTURE (EXACT KEYS):
+    ═══════════════════════════════════════════════════
+    {{
+      {graph_field}
+      "strategy_card": {{
+        "title": "איך ניגשים לשאלה הזו? 🧭",
+        "intro": "היי! נראה שיש לנו פה שאלת [נושא] מצוינת...",
+        "bullets": ["רמז 1: [רמז מוכוון פעולה ללא ספוילרים או תשובות]", "רמז 2: [רמז נוסף]"],
+        "call_to_action": "קחו דף ועט, נסו לפתור לבד לפי הרמזים, ואם נתקעתם – פתחו את הסעיפים למטה!"
+      },
+      "approach": "הקדמה מלאה: פתיח חם, אישי ומלמד שמסביר בשפה פתוחה מה נלך לעשות בתרגיל ולמה (למשל: 'כדי למצוא אסימפטוטות אנחנו נבדוק מה קורה בפלוס ומינוס אינסוף').",
+      "steps": [
+        {
+          "step_id": 1,
+          "content_mixed": "(הסבר פדגוגי מפורט ואמהי) כדי למצוא את הנגזרת נשתמש בכלל המנה, ונגזור את המונה בנפרד ואת המכנה בנפרד:",
+          "block_math": "y' = \\frac{\\color{blue}{2x} \\cdot (x-1) - x^2 \\cdot \\color{blue}{1}}{(x-1)^2}"
+        },
+        {
+          "step_id": 2,
+          "content_mixed": "(המשך הסבר חם ומפורט) נציב כעת $x=\\color{red}{5}$ במשוואה שצמצמנו:",
+          "block_math": "y' = \\frac{\\color{red}{5}^2 - 2\\cdot \\color{red}{5}}{(\\color{red}{5}-1)^2} = \\frac{15}{16}"
+        }
+      ],
+      "final_answer": "התשובה הסופית נטו (LaTeX)",
+      "teacher_summary": {
+        "audio_pitch": "פיצ' שיחתי (כמו פודקאסט קצר) של 30-40 שניות שבו המורה מסכמת את התרגיל וחולקת תובנות. כתבי בטון אמהי, חם ומעודד.",
+        "key_concepts": ["סיכום מלמד 1: הפקת לקחים ותובנה אסטרטגית מהתרגיל (למשל 'שימו לב שתמיד לפני גזירת מנה נרצה לסדר את הפונקציה')", "סיכום מלמד 2: כלל אצבע שאפשר לקחת משאלה זו הלאה"],
+        "formulas": ["נוסחאות מרכזיות ��הן השתמשנו, בפורמט LaTeX נקי (ללא סוגרי דולר)"]
+      },
+      "assessment": {
+        "primary_skill": "אלגברה / גיאומטריה / טריגונומטריה / הסתברות / חשבון דיפרנציאלי",
+        "sub_skill": "תת הנושא הספציפי",
+        "mastery_score": 85,
+        "parent_note": "משפט על הצלחת התלמיד עבור דוח ההורים."
+      }
+    }}
+    
+    CRITICAL: Output ONLY the JSON block. No text before, no text after. No markdown formatting.
+    """
+    return prompt_template.replace("{graph_field}", graph_field)
+
+def get_master_prompt_v430(category: str = "", problem_text: str = ""):
+    """V4.3.0: Legacy placeholder, redirecting to V8.6.0 for 'The Golden Merge'"""
+    return get_master_prompt_v860(category=category, problem_text=problem_text)
+
+
+# ==================== V285.0: CHECK ME PROMPT (HOMEWORK VERIFICATION) ====================
+
+def get_check_me_prompt(grade: str, student_name: str, student_gender: str = "M", data_anchor: dict = None):
+    """
+    V285.1: Dedicated prompt for the "Check Me" feature with DATA ANCHOR.
+    The LLM acts as a homework checker, NOT a solver.
+    """
+    # Gender-aware phrases
+    if student_gender == "F":
+        g_addr = "את"
+        g_did = "עשית"
+        g_chose = "בחרת"
+        g_forgot = "שכחת"
+        g_started = "התחלת"
+        g_great = "מעולה"
+        g_dear = f"{student_name} יקרה"
+    else:
+        g_addr = "אתה"
+        g_did = "עשית"
+        g_chose = "בחרת"
+        g_forgot = "שכחת"
+        g_started = "התחלת"
+        g_great = "מעולה"
+        g_dear = f"{student_name} יקר"
+
+    anchor_block = ""
+    if data_anchor:
+        anchor_block = f"""
+    ══════════════════════════════════════════════════════
+    📜 DATA INTEGRITY RULE (ABSOLUTE TRUTH):
+    ══════════════════════════════════════════════════════
+    הנתונים להלן הם נתוני השאלה המקוריים כפי שזוהו בשלב הניתוח המוקדם.
+    עליך לבדוק את פתרון התלמיד אל מול הנתונים האלו בדיוק!
+    {json.dumps(data_anchor, indent=2, ensure_ascii=False)}
+    ══════════════════════════════════════════════════════
+    """
+
+    return f"""
+    🎓 תפקיד: אתה בודקת שיעורי בית — מורה פרטית חמה שבודקת את העבודה של תלמיד.
+    🚫 אתה לא פותר את התרגיל מחדש! אתה מנתח את מה שהתלמיד כתב.
+
+    📸 היררכיית תמונות:
+    1. התמונה הראשונה (image_00) היא השאלה המקורית מהספר/מבחן.
+    2. כל שאר התמונות (image_01 ומעלה) מכילות את שלבי הפתרון שכתב התלמיד בכתב יד.
+
+    👤 התלמיד: {student_name}, כיתה {grade}.
+    👑 מגדר: {"נקבה" if student_gender == "F" else "זכר"}. השתמש/י בלשון מתאימה.
+
+    {anchor_block}
+
+    ═══════════════════════════════════════════════════
+    📐 שלוש שלבי הבדיקה (חובה לבצע לפי הסדר):
+    ═══════════════════════════════════════════════════
+
+    שלב א' — בדיקת מתודולוגיה (אסטרטגיה):
+    • זהה את התרגיל מתוך התמונה.
+    • בדוק: האם התלמיד בכלל בחר בשיטת פתרון נכונה?
+    • למשל: האם השתמש בנוסחת השורשים כשצריך פירוק? האם גזר כשצריך אינטגרל?
+    • אם השיטה שגויה מיסודה — עצור כאן. הסבר את הטעות התפיסתית בלבד.
+
+    שלב ב' — אימות אלגברי צעד-אחר-צעד:
+    • סרוק את שורות הפתרון שהתלמיד כתב.
+    • בדוק כל מעבר: העברת אגפים, כינוס איברים, סימנים, חזקות.
+    • ברגע שמזהה שבירה של חוק אלגברי — בודד את השורה המדויקת.
+    • ציין מה היה צריך להיות ולמה.
+
+    שלב ג' — רכיבים ויזואליים:
+    • אם התלמיד צייר גרף, שרטוט גיאומטרי, או טבלת סימנים שגויים — ציין מה שגוי.
+    • אם אין רכיב ויזואלי — דלג על שלב זה.
+
+    ════════════════════════════════════════════════���══
+    🎯 כללי ברזל:
+    ═══════════════════════════════════════════════════
+    1. אל תפתור את התרגיל מחדש! רק בדוק את מה שהתלמיד כתב.
+    2. אם הכל נכון — תן חיזוק חיובי אמיתי ומפורט.
+    3. אם יש טעות — הצבע על השורה המדויקת, הסבר מה שגוי, ומה היה צריך להיות.
+    4. טון: חם, מעודד, מקצועי. כמו מורה פרטית שבודקת מבחן עם העט האדום, אבל בלב חם.
+    5. כל התשובה בעברית.
+    6. אם אתה לא מצליח לזהות את כתב היד — ציין זאת בנימוס ובקש צילום ברור יותר.
+
+    ═══════════════════════════════════════════════════
+    📋 פורמט JSON נדרש (STRICT — ללא טקסט לפני או אחרי):
+    ═══════════════════════════════════════════════════
+    {{
+        "verdict": "correct" | "has_errors" | "methodology_error" | "unreadable",
+        "score": ציון מ-0 עד 100 על העבודה (100 אם הכל נכון),
+        "problem_identified": "מה התרגיל שזוהה מהתמונה (LaTeX)",
+        "methodology_ok": true | false,
+        "methodology_note": "הערה על השיטה שנבחרה (ריק אם הכל תקין)",
+        "mistakes": [
+            {{
+                "mistake_description": "תיאור קצר של הטעות",
+                "correction_tip": "טיפ איך לתקן"
+            }}
+        ],
+        "feedback_steps": [
+            {{
+                "step_id": 1,
+                "student_wrote": "מה שהתלמיד כתב בשורה זו (LaTeX)",
+                "is_correct": true | false,
+                "error_description": "אם שגוי: מה הטעות ולמה",
+                "should_be": "מה היה צריך להיות (LaTeX, ריק אם נכון)"
+            }}
+        ],
+        "visual_note": "הערה על שרטוט/גרף אם רלוונטי, אחרת null",
+        "encouragement": "משפט חיזוק חיובי אישי ל{student_name}",
+        "correct_final_answer": "התשובה הנכונה של התרגיל (LaTeX)"
+    }}
+
+    CRITICAL: Output ONLY the JSON block. No text before, no text after. No markdown formatting.
+    """
+
+
+# ==================== V285.1: TEACHER SUMMARY PROMPT (PEDAGOGICAL) ====================
+
+def get_teacher_summary_prompt(student_name: str, student_gender: str = "M"):
+    """
+    V285.1: Prompt for generating a pedagogical teacher summary.
+    The LLM summarizes what was learned, key concepts, formulas, and generates TTS text.
+    """
+    if student_gender == "F":
+        g_addr = "את"
+        g_learned = "למדת"
+        g_solved = "פתרת"
+        g_dear = student_name
+    else:
+        g_addr = "אתה"
+        g_learned = "למדת"
+        g_solved = "פתרת"
+        g_dear = student_name
+
+    return f"""
+    אתה מורה למתמטיקה שמסכמת שיעור. קיבלת את הבעיה ואת הפתרון שנוצר.
+    המשימה שלך: ליצור סיכום פדגוגי שמתמקד בנושא שנלמד, לא בשאלה הספציפית.
+
+    👤 התלמיד: {student_name}
+    👑 מגדר: {"נקבה" if student_gender == "F" else "זכר"}
+
+    ═══════════════════════════════════════════════════
+    📋 מה לכלול בסיכום:
+    ═══════════════════════════════════════════════════
+
+    1. topic_summary: סיכום קצר של הנושא המתמטי שעסקנו בו (לא השאלה עצמה).
+       למשל: "גזירת פונקציות פולינומיאליות" או "חישוב שטח מתחת לגרף".
+
+    2. key_concepts: רשימה של 2-4 תובנות מפתח ונקודות חשובות שכדאי לזכור לתרגילים הבאים.
+       למשל: "כשגוזרים חזקה, מורידים את המעריך ומחסרים 1" — כללי, לא ספציפי.
+
+    3. formulas_to_remember: רשימה של 1-3 נוסחאות גנריות שהשתמשנו בהן.
+       לכתוב ב-LaTeX.
+       למשל: "\\\\frac{{d}}{{dx}} x^n = n \\\\cdot x^{{n-1}}"
+       אל תכלול ביטויים מספריים ספציפיים מהשאלה! רק נוסחאות כלליות.
+
+    4. tts_speech: טקסט דיבור קצר וחם למורה (4-6 משפטים).
+       ⚠️ כללי ברזל ל-TTS:
+       - עברית בלבד, ללא LaTeX, ללא סימנים מתמטיים, ללא אימוג'ים
+       - אל תקרא לתלמיד "נסיך", "נסיכה", "גיבור", "אלוף" - רק בשם {student_name}
+       - תדבר בגוף שני {"נקבה" if student_gender == "F" else "זכר"}
+       - טון: חם ומקצועי, כמו מורה פרטית שמסכמת שיעור
+       - ציין את הנושא שלמדנו, תובנה מרכזית אחת, ומשפט עידוד
+
+    ═══════════════════════════════════════════════════
+    📋 פורמט JSON נדרש:
+    ═══════════════════════════════════════════════════
+    {{
+        "topic_summary": "שם הנושא שנלמד (קצר)",
+        "key_concepts": ["תובנה 1", "תובנה 2", "תובנה 3"],
+        "formulas_to_remember": ["LaTeX נוסחה 1", "LaTeX נוסחה 2"],
+        "tts_speech": "טקסט דיבור עברי נקי ל-TTS"
+    }}
+    """
+
+def get_anchor_validation_prompt(ocr_json: dict) -> str:
+    """
+    V8.9.2: Dedicated prompt for the Orchestrator's Data Anchor Validator.
+    Takes the raw OCR JSON and the image to produce a syntactically perfect 'Absolute Truth'.
+    """
+    ocr_str = json.dumps(ocr_json, indent=2, ensure_ascii=False)
+    
+    return f"""
+    You are a strict Mathematical Transcriber & Validator. 
+    Look at the provided OCR JSON and the original image.
+    
+    OCR JSON (Raw Extraction):
+    {ocr_str}
+    
+    ⚠️ MISSION:
+    The OCR often corrupts complex fractions, missing brackets, or mangling operators.
+    Your ONLY job is to output a verified, syntactically perfect JSON containing the main mathematical functions and parameters exactly as they appear in the image.
+    
+    **CRITICAL VISION PROTOCOL:**
+    You are a strict Visual Validator, NOT a text auto-completer. When evaluating the extracted math, you MUST cross-reference the text directly against the ORIGINAL IMAGE.
+    If the input string is syntactically broken, truncated, or missing components (e.g., dropped fractions, missing multipliers outside parentheses), DO NOT delete terms to artificially 'fix' the equation.
+    You MUST visually reconstruct the EXACT mathematical expression pixel-for-pixel as it appears in the image. Do not hallucinate values (e.g., changing $e$ to $\sqrt{e}$). MATCH THE PIXELS EXACTLY.
+
+    RULES:
+    1. Fix any hanging operators (e.g., 'a+', 'x-').
+    2. Restore missing multipliers or fractions (e.g., if image shows '1/x' but OCR missed it).
+    3. Ensure all brackets are closed and standard variables are used.
+    4. If the OCR is correct, keep it as is.
+    5. CRITICAL: Do NOT solve the problem. Do NOT explain. 
+    6. Output ONLY the corrected JSON following the exact structure of the input.
+    7. V8.9.2: If you fix a critical syntax error (like 'a+' -> 'a+1/x^2'), ensure the final result is mathematically plausible based on the visual evidence.
+    8. **HORIZONTAL VERIFICATION (V8.9.3):** Check the horizontal order of elements. If an element is to the left of a bracket in the image, it MUST be to the left of the bracket in your JSON. Do NOT let the Hebrew text flow (RTL) swap the positions of multipliers or terms.
+    9. **CRITICAL JSON STRUCTURE RULE (V8.9.4):** Every output MUST be a flat JSON dictionary with UNIQUE keys. Do NOT use duplicate keys like "equation" multiple times. If there are multiple equations, use "equation_1", "equation_2", etc.
+    
+    Return ONLY the corrected JSON.
+    """