Fix: Clean production deployment with sse-starlette

.env.example

@@ -0,0 +1,5 @@
+GOOGLE_API_KEY=your-gemini-api-key-here
+
+# OCR Mode: development = Stitch & Strip engine (new, single-pass)
+#            production  = Triple-Pass legacy (safe, proven)
+OCR_STRIP_MODE=development

.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+.venv_fix/
+venv/
+env/
+ENV/
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Logs
+*.log
+server.log
+
+# Credentials
+.env
+serviceAccountKey_dev.json
+.google-credentials.json
+
+# Backups
+*.bak
+
+# Models & Large Binaries (Unused)
+phonikud-1.0.int8.onnx
+
+# Temporary / Cache
+.pytest_cache/
+test_results/
+temp/
+tmp/
+output_locus.txt
+
+# Media (Ignore test recordings)
+*.wav
+!welcome_speech_fixed.wav

Dockerfile

@@ -0,0 +1,31 @@
+# Dockerfile - V8.0 FIXED (Uvicorn + SymPy Support)
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# התקנת תלויות מערכת (פונטים לגרפים)
+RUN apt-get update && apt-get install -y \
+    libgl1 \
+    libglib2.0-0 \
+    fonts-dejavu-core \
+    fontconfig \
+    && rm -rf /var/lib/apt/lists/* \
+    && fc-cache -f -v
+
+# התקנת ספריות פייתון
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# העתקת קבצי האפליקציה
+COPY . .
+
+# יצירת משתמש לא-root (דרישת אבטחה)
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# חשיפת פורט 7860
+EXPOSE 7860
+
+# --- התיקון הקריטי: הרצה עם uvicorn ---
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,37 @@
+---
+title: BuddyMath
+emoji: 🧮
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+---
+
+# BuddyMath Server V3.1
+
+מורה פרטי AI למתמטיקה לתלמידים ישראליים 🇮🇱
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Health check |
+| `/health` | GET | Server status |
+| `/solve_stream` | POST | פתרון בעיה (SSE) |
+
+## Modes
+
+- `solve` - פתור לי
+- `teach_me` - למד אותי  
+- `check` - בדוק אותי
+
+## Parameters
+
+```
+image: File (required)
+grade: string (required)
+mode: string (default: "solve")
+student_name: string (default: "תלמיד/ה")
+student_gender: string (default: "male")
+user_note: string (optional)
+```

all_users.json

@@ -0,0 +1,34 @@
+{
+  "test_user_123": {
+    "last_seen": "2026-02-15T12:49:04.304849",
+    "id": "test_user_123"
+  },
+  "\u05d3\u05d5\u05ea\u05df": {
+    "last_seen": "2026-03-08T15:18:08.252094",
+    "id": "\u05d3\u05d5\u05ea\u05df"
+  },
+  "stress_user_1": {
+    "last_seen": "2026-02-27T12:03:10.171108",
+    "id": "stress_user_1"
+  },
+  "stress_user_2": {
+    "last_seen": "2026-02-27T12:03:10.221285",
+    "id": "stress_user_2"
+  },
+  "stress_user_3": {
+    "last_seen": "2026-02-27T12:03:10.263698",
+    "id": "stress_user_3"
+  },
+  "stress_user_4": {
+    "last_seen": "2026-02-27T12:03:10.332969",
+    "id": "stress_user_4"
+  },
+  "stress_user_0": {
+    "last_seen": "2026-02-27T12:03:10.382946",
+    "id": "stress_user_0"
+  },
+  "diagnostic": {
+    "last_seen": "2026-02-28T11:19:56.770735",
+    "id": "diagnostic"
+  }
+}

audio_generator.py

@@ -0,0 +1,267 @@
+# audio_generator.py - V273.0 (Google Cloud TTS - High Quality Hebrew)
+import asyncio
+import base64
+import os
+import tempfile
+import logging
+
+# Configure Logging
+logger = logging.getLogger(__name__)
+
+# ═══════════════════════════════════════════════════════════════
+# 🎙️ Google Cloud TTS Configuration
+# ═══════════════════════════════════════════════════════════════
+# 
+# קולות עבריים זמינים:
+# - he-IL-Wavenet-A (נקבה, איכות גבוהה) ⭐ מומלץ
+# - he-IL-Wavenet-B (זכר, איכות גבוהה)
+# - he-IL-Standard-A (נקבה, איכות רגילה)
+# - he-IL-Standard-B (זכר, איכות רגילה)
+#
+# Free Tier: 1 מיליון תווים/חודש (WaveNet: 1M, Standard: 4M)
+# ═══════════════════════════════════════════════════════════════
+
+GOOGLE_VOICE_NAME = "he-IL-Wavenet-A"  # Female, high quality
+GOOGLE_LANGUAGE_CODE = "he-IL"
+SPEAKING_RATE = 0.95  # מעט יותר איטי לבהירות
+PITCH = 1.0  # גובה קול רגיל
+
+# Fallback to edge-tts if Google Cloud not configured
+USE_EDGE_TTS_FALLBACK = True
+EDGE_TTS_VOICE = "he-IL-HilaNeural"
+
+from firebase_manager import firebase_manager  # V261.17
+
+
+def _is_google_cloud_configured() -> bool:
+    """בדיקה אם Google Cloud מוגדר"""
+    # Option 1: Environment variable
+    if os.environ.get("GOOGLE_APPLICATION_CREDENTIALS"):
+        return True
+    # Option 2: Check for credentials file in common locations
+    common_paths = [
+        "/app/google-credentials.json",
+        "./google-credentials.json",
+        os.path.expanduser("~/.config/gcloud/application_default_credentials.json")
+    ]
+    for path in common_paths:
+        if os.path.exists(path):
+            os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = path
+            return True
+    return False
+
+
+async def _generate_with_google_cloud(text: str, output_path: str) -> bool:
+    """
+    יצירת אודיו עם Google Cloud TTS
+    מחזיר True אם הצליח, False אם נכשל
+    """
+    try:
+        from google.cloud import texttospeech
+        
+        # Create client
+        client = texttospeech.TextToSpeechClient()
+        
+        # Build the voice request
+        voice = texttospeech.VoiceSelectionParams(
+            language_code=GOOGLE_LANGUAGE_CODE,
+            name=GOOGLE_VOICE_NAME,
+        )
+        
+        # Select the audio format
+        audio_config = texttospeech.AudioConfig(
+            audio_encoding=texttospeech.AudioEncoding.MP3,
+            speaking_rate=SPEAKING_RATE,
+            pitch=PITCH,
+        )
+        
+        # Build the synthesis input
+        synthesis_input = texttospeech.SynthesisInput(text=text)
+        
+        # Perform the text-to-speech request
+        logger.info(f"🎙️ Google Cloud TTS: Generating audio for {len(text)} chars...")
+        
+        # Run in thread pool to not block async
+        loop = asyncio.get_running_loop()
+        response = await loop.run_in_executor(
+            None,
+            lambda: client.synthesize_speech(
+                input=synthesis_input,
+                voice=voice,
+                audio_config=audio_config
+            )
+        )
+        
+        # Write the audio content to file
+        with open(output_path, "wb") as out:
+            out.write(response.audio_content)
+        
+        logger.info(f"✅ Google Cloud TTS: Audio saved to {output_path}")
+        return True
+        
+    except ImportError:
+        logger.warning("⚠️ google-cloud-texttospeech not installed. Run: pip install google-cloud-texttospeech")
+        return False
+    except Exception as e:
+        logger.error(f"❌ Google Cloud TTS failed: {e}")
+        return False
+
+
+async def _generate_with_edge_tts(text: str, output_path: str) -> bool:
+    """
+    יצירת אודיו עם edge-tts (Fallback)
+    """
+    try:
+        import edge_tts
+        
+        logger.info(f"🎙️ Edge TTS (Fallback): Generating audio...")
+        communicate = edge_tts.Communicate(text, EDGE_TTS_VOICE)
+        await communicate.save(output_path)
+        
+        logger.info(f"✅ Edge TTS: Audio saved to {output_path}")
+        return True
+        
+    except Exception as e:
+        logger.error(f"❌ Edge TTS failed: {e}")
+        return False
+
+
+async def generate_teacher_audio(text: str, output_path: str = None) -> str:
+    """
+    V273.0: יצירת אודיו עם Google Cloud TTS (איכות גבוהה)
+    
+    מנסה קודם Google Cloud TTS, אם לא מוגדר/נכשל → edge-tts fallback
+    
+    Returns: 
+        - Public URL (if Firebase upload success)
+        - Base64 string (fallback)
+        - None (if all failed)
+    """
+    try:
+        if not text:
+            return None
+        
+        # Clean text for TTS (remove emojis and special chars that cause issues)
+        clean_text = _clean_text_for_tts(text)
+        
+        if not clean_text:
+            return None
+            
+        logger.info(f"🎙️ TTS Request: {clean_text[:50]}...")
+        
+        # Determine output path
+        if output_path:
+            os.makedirs(os.path.dirname(output_path), exist_ok=True)
+            final_path = output_path
+        else:
+            timestamp = int(asyncio.get_event_loop().time() * 1000)
+            final_path = os.path.join(tempfile.gettempdir(), f"audio_{timestamp}.mp3")
+
+        # Try Google Cloud TTS first
+        success = False
+        if _is_google_cloud_configured():
+            success = await _generate_with_google_cloud(clean_text, final_path)
+        else:
+            logger.info("ℹ️ Google Cloud not configured, using Edge TTS")
+        
+        # Fallback to edge-tts
+        if not success and USE_EDGE_TTS_FALLBACK:
+            success = await _generate_with_edge_tts(clean_text, final_path)
+        
+        if not success:
+            logger.error("❌ All TTS methods failed")
+            return None
+
+        # Try Firebase Upload
+        try:
+            blob_name = f"audio/{os.path.basename(final_path)}"
+            loop = asyncio.get_running_loop()
+            
+            public_url = await loop.run_in_executor(
+                None, 
+                lambda: firebase_manager.upload_file(final_path, blob_name)
+            )
+            
+            if public_url:
+                logger.info(f"☁️ Firebase URL: {public_url}")
+                # Clean up local file
+                if not output_path:
+                    os.remove(final_path)
+                return public_url
+        except Exception as fb_err:
+            logger.warning(f"⚠️ Firebase upload failed ({fb_err}). Using Base64.")
+
+        # Fallback: Return Base64
+        with open(final_path, "rb") as audio_file:
+            audio_bytes = audio_file.read()
+            audio_base64 = base64.b64encode(audio_bytes).decode('utf-8')
+            
+        # Clean up temp file
+        if not output_path:
+            os.remove(final_path)
+            
+        return audio_base64
+
+    except Exception as e:
+        logger.error(f"❌ TTS Generation Failed: {e}")
+        return None
+
+
+def _clean_text_for_tts(text: str) -> str:
+    """
+    ניקוי טקסט לפני TTS - הסרת אימוג'ים וסימנים בעייתיים
+    """
+    import re
+    
+    if not text:
+        return ""
+    
+    # Remove emojis
+    emoji_pattern = re.compile("["
+        u"\U0001F600-\U0001F64F"  # emoticons
+        u"\U0001F300-\U0001F5FF"  # symbols & pictographs
+        u"\U0001F680-\U0001F6FF"  # transport & map symbols
+        u"\U0001F1E0-\U0001F1FF"  # flags
+        u"\U00002702-\U000027B0"
+        u"\U000024C2-\U0001F251"
+        "]+", flags=re.UNICODE)
+    
+    clean = emoji_pattern.sub('', text)
+    
+    # Remove multiple spaces
+    clean = re.sub(r'\s+', ' ', clean)
+    
+    # Remove LaTeX remnants that might have slipped through
+    clean = clean.replace('$', '').replace('\\', '')
+    
+    return clean.strip()
+
+
+# ═══════════════════════════════════════════════════════════════
+# 🧪 Testing
+# ═══════════════════════════════════════════════════════════════
+
+if __name__ == "__main__":
+    async def main():
+        text = """
+        איזה יופי של תרגיל! היינו צריכים למצוא את נקודות הקיצון של הפונקציה.
+        השתמשנו בנגזרת ראשונה כדי למצוא איפה השיפוע מתאפס.
+        הטריק לזכור - נגזרת אפס תמיד מסמנת נקודת קיצון אפשרית.
+        כל הכבוד על ההתמדה!
+        """
+        
+        print(f"🎙️ Testing TTS...")
+        print(f"📝 Text length: {len(text)} chars")
+        print(f"☁️ Google Cloud configured: {_is_google_cloud_configured()}")
+        
+        result = await generate_teacher_audio(text)
+        
+        if result:
+            if result.startswith("http"):
+                print(f"✅ Got URL: {result}")
+            else:
+                print(f"✅ Got Base64: {len(result)} chars")
+        else:
+            print("❌ TTS failed")
+    
+    asyncio.run(main())

config.py

@@ -0,0 +1,39 @@
+# config.py - V1.0 (Central Config)
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Determine Environment
+# Defaults to PROD if not specified, for safety
+ENV = os.getenv("ENV", "production").lower()
+IS_PRODUCTION = ENV == "production"
+
+# Firebase Configuration
+if IS_PRODUCTION:
+    # PROD: bussymath
+    FIREBASE_CREDENTIALS_PATH = os.path.join(os.path.dirname(__file__), "serviceAccountKey.json")
+    STORAGE_BUCKET = "bussymath.firebasestorage.app"
+    PROJECT_ID = "bussymath"
+else:
+    # DEV: buddy-math-dev
+    # The dev bucket buddy-math-dev is returning 404, so we must use the prod bucket AND prod key
+    FIREBASE_CREDENTIALS_PATH = os.path.join(os.path.dirname(__file__), "serviceAccountKey.json")
+    
+    STORAGE_BUCKET = "bussymath.firebasestorage.app"
+    PROJECT_ID = "bussymath"
+
+# Server Configuration
+HOST = "0.0.0.0"
+PORT = 8000 if not IS_PRODUCTION else 7860 # HF Spaces/Cloud Run often use 7860 or PORT env
+
+# V3.1.2: Adaptive Failure Mode - Confidence Thresholds
+# V3.1.3: Recalibrated (Hard Floor 0.55)
+# V4.2.11: Lowered for DEV to unblock geometry diagnostics
+CONFIDENCE_THRESHOLD_HIGH = 0.75
+CONFIDENCE_THRESHOLD_MEDIUM = 0.55 if IS_PRODUCTION else 0.01
+
+print(f"[CONFIG] Loading {ENV.upper()} configuration.")
+print(f"[CONFIG] Project: {PROJECT_ID}")
+print(f"[CONFIG] Bucket: {STORAGE_BUCKET}")

cost_tracker.py

@@ -0,0 +1,82 @@
+PRICING = { "input": 0.10, "output": 0.40 }
+
+class CostTracker:
+    def __init__(self):
+        self.input_tokens = 0
+        self.output_tokens = 0
+
+    def add(self, usage_metadata):
+        if usage_metadata:
+            self.input_tokens += getattr(usage_metadata, 'prompt_token_count', 0)
+            self.output_tokens += getattr(usage_metadata, 'candidates_token_count', 0)
+
+    def add_manual(self, inp, out):
+        self.input_tokens += inp
+        self.output_tokens += out
+
+    def get_cost(self):
+        return (self.input_tokens / 1e6 * PRICING["input"]) + (self.output_tokens / 1e6 * PRICING["output"])
+
+    def get_summary(self): # ✅ הפונקציה שהייתה חסרה
+        return {
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "cost_usd": self.get_cost()
+        }
+
+    def print_report(self):
+        print(f"💰 COST: ${self.get_cost():.6f}")
+
+# Static Logger
+import os
+import json
+import time
+import tempfile
+
+# V260.9: Smarter logging path
+def get_log_file_path():
+    base_dir = os.path.join(os.getcwd(), "logs")
+    # Try creating/accessing local logs dir
+    try:
+        if not os.path.exists(base_dir):
+            os.makedirs(base_dir)
+        # Test write permission
+        test_file = os.path.join(base_dir, ".test_write")
+        with open(test_file, "w") as f: f.write("ok")
+        os.remove(test_file)
+        return os.path.join(base_dir, "usage.jsonl")
+    except (PermissionError, OSError):
+        # Fallback to temp
+        return os.path.join(tempfile.gettempdir(), "buddy_math_usage.jsonl")
+
+LOG_FILE = get_log_file_path()
+LOG_DIR = os.path.dirname(LOG_FILE)
+
+def log_api_usage(usage_metadata, source="unknown"):
+    """Log API usage to proper location"""
+    if not usage_metadata:
+        return
+
+    try:
+        # LOG_DIR check is now redundant but safe
+        if not os.path.exists(LOG_DIR):
+            os.makedirs(LOG_DIR, exist_ok=True)
+            
+        entry = {
+            "timestamp": time.time(),
+            "source": source,
+            "input_tokens": getattr(usage_metadata, 'prompt_token_count', 0),
+            "output_tokens": getattr(usage_metadata, 'candidates_token_count', 0),
+            "total_tokens": getattr(usage_metadata, 'total_token_count', 0)
+        }
+        
+        with open(LOG_FILE, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+            
+        # Also print to stdout for immediate visibility in console logs
+        print(f"💰 [USAGE] {source}: In={entry['input_tokens']}, Out={entry['output_tokens']}")
+        
+    except Exception as e:
+        # Fallback to pure stdout if file logging completely fails
+        print(f"💰 [USAGE-STDOUT only] {source}: In={getattr(usage_metadata, 'prompt_token_count', 0)}, Out={getattr(usage_metadata, 'candidates_token_count', 0)}")
+        print(f"⚠️ [USAGE LOG ERROR] Failed to log to file {LOG_FILE}: {e}")

curriculum_engine.py

@@ -0,0 +1,115 @@
+# curriculum_engine.py - V4.0 (Curriculum Oracle)
+# Defines pedagogical boundaries according to the Israeli Ministry of Education (Mafmar).
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+CURRICULUM_RULES = {
+    # grade: { blacklist: [operators], whitelist: [operators], descriptions: {operator: hebrew_name} }
+    7: {
+        "blacklist": ["SYSTEM_OF_EQUATIONS", "QUADRATIC_EQUATION", "DERIVATIVE", "INTEGRAL", "TRIGONOMETRY"],
+        "whitelist": ["LINEAR_EQUATION", "FRACTIONS", "EXPONENTS_BASIC", "PERCENTAGES"],
+        "descriptions": {
+            "SYSTEM_OF_EQUATIONS": "מערכת משוואות בשני נעלמים",
+            "QUADRATIC_EQUATION": "משוואה ריבועית",
+            "DERIVATIVE": "נגזרות",
+            "TRIGONOMETRY": "טריגונומטריה"
+        }
+    },
+    8: {
+        "blacklist": ["QUADRATIC_EQUATION", "DERIVATIVE", "INTEGRAL", "TRIG_Trig_ADVANCED"],
+        "whitelist": ["LINEAR_EQUATION", "SYSTEM_OF_EQUATIONS", "BASIC_GEOMETRY", "PYTHAGOREAN_THEOREM"],
+        "descriptions": {
+            "QUADRATIC_EQUATION": "משוואה ריבועית",
+            "DERIVATIVE": "נגזרות"
+        }
+    },
+    9: {
+        "blacklist": ["DERIVATIVE", "INTEGRAL", "LOGARITHM"],
+        "whitelist": ["QUADRATIC_EQUATION", "SYSTEM_OF_EQUATIONS", "SIMILAR_TRIANGLES", "CIRCLE_BASIC"],
+        "descriptions": {
+            "DERIVATIVE": "נגזרות",
+            "LOGARITHM": "לוגריתמים"
+        }
+    },
+    10: {
+        "blacklist": ["INTEGRAL_ADVANCED", "VECTORS"],
+        "whitelist": ["DERIVATIVE_POLYNOMIAL", "TRIGONOMETRY_BASIC", "CIRCLE_EQUATION_BASIC"],
+        "descriptions": {
+            "INTEGRAL_ADVANCED": "אינטגרלים מורכבים",
+            "VECTORS": "ווקטורים"
+        }
+    },
+    # V286.0: Grade 11 — 4 יח"ל focus
+    11: {
+        "blacklist": ["VECTORS_3D", "ADVANCED_INTEGRATION", "SOLID_GEOMETRY_ADVANCED"],
+        "whitelist": ["DERIVATIVE", "TRIGONOMETRY", "LOGARITHM", "SEQUENCES", "COMPLEX_NUMBERS_BASIC",
+                      "FUNCTION_ANALYSIS", "PROBABILITY_BASIC", "CIRCLE_EQUATION"],
+        "descriptions": {
+            "VECTORS_3D": "וקטורים במרחב",
+            "ADVANCED_INTEGRATION": "אינטגרציה מתקדמת"
+        }
+    },
+    # V286.0: Grade 12 / 5 יח"ל — full access
+    12: {
+        "blacklist": [],
+        "whitelist": ["DERIVATIVE", "INTEGRAL", "INTEGRAL_ADVANCED", "TRIGONOMETRY",
+                      "TRIGONOMETRY_ADVANCED", "LOGARITHM", "SEQUENCES", "COMPLEX_NUMBERS",
+                      "COMPLEX_ANALYSIS", "VECTORS", "VECTORS_3D", "FUNCTION_ANALYSIS",
+                      "PROBABILITY", "COMBINATORICS", "SOLID_GEOMETRY", "LIMITS",
+                      "OPTIMIZATION", "INDUCTION", "GEOMETRY_ANALYTIC", "CIRCLE_EQUATION"],
+        "descriptions": {}
+    }
+}
+
+def get_allowed_math_operators(grade_str: str, level: str = "4", topic: str = "GENERAL") -> dict:
+    """
+    Returns the pedagogical boundary rules for a specific student profile.
+    
+    Args:
+        grade_str: Student grade (e.g. "7", "י", "י\"א")
+        level: Units level for high school (3, 4, 5)
+        topic: Current mathematical topic
+        
+    Returns:
+        dict: { "allowed": [], "forbidden": [], "reason_map": {} }
+    """
+    # 1. Normalize grade
+    from topic_taxonomy import _extract_grade_number
+    grade_num = _extract_grade_number(grade_str)
+    
+    print(f"🎓 [CURRICULUM] Fetching rules for Grade {grade_num}, Level {level} units")
+    
+    rules = CURRICULUM_RULES.get(grade_num, {
+        "blacklist": [],
+        "whitelist": ["GENERAL"],
+        "descriptions": {}
+    })
+    
+    # 2. Add Level-specific tweaks (Epic V4.1+)
+    if grade_num >= 10:
+        if level == "3":
+            rules["blacklist"].extend(["COMPLEX_ANALYSIS", "IMPLICIT_DERIVATIVE"])
+        elif level == "5":
+            rules["whitelist"].extend(["COMPLEX_ANALYSIS", "ADVANCED_CALCULUS"])
+            
+    return {
+        "allowed": rules.get("whitelist", []),
+        "forbidden": rules.get("blacklist", []),
+        "reason_map": rules.get("descriptions", {})
+    }
+
+def is_operator_allowed(operator: str, grade_str: str, level: str = "4") -> bool:
+    """Helper to check a single operator."""
+    rules = get_allowed_math_operators(grade_str, level)
+    if operator in rules["forbidden"]:
+        return False
+    return True
+
+if __name__ == "__main__":
+    # Test
+    print(get_allowed_math_operators("7"))
+    print(is_operator_allowed("DERIVATIVE", "7"))
+    print(is_operator_allowed("SYSTEM_OF_EQUATIONS", "7"))
+    print(is_operator_allowed("SYSTEM_OF_EQUATIONS", "8"))

curriculum_israel.py

@@ -0,0 +1,579 @@
+# curriculum_israel.py - תוכנית הלימודים במתמטיקה לפי משרד החינוך
+# ====================================================================
+# מותאם לכל כיתה ורמה (ז'-י"ב) לפי תוכנית הלימודים הישראלית
+# כל התוכן בעברית!
+
+"""
+מבנה מערכת החינוך בישראל - מתמטיקה:
+======================================
+חטיבת ביניים (ז'-ט'): רמה א' מצטיינים, רמה א' רגילה, רמה ב'
+חטיבה עליונה (י'-י"ב): 3 יח"ל, 4 יח"ל, 5 יח"ל
+"""
+
+# =============================================================================
+# פרופילי כיתות - מה לומדים בכל כיתה
+# =============================================================================
+
+GRADE_PROFILES = {
+    
+    # ═══════════════════════════════════════════════════════════════════════
+    # כיתה ז'
+    # ═══════════════════════════════════════════════════════════════════════
+    "ז": {
+        "name": "כיתה ז'",
+        "age_range": "12-13",
+        "levels": {
+            "א_מצטיינים": {
+                "name": "רמה א' מצטיינים",
+                "topics": [
+                    "מספרים שליליים וחיוביים",
+                    "חזקות ושורשים",
+                    "ביטויים אלגבריים",
+                    "משוואות ממעלה ראשונה",
+                    "יחס ופרופורציה",
+                    "אחוזים",
+                    "גאומטריה: זוויות, משולשים, מרובעים",
+                    "שטח והיקף",
+                    "נפח ושטח פנים",
+                    "סטטיסטיקה תיאורית",
+                ],
+                "expected_level": "מתקדם - שאלות מאתגרות, חשיבה מתמטית",
+                "explanation_style": "הסברים מעמיקים עם הרחבות",
+            },
+            "א_רגילה": {
+                "name": "רמה א' רגילה",
+                "topics": [
+                    "מספרים שליליים וחיוביים",
+                    "חזקות בסיסיות",
+                    "ביטויים אלגבריים פשוטים",
+                    "משוואות ממעלה ראשונה",
+                    "יחס ופרופורציה",
+                    "אחוזים",
+                    "גאומטריה בסיסית",
+                    "שטח והיקף",
+                ],
+                "expected_level": "סטנדרטי - בניית בסיס חזק",
+                "explanation_style": "הסברים ברורים עם דוגמאות רבות",
+            },
+            "ב": {
+                "name": "רמה ב'",
+                "topics": [
+                    "מספרים שלמים",
+                    "פעולות חשבון בסיסיות",
+                    "שברים ומספרים עשרוניים",
+                    "אחוזים פשוטים",
+                    "גאומטריה בסיסית",
+                    "מדידה",
+                ],
+                "expected_level": "בסיסי - חיזוק יסודות",
+                "explanation_style": "הסברים פשוטים מאוד, צעד אחר צעד, עם הרבה עידוד",
+            },
+        },
+    },
+    
+    # ═══════════════════════════════════════════════════════════════════════
+    # כיתה ח'
+    # ═══════════════════════════════════════════════════════════════════════
+    "ח": {
+        "name": "כיתה ח'",
+        "age_range": "13-14",
+        "levels": {
+            "א_מצטיינים": {
+                "name": "רמה א' מצטיינים",
+                "topics": [
+                    "פונקציה לינארית",
+                    "מערכת משוואות",
+                    "אי-שוויונות",
+                    "משולשים: חפיפה ודמיון",
+                    "משפט פיתגורס",
+                    "מעגל",
+                    "הסתברות",
+                    "סטטיסטיקה",
+                ],
+                "expected_level": "מתקדם - הכנה לתיכון ברמה גבוהה",
+                "explanation_style": "הסברים מעמיקים עם קישורים בין נושאים",
+            },
+            "א_רגילה": {
+                "name": "רמה א' רגילה",
+                "topics": [
+                    "פונקציה לינארית",
+                    "מערכת משוואות פשוטה",
+                    "אי-שוויונות פשוטים",
+                    "משולשים וחפיפה",
+                    "משפט פיתגורס",
+                    "הסתברות בסיסית",
+                ],
+                "expected_level": "סטנדרטי",
+                "explanation_style": "הסברים ברורים ומסודרים",
+            },
+            "ב": {
+                "name": "רמה ב'",
+                "topics": [
+                    "משוואות פשוטות",
+                    "גרפים בסיסיים",
+                    "גאומטריה: משולשים ומרובעים",
+                    "מדידה ושטחים",
+                    "הסתברות פשוטה",
+                ],
+                "expected_level": "בסיסי",
+                "explanation_style": "הסברים פשוטים עם דוגמאות מחיי היומיום",
+            },
+        },
+    },
+    
+    # ═══════════════════════════════════════════════════════════════════════
+    # כיתה ט'
+    # ═══════════════════════════════════════════════════════════════════════
+    "ט": {
+        "name": "כיתה ט'",
+        "age_range": "14-15",
+        "levels": {
+            "א_מצטיינים": {
+                "name": "רמה א' מצטיינים",
+                "topics": [
+                    "פונקציה ריבועית",
+                    "משוואה ריבועית ונוסחת השורשים",
+                    "אי-שוויון ריבועי",
+                    "דמיון משולשים מתקדם",
+                    "משפט תאלס",
+                    "טריגונומטריה במשולש ישר-זווית",
+                    "מעגל: זוויות היקפיות ומרכזיות",
+                    "הסתברות מתקדמת",
+                ],
+                "expected_level": "מתקדם - הכנה ל-5 יח\"ל",
+                "explanation_style": "הסברים מעמיקים עם הוכחות",
+            },
+            "א_רגילה": {
+                "name": "רמה א' רגילה",
+                "topics": [
+                    "פונקציה ריבועית",
+                    "משוואה ריבועית",
+                    "דמיון משולשים",
+                    "טריגונומטריה בסיסית",
+                    "מעגל",
+                ],
+                "expected_level": "סטנדרטי - הכנה ל-4 יח\"ל",
+                "explanation_style": "הסברים מסודרים עם תרגול",
+            },
+            "ב": {
+                "name": "רמה ב'",
+                "topics": [
+                    "פונקציה לינארית",
+                    "משוואות פשוטות",
+                    "גאומטריה בסיסית",
+                    "הסתברות פשוטה",
+                ],
+                "expected_level": "בסיסי - הכנה ל-3 יח\"ל",
+                "explanation_style": "הסברים פשוטים ומעודדים",
+            },
+        },
+    },
+    
+    # ═══════════════════════════════════════════════════════════════════════
+    # כיתה י' - תחילת לימודי בגרות
+    # ═══════════════════════════════════════════════════════════════════════
+    "י": {
+        "name": "כיתה י'",
+        "age_range": "15-16",
+        "levels": {
+            "3_יחידות": {
+                "name": "3 יחידות לימוד",
+                "topics": [
+                    "אלגברה: משוואות ואי-שוויונות",
+                    "פונקציות: לינארית וריבועית",
+                    "גאומטריה אנליטית בסיסית",
+                    "טריגונומטריה במשולש",
+                    "סטטיסטיקה והסתברות",
+                ],
+                "bagrut_format": True,
+                "expected_level": "בגרות 3 יח\"ל - דגש על יישומים",
+                "explanation_style": "הסברים ברורים בפורמט בגרות, דגש על שאלות מילוליות",
+            },
+            "4_יחידות": {
+                "name": "4 יחידות לימוד",
+                "topics": [
+                    "אלגברה מתקד��ת",
+                    "פונקציות: ריבועית, שורש, ערך מוחלט",
+                    "גאומטריה אנליטית",
+                    "טריגונומטריה: משפטי סינוסים וקוסינוסים",
+                    "סדרות חשבוניות והנדסיות",
+                    "הסתברות",
+                ],
+                "bagrut_format": True,
+                "expected_level": "בגרות 4 יח\"ל - רמה בינונית-גבוהה",
+                "explanation_style": "הסברים מפורטים בפורמט בגרות עם נימוקים",
+            },
+            "5_יחידות": {
+                "name": "5 יחידות לימוד",
+                "topics": [
+                    "אלגברה מתקדמת",
+                    "פונקציות מורכבות",
+                    "גאומטריה אנליטית מתקדמת",
+                    "טריגונומטריה מתקדמת",
+                    "סדרות והוכחות",
+                    "מבוא לחשבון דיפרנציאלי",
+                ],
+                "bagrut_format": True,
+                "expected_level": "בגרות 5 יח\"ל - רמה גבוהה",
+                "explanation_style": "הסברים מעמיקים עם הוכחות ונימוקים מלאים",
+            },
+        },
+    },
+    
+    # ═══════════════════════════════════════════════════════════════════════
+    # כיתה י"א
+    # ═══════════════════════════════════════════════════════════════════════
+    "יא": {
+        "name": "כיתה י\"א",
+        "age_range": "16-17",
+        "levels": {
+            "3_יחידות": {
+                "name": "3 יחידות לימוד",
+                "topics": [
+                    "חזרה והעמקה באלגברה",
+                    "פונקציות ויישומים",
+                    "סטטיסטיקה מתקדמת",
+                    "הסתברות",
+                    "גאומטריה במישור",
+                ],
+                "bagrut_format": True,
+                "expected_level": "הכנה לבגרות 3 יח\"ל",
+                "explanation_style": "תרגול בגרויות עם הסברים",
+            },
+            "4_יחידות": {
+                "name": "4 יחידות לימוד",
+                "topics": [
+                    "חדו\"א: נגזרות",
+                    "חקירת פונקציות פולינומיאליות",
+                    "גאומטריה אנליטית: ישר ומעגל",
+                    "טריגונומטריה מתקדמת",
+                    "סדרות",
+                    "הסתברות מותנית",
+                ],
+                "bagrut_format": True,
+                "expected_level": "בגרות 4 יח\"ל",
+                "explanation_style": "פורמט בגרות מלא עם כל הנימוקים",
+            },
+            "5_יחידות": {
+                "name": "5 יחידות לימוד",
+                "topics": [
+                    "חדו\"א: נגזרות ואינטגרלים",
+                    "חקירת פונקציות מורכבות",
+                    "גאומטריה אנליטית מתקדמת",
+                    "מספרים מרוכבים",
+                    "הסתברות מתקדמת",
+                    "אינדוקציה",
+                ],
+                "bagrut_format": True,
+                "expected_level": "בגרות 5 יח\"ל - רמה גבוהה",
+                "explanation_style": "הוכחות מלאות, נימוקים פורמליים",
+            },
+        },
+    },
+    
+    # ═══════════════════════════════════════════════════════════════════════
+    # כיתה י"ב
+    # ═══════════════════════════════════════════════════════════════════════
+    "יב": {
+        "name": "כיתה י\"ב",
+        "age_range": "17-18",
+        "levels": {
+            "3_יחידות": {
+                "name": "3 יחידות לימוד",
+                "topics": [
+                    "חזרה מקיפה לבגרות",
+                    "פתרון בגרויות קודמות",
+                    "כל נושאי 3 יח\"ל",
+                ],
+                "bagrut_format": True,
+                "expected_level": "הכנה אינטנסיבית לבגרות",
+                "explanation_style": "פתרון בגרויות עם טיפים למב��ן",
+            },
+            "4_יחידות": {
+                "name": "4 יחידות לימוד",
+                "topics": [
+                    "חזרה מקיפה לבגרות",
+                    "חדו\"א: אינטגרלים ושטחים",
+                    "גאומטריה אנליטית מתקדמת",
+                    "פתרון בגרויות",
+                ],
+                "bagrut_format": True,
+                "expected_level": "הכנה אינטנסיבית לבגרות 4 יח\"ל",
+                "explanation_style": "פתרון מבחנים עם אסטרטגיות",
+            },
+            "5_יחידות": {
+                "name": "5 יחידות לימוד",
+                "topics": [
+                    "חדו\"א מתקדם",
+                    "אינטגרלים ויישומים",
+                    "משוואות דיפרנציאליות פשוטות",
+                    "גאומטריה אנליטית: אליפסה והיפרבולה",
+                    "מספרים מרוכבים מתקדם",
+                    "וקטורים",
+                    "הכנה לבגרות",
+                ],
+                "bagrut_format": True,
+                "expected_level": "הכנה אינטנסיבית לבגרות 5 יח\"ל",
+                "explanation_style": "פתרון מלא עם כל ההוכחות והנימוקים",
+            },
+        },
+    },
+}
+
+
+# =============================================================================
+# כללי בגרות לפי נושא (מתוך מסמך משרד החינוך)
+# =============================================================================
+
+BAGRUT_RULES = {
+    "גאומטריה": {
+        "חובה": [
+            "לנמק בהגדרות ומשפטים גאומטריים בלבד",
+            "לציין את המשולש/מרובע שאליו מתייחסים",
+            "להגדיר זווית ב-3 אותיות או אות אחת + שם המשולש",
+        ],
+        "לא_נדרש": [
+            "'כל גודל שווה לעצמו'",
+            "'כלל החיבור'",
+            "'כלל החיסור'",
+            "לרשום שקטעים מקבילים אם כתבנו שישרים מקבילים",
+        ],
+        "נימוקים_נפוצים": [
+            "נתון",
+            "זוויות מתחלפות בין ישרים מקבילים",
+            "זוויות חד-צדדיות משלימות ל-180°",
+            "זוויות קודקודיות שוות",
+            "סכום זוויות במשולש = 180°",
+            "משפט פיתגורס",
+            "משפט תאלס",
+            "חפיפת משולשים (צ.ז.צ / ז.צ.ז / צ.צ.צ)",
+            "דמיון משולשים (ז.ז / צ.ז.צ / צ.צ.צ)",
+        ],
+    },
+    
+    "חדוא": {
+        "חובה": [
+            "תחום הגדרה: לכתוב אי-שוויון נכון (חזק ≠ חלש)",
+            "באינטגרל: לכתוב פונקציה קדומה + הצבת גבולות",
+            "לכתוב dx וסוגריים במקום הנכון",
+        ],
+        "לא_נדרש": [
+            "לפרט חישובי גבולות לאסימפטוטות",
+            "לפרט הצבות בקביעת סוג קיצון",
+        ],
+        "טעויות_קריטיות": [
+            "תחום הגדרה עם כיוון אי-שוויון שגוי = 0 נקודות",
+            "אינטגרל ללא פונקציה קדומה = 0 נקודות",
+        ],
+    },
+    
+    "הסתברות": {
+        "חובה": [
+            "להגדיר כל מאורע (A, B) במילים",
+            "בהסתברות מותנית: לרשום P(B|A) ואז להציב בנוסחה",
+            "להראות כל חישוב",
+        ],
+    },
+    
+    "אלגברה": {
+        "חובה": [
+            "להראות דרך פתרון מלאה",
+            "תשובה סופית ללא דרך = לא נבדק",
+            "במשוואה ריבועית: להראות נוסחה או פירוק",
+        ],
+    },
+    
+    "אינדוקציה": {
+        "חובה": [
+            "משפטי קישור: 'נבדוק עבור n=1', 'נניח עבור n=k', 'נוכיח עבור n=k+1'",
+            "לרשום נכון מה צריך להוכיח",
+        ],
+        "טעויות_קריטיות": [
+            "'נניח לכל n טבעי' = הורדה של 20%",
+            "רישום שגוי של מה שצריך להוכיח = לא בודקים המשך",
+        ],
+    },
+    
+    "טריגונומטריה": {
+        "4_יחידות": [
+            "לפשט sin(180°-x) וכדומה",
+        ],
+        "5_יחידות": [
+            "לעבוד ברדיאנים בלבד (מעלות = 0 נקודות)",
+        ],
+    },
+
+    "סדרות": {
+        "חובה": [
+            "לרשום את סוג הסדרה (חשבונית/הנדסית) ואת הנוסחה הכללית",
+            "בסכום חלקי: לרשום את הנוסחה ולהציב",
+            "בהוכחת נוסחה: להשתמש באינדוקציה מלאה",
+        ],
+    },
+
+    "מספרים_מרוכבים": {
+        "חובה": [
+            "לרשום z בצורה אלגברית (a+bi) וגם בצורה טריגונומטרית אם נדרש",
+            "להראות חישוב מודולוס וארגומנט",
+            "בשורשים: להשתמש בנוסחת דה-מואבר ולרשום את כל השורשים",
+        ],
+    },
+
+    "וקטורים": {
+        "חובה": [
+            "לרשום וקטור כצמד מוסדר",
+            "במכפלה סקלרית: להראות חישוב בשתי דרכים (קואורדינטות וזווית)",
+            "להוכיח ניצבות דרך מכפלה סקלרית = 0",
+        ],
+    },
+
+    "סטטיסטיקה": {
+        "חובה": [
+            "לרשום את נוסחת הממוצע/שונות/סטיית תקן",
+            "בהתפלגות נורמלית: לציין Z-score ולהשתמש בטבלאות",
+            "בהתפלגות בינומית: לרשום n, p, ולהציב בנוסחה",
+        ],
+    },
+}
+
+
+# =============================================================================
+# סגנונות הסבר לפי גיל
+# =============================================================================
+
+EXPLANATION_STYLES = {
+    "חטיבת_ביניים": {
+        "שפה": "פשוטה ונגישה",
+        "דוגמאות": "מחיי היומיום",
+        "עידוד": "הרבה חיזוקים חיוביים",
+        "קצב": "איטי ומפורט",
+        "אימוג'ים": "כן, בכמות מתונה",
+    },
+    "חטיבה_עליונה_3_יחידות": {
+        "שפה": "ברורה עם מונחים מתמטיים בסיסיים",
+        "דוגמאות": "יישומיות",
+        "עידוד": "מתון",
+        "קצב": "רגיל",
+        "פורמט": "בגרות",
+    },
+    "חטיבה_עליונה_4_יחידות": {
+        "שפה": "מתמטית עם הסברים",
+        "דוגמאות": "מתמטיות",
+        "עידוד": "ממוקד",
+        "קצב": "רגיל-מהיר",
+        "פורמט": "בגרות מלא",
+    },
+    "חטיבה_עליונה_5_יחידות": {
+        "שפה": "מתמטית פורמלית",
+        "דוגמאות": "הוכחות ונימוקים",
+        "עידוד": "מינימלי",
+        "קצב": "מהיר",
+        "פורמט": "בגרות מלא עם הוכחות",
+    },
+}
+
+
+# =============================================================================
+# פונקציות עזר
+# =============================================================================
+
+def get_grade_profile(grade: str, level: str = None) -> dict:
+    """מחזיר פרופיל כיתה ורמה"""
+    
+    # נרמול שם הכיתה
+    grade_map = {
+        "ז'": "ז", "ז": "ז", "7": "ז",
+        "ח'": "ח", "ח": "ח", "8": "ח",
+        "ט'": "ט", "ט": "ט", "9": "ט",
+        "י'": "י", "י": "י", "10": "י",
+        "י\"א": "יא", "יא": "יא", "11": "יא",
+        "י\"ב": "יב", "יב": "יב", "12": "יב",
+    }
+    
+    grade_key = grade_map.get(grade, "י")
+    profile = GRADE_PROFILES.get(grade_key, GRADE_PROFILES["י"])
+    
+    # נרמול רמה
+    if level:
+        level_map = {
+            "3 יח\"ל": "3_יחידות", "3 יחידות": "3_יחידות", "3": "3_יחידות",
+            "4 יח\"ל": "4_יחידות", "4 יחידות": "4_יחידות", "4": "4_יחידות",
+            "5 יח\"ל": "5_יחידות", "5 יחידות": "5_יחידות", "5": "5_יחידות",
+            "רמה א' מצטיינים": "א_מצטיינים", "מצטיינים": "א_מצטיינים",
+            "רמה א' רגילה": "א_רגילה", "רגילה": "א_רגילה",
+            "רמה ב'": "ב", "ב": "ב",
+        }
+        level_key = level_map.get(level, list(profile["levels"].keys())[0])
+        level_profile = profile["levels"].get(level_key, list(profile["levels"].values())[0])
+    else:
+        level_profile = list(profile["levels"].values())[0]
+    
+    return {
+        "grade": profile,
+        "level": level_profile,
+    }
+
+
+def get_explanation_style(grade: str, level: str = None) -> dict:
+    """מחזיר סגנון הסבר מותאם"""
+    
+    profile = get_grade_profile(grade, level)
+    
+    # זיהוי אם חטיבת ביניים או עליונה
+    if grade in ["ז", "ז'", "ח", "ח'", "ט", "ט'", "7", "8", "9"]:
+        return EXPLANATION_STYLES["חטיבת_ביניים"]
+    
+    # חטיבה עליונה - לפי יחידות
+    level_name = profile["level"].get("name", "")
+    if "3 יחידות" in level_name:
+        return EXPLANATION_STYLES["חטיבה_עליונה_3_יחידות"]
+    elif "4 יחידות" in level_name:
+        return EXPLANATION_STYLES["חטיבה_עליונה_4_יחידות"]
+    else:
+        return EXPLANATION_STYLES["חטיבה_עליונה_5_יחידות"]
+
+
+def get_bagrut_rules(topic: str) -> dict:
+    """מחזיר כללי בגרות לנושא מסוים"""
+    
+    topic_map = {
+        "גאומטריה": "גאומטריה",
+        "geometry": "גאומטריה",
+        "חדוא": "חדוא",
+        "calculus": "חדוא",
+        "חקירה": "חדוא",
+        "נגזרת": "חדוא",
+        "אינטגרל": "חדוא",
+        "הסתברות": "הסתברות",
+        "probability": "הסתברות",
+        "אלגברה": "אלגברה",
+        "algebra": "אלגברה",
+        "משוואה": "אלגברה",
+        "אינדוקציה": "אינדוקציה",
+        "induction": "אינדוקציה",
+        "טריגונומטריה": "טריגונומטריה",
+        "trigonometry": "טריגונומטריה",
+        "סדרה": "סדרות",
+        "סדרות": "סדרות",
+        "sequence": "סדרות",
+        "מרוכב": "מספרים_מרוכבים",
+        "complex": "מספרים_מרוכבים",
+        "וקטור": "וקטורים",
+        "vector": "וקטורים",
+        "סטטיסטיקה": "סטטיסטיקה",
+        "statistics": "סטטיסטיקה",
+        "ממוצע": "סטטיסטיקה",
+        "התפלגות": "סטטיסטיקה",
+    }
+    
+    for key, value in topic_map.items():
+        if key in topic.lower():
+            return BAGRUT_RULES.get(value, {})
+    
+    return {}
+
+
+def is_bagrut_level(grade: str, level: str = None) -> bool:
+    """בודק אם זו רמת בגרות"""
+    profile = get_grade_profile(grade, level)
+    return profile["level"].get("bagrut_format", False)

debug_llm_payload.py

@@ -0,0 +1,42 @@
+import asyncio
+import os
+import sys
+
+# Set encoding for Windows console (just in case)
+if sys.platform == 'win32':
+    sys.stdout.reconfigure(encoding='utf-8')
+    sys.stderr.reconfigure(encoding='utf-8')
+
+from orchestrator import BuddyOrchestrator
+from domain.processing_strategy import ProcessingStrategy
+from smart_solver import SmartSolver
+
+async def debug_orchestrator():
+    orchestrator = BuddyOrchestrator()
+    problem_text = "פתור את המשוואה הטריגונומטרית: sin x = 0.5"
+    grade = "10"
+    student_name = "דוד"
+
+    print("🚀 Starting Smart Solver Trace...")
+    try:
+        data_anchor = {"function_equations": ["sin x = 0.5"]}
+        result = await orchestrator.smart_solve(
+            problem_text=problem_text,
+            data_anchor=data_anchor,
+            grade=grade,
+            category="ALGEBRA",
+            processing_strategy=ProcessingStrategy.STRICT_SYMBOLIC
+        )
+        
+        import json
+        with open("debug_output.json", "w", encoding="utf-8") as f:
+            json.dump(result, f, indent=2, ensure_ascii=False)
+        print("✅ Saved to debug_output.json")
+
+    except Exception as e:
+        print(f"❌ Error during execution: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    asyncio.run(debug_orchestrator())

domain/curriculum_classifier.py

@@ -0,0 +1,94 @@
+# domain/curriculum_classifier.py
+import sympy as sp
+import logging
+
+logger = logging.getLogger(__name__)
+
+class CurriculumClassifier:
+    """
+    V6.1 Hybrid Architecture - Phase 1: Router Layer
+    Evaluates math complexity and injects grade-specific pedagogical prompts.
+    """
+    
+    @staticmethod
+    def estimate_complexity(math_string: str) -> int:
+        """
+        Calculates a complexity score (1-10) based on AST features.
+        """
+        score = 1
+        try:
+            # Parse multiple equations if necessary
+            expressions = []
+            
+            # Helper to quickly strip common LaTeX that crashes sympify
+            import re
+            cleaned_str = re.sub(r'\\[a-zA-Z]+', '', str(math_string))
+            cleaned_str = cleaned_str.replace('{', '(').replace('}', ')').replace('$', '')
+            
+            for part in cleaned_str.split(','):
+                expressions.append(sp.sympify(part.replace('=', '-'), evaluate=False))
+                
+            for expr in expressions:
+                # Number of variables
+                vars_count = len(expr.free_symbols)
+                if vars_count > 1:
+                    score += vars_count
+                
+                # Number of operations / tree depth mapping (approx)
+                ops_count = expr.count_ops()
+                score += ops_count // 3
+                
+                # Advanced functions (Trigonometry, Logarithms)
+                if expr.has(sp.sin, sp.cos, sp.tan, sp.log, sp.exp):
+                    score += 3
+                    
+                # High degree polynomials
+                if expr.is_polynomial():
+                    degrees = sp.degree_list(expr)
+                    max_deg = max(degrees) if degrees else 0
+                    if max_deg > 2:
+                        score += 2
+                        
+        except Exception as e:
+            # Fallback heuristic if SymPy parse fails entirely
+            raw_len = len(str(math_string))
+            fallback_score = 3 + (raw_len // 15)
+            logger.warning(f"Complexity estimation failed, falling back to len heuristic ({fallback_score}): {e}")
+            score = fallback_score
+
+            
+        final_score = min(max(int(score), 1), 10)
+        logger.info(f"[ROUTER] Intended Math Complexity Score: {final_score}/10")
+        return final_score
+
+    @staticmethod
+    def get_prompt_specialization(grade: str, intent_category: str) -> str:
+        """
+        Returns pedagogical prompt constraints based on the student's grade.
+        """
+        grade_num = 0
+        import re
+        match = re.search(r'\d+', str(grade))
+        if match:
+            grade_num = int(match.group())
+            
+        constraints = []
+        
+        # Base setup
+        constraints.append("אתה מורה פרטי למתמטיקה.")
+        
+        # Grade specific logic
+        if grade_num <= 7:
+            constraints.append("הסבר במונחים פשוטים מאוד. אל תשתמש במילים כמו 'נבודד' או 'נפשט', אלא 'נשאיר את הנעלם לבד' או 'נחשב את המספרים'.")
+        elif grade_num <= 9:
+            constraints.append("השתמש במונחי אלגברה תקניים כמו 'העברת אגפים', 'כינוס איברים דומים', ו'בידוד משתנה'. שמור על שפה מעודדת.")
+        elif grade_num <= 12:
+            constraints.append("הנח כי התלמיד מכיר מושגי יסוד באלגברה. התמקד בהיגיון העמוק של התרגיל ובחוקים המתמטיים (למשל חוקי חזקות, זהויות). הייה רשמי ומדויק.")
+            if "TRIGONOMETRY" in intent_category.upper():
+                constraints.append("במשוואות טריגונומטריות, הבהר תמיד את שיקולי המחזוריות או מעגל היחידה.")
+        else:
+            constraints.append("הסבר בבהירות ובצורה ישירה.")
+            
+        specialization = " ".join(constraints)
+        logger.info(f"[ROUTER] Prompt specialization applied for Grade {grade} ({intent_category})")
+        return specialization

domain/math_normalizer.py

@@ -0,0 +1,38 @@
+# domain/math_normalizer.py
+
+import re
+import logging
+
+logger = logging.getLogger(__name__)
+
+class MathCanonicalizer:
+    @staticmethod
+    def preprocess_ocr_string(math_string: str) -> str:
+        """
+        V6 Polish (P0): Aggressively cleans raw OCR math strings before SymPy parsing.
+        - Adds explicit multiplication.
+        - Wraps trigonometric functions in parentheses (e.g., sin x -> sin(x)).
+        - Normalizes basic artifacts.
+        """
+        if not math_string:
+            return ""
+            
+        clean_str = str(math_string).strip()
+        
+        # 1. Standardize Whitespace
+        clean_str = re.sub(r'\s+', ' ', clean_str)
+        
+        # 2. Add implicit multiplication between numbers and variables (e.g., 2x -> 2*x)
+        # Note: SymPy handles some of this, but we do it explicitly to be safe
+        clean_str = re.sub(r'(\d)([a-zA-Z])', r'\1*\2', clean_str)
+        
+        # 3. Trigonometric Functions Parentheses Guard
+        # Matches sin, cos, tan, cot, arcsin, arccos, arctan, etc. followed by space and a variable/number
+        # Example: 'sin x' -> 'sin(x)', 'cos 2x' -> 'cos(2*x)', 'tan ^2x' is trickier but we handle the basics.
+        trig_funcs = r'(sin|cos|tan|cot|sec|csc|arcsin|arccos|arctan)'
+        
+        # Match 'sin x' or 'sin 2*x' but not 'sin(x)'
+        # This regex looks for trig function, optional space, and then something that is not a parenthesis
+        clean_str = re.sub(fr'{trig_funcs}\s+([a-zA-Z0-9_*]+)(?!\()', r'\1(\2)', clean_str)
+        
+        return clean_str

domain/math_validator.py

@@ -0,0 +1,282 @@
+# domain/math_validator.py — V1.0 (SYMPY POLYGRAPH)
+"""
+CTO Directive: "SymPy Polygraph" — validates LLM math claims before releasing to Flutter.
+
+Rules:
+1. Scans ALL steps (including GEOMETRY) for math_latex fields — no exemptions.
+2. Fail-CLOSED: SympifyError → (False, "SymPy Parsing Failed"). Never swallow errors.
+3. 3-second hard timeout on every SymPy call (prevents Resource Exhaustion from
+   LLM-hallucinated expressions like x**1000 that would stall the CPU).
+4. Consecutive algebraic pairs are equivalence-checked via sympy.simplify.
+"""
+
+import re
+import logging
+import multiprocessing
+import time
+import asyncio
+from typing import Tuple, List
+
+import sympy
+
+logger = logging.getLogger(__name__)
+
+# Expressions that are structurally unparseable but pedagogically harmless
+# (e.g. "d = 5 | r = 5 | על המעגל")
+_PIPE_SEPARATED_RESULT = re.compile(r'\|')
+_HEBREW_ONLY = re.compile(r'^[\u0590-\u05FF\s]+$')
+
+# LaTeX commands that SymPy cannot parse — strip them before sympify
+_LATEX_STRIP = re.compile(
+    r'\\(?:frac|left|right|cdot|times|div|sqrt|pm|mp|leq|geq|neq'
+    r'|approx|infty|pi|theta|alpha|beta|gamma|delta|sin|cos|tan|log|ln'
+    r'|text|mathrm|mathbf|boxed|underbrace|overbrace|hat|bar|vec|dot|overline|underline)\b'
+)
+
+
+def _latex_to_sympy_str(latex_str: str) -> str:
+    """
+    Best-effort LaTeX → SymPy-parseable string.
+    Not a full LaTeX parser — just cleans the most common patterns.
+    """
+    s = latex_str.strip()
+    # Handle \frac{a}{b} → (a)/(b) (Safe version with Kill-Switch)
+    loop_counter = 0
+    max_loops = 15
+    while r'\frac' in s and loop_counter < max_loops:
+        old_s = s
+        s = re.sub(r'\\frac\s*\{([^{}]*)\}\s*\{([^{}]*)\}', r'(\1)/(\2)', s)
+        if old_s == s:
+            s = s.replace(r'\frac', '(frac_err)')
+            break
+        loop_counter += 1
+    # Remove remaining LaTeX commands
+    s = _LATEX_STRIP.sub(' ', s)
+    # Remove LaTeX delimiters
+    s = s.replace('{', '(').replace('}', ')').replace('$', '')
+    s = s.replace(r'\left', '').replace(r'\right', '')
+    
+    # Handle absolute value pipes |x| -> Abs(x)
+    # Loop to capture nested or multiple Abs pairs
+    loop_counter = 0
+    while '|' in s and s.count('|') >= 2 and loop_counter < 10:
+        s = re.sub(r'\|([^|]+)\|', r'Abs(\1)', s)
+        loop_counter += 1
+        
+    # Implicit multiplication: 2x → 2*x
+    s = re.sub(r'(\d)([a-zA-Z(])', r'\1*\2', s)
+    # Handle equals sign (for equations)
+    if '=' in s:
+        parts = s.split('=', 1)
+        s = f"({parts[0]}) - ({parts[1]})"
+    return s.strip()
+
+
+def _is_plaintext(expr_str: str) -> bool:
+    """Returns True if the expression is plain text (Hebrew / pipe-separated), not math."""
+    if _HEBREW_ONLY.match(expr_str):
+        return True
+    if _PIPE_SEPARATED_RESULT.search(expr_str) and not any(c in expr_str for c in ['+', '-', '*', '/', '^', '=']):
+        return True
+    return False
+
+
+class MathPolygraph:
+    """
+    Post-processing validator that spot-checks LLM math_latex fields using SymPy.
+    Called AFTER safe_extract_json, BEFORE the JSON is released to Flutter.
+
+    Design:
+    - validate_step_sequence() is the only public API.
+    - Returns (True, "") on clean pass.
+    - Returns (False, reason) on hallucination or parse failure.
+    - The orchestrator must set logic_error=True and return a hint response
+      when this returns False.
+    """
+
+    TIMEOUT_SECONDS = 3
+
+    @staticmethod
+    def _sympify_worker(expr_str: str, queue: multiprocessing.Queue):
+        """Worker function for multiprocessing."""
+        try:
+            # We don't actually need the result object, just to know if it PARSES
+            # without hanging the entire server.
+            sympy.sympify(expr_str, evaluate=False)
+            queue.put(True)
+        except Exception:
+            queue.put(False)
+
+    @staticmethod
+    def _sympify_with_timeout(expr_str: str) -> bool:
+        """
+        V8.6.6: Runs sympy.sympify in an isolated PROCESS with a hard 2-second timeout.
+        Returns:
+            True: Parse successful.
+            False: Parse failed (SymPy error).
+            None: Process timed out (Hard Kill).
+        """
+        queue = multiprocessing.Queue()
+        process = multiprocessing.Process(
+            target=MathPolygraph._sympify_worker, 
+            args=(expr_str, queue)
+        )
+        
+        try:
+            process.start()
+            # Wait for 2 seconds
+            process.join(timeout=2)
+            
+            if process.is_alive():
+                logger.error(f"🛑 [POLYGRAPH] SymPy DEADLOCK detected! Hard-killing process for: {expr_str[:50]}...")
+                process.terminate()
+                process.join() # Clean up
+                return None # TIMEOUT
+            
+            if not queue.empty():
+                return queue.get()
+            return False # Fallthrough to error
+        except Exception as e:
+            logger.error(f"⚠️ [POLYGRAPH] Multiprocessing error: {e}")
+            if process.is_alive():
+                process.terminate()
+            return False
+
+    @staticmethod
+    async def _validate_single(math_latex: str, step_id) -> Tuple[bool, str]:
+        """
+        Validates that a single math_latex string is SymPy-parseable.
+        Fail-CLOSED: any error → (False, reason).
+        """
+        if not math_latex or not math_latex.strip():
+            # Empty math field is allowed (some steps have no math)
+            return True, ""
+
+        raw = str(math_latex).strip()
+
+        # Plain text results (e.g. Hebrew labels, pipe-separated geometry) — skip SymPy
+        if _is_plaintext(raw):
+            logger.info(f"[POLYGRAPH] Step {step_id}: plain-text field, skipping SymPy.")
+            return True, ""
+
+        sympy_str = _latex_to_sympy_str(raw)
+        if not sympy_str or sympy_str in ('', '-', '()', '( ) - ( )'):
+            logger.warning(f"[POLYGRAPH] Step {step_id}: empty after LaTeX strip, skipping.")
+            return True, ""
+
+        try:
+            # V8.6.7: Run blocking multiprocessing in a separate thread to keep Event Loop alive
+            status = await asyncio.to_thread(MathPolygraph._sympify_with_timeout, sympy_str)
+            
+            if status is True:
+                return True, ""
+            elif status is None:
+                # V8.6.6: Bypass Timeout — Always return True so SSE stream continues!
+                logger.warning(f"[POLYGRAPH] 🕐 Step {step_id}: SymPy TIMEOUT bypass triggered.")
+                return True, f"SYMPY_TIMEOUT:step_{step_id}"
+            else:
+                # Parse error
+                return False, f"SYMPY_PARSE_ERROR:step_{step_id}"
+
+        except Exception as e:
+            # Updated Regex for Geometry and Logic Bypass
+            is_geometry_or_logic = bool(re.search(r'\\parallel|\\angle|\\triangle|\\cong|\\sim|\\perp|\\Rightarrow|\\implies|\\rightarrow|\\text', raw))
+            
+            if is_geometry_or_logic:
+                logger.info(f"🛡️ [POLYGRAPH] Skipping SymPy validation for Geometry/Logic expression: {raw}")
+                # זה גיאומטריה או לוגיקה, SymPy לא רלוונטי כאן. אנחנו מאשרים מעבר.
+                return True, ""
+            else:
+                logger.error(f"[POLYGRAPH] ❌ Step {step_id}: Unexpected SymPy error: {e}")
+                return True, "" # Soft-fail on unexpected errors too
+
+    @staticmethod
+    async def validate_step_sequence(steps: List[dict]) -> Tuple[bool, str]:
+        """
+        Public API. Scans ALL steps (GEOMETRY included) for math_latex fields.
+
+        For each step:
+        1. Validates the math_latex is SymPy-parseable (fail-closed).
+
+        For consecutive algebraic step pairs (both have math_latex):
+        2. Checks algebraic equivalence via sympy.simplify (spot-check for hallucinations).
+
+        Args:
+            steps: List of step dicts. Each may have a 'math_latex' or 'block_math' field.
+
+        Returns:
+            (True, "") if all checks pass.
+            (False, reason) on first failure.
+        """
+        if not steps:
+            return True, ""
+
+        logger.info(f"[POLYGRAPH] 🔬 Scanning {len(steps)} step(s) for math integrity...")
+
+        prev_expr = None
+        prev_sympy = None
+        prev_id = None
+
+        for step in steps:
+            step_id = step.get('step_id', step.get('step_number', '?'))
+
+            # Collect all math fields — check both new (math_latex) and legacy (block_math)
+            math_fields = []
+            for field in ('math_latex', 'block_math', 'math'):
+                val = step.get(field)
+                if val and isinstance(val, str) and val.strip():
+                    math_fields.append((field, val.strip()))
+
+            # Also check nested math_artifact.latex
+            artifact = step.get('math_artifact', {})
+            if isinstance(artifact, dict):
+                artifact_latex = artifact.get('latex', '')
+                if artifact_latex and artifact_latex.strip():
+                    math_fields.append(('math_artifact.latex', artifact_latex.strip()))
+
+            if not math_fields:
+                prev_expr = None
+                prev_sympy = None
+                continue
+
+            # Validate primary math field
+            primary_field, primary_val = math_fields[0]
+
+            ok, reason = await MathPolygraph._validate_single(primary_val, step_id)
+            if not ok:
+                return False, reason
+
+            # ── Consecutive equivalence check ────────────────────────────────
+            # If the LLM claims step N+1 follows from step N, verify they're related
+            # (Skip plain-text and Hebrew-only results)
+            if prev_expr is not None and prev_sympy is not None and not _is_plaintext(primary_val):
+                curr_sympy_str = _latex_to_sympy_str(primary_val)
+                if curr_sympy_str:
+                    try:
+                        # V8.6.7: Run in thread to prevent blocking
+                        curr_sympy = await asyncio.to_thread(MathPolygraph._sympify_with_timeout, curr_sympy_str)
+                        # 🚨 HOTFIX: Removed sympy.simplify() to prevent CPU Deadlocks. 
+                        # We only check for valid parseable syntax.
+                        prev_sympy = curr_sympy
+                        prev_expr = primary_val
+                        prev_id = step_id
+                    except (concurrent.futures.TimeoutError, sympy.SympifyError, Exception) as e:
+                        # Reset chain on failure (don't propagate equivalence errors)
+                        prev_sympy = None
+                        prev_expr = None
+            else:
+                # Try to build the SymPy object for the next comparison
+                if not _is_plaintext(primary_val):
+                    try:
+                        curr_str = _latex_to_sympy_str(primary_val)
+                        if curr_str:
+                            # V8.6.7: Run in thread to prevent blocking
+                            prev_sympy = await asyncio.to_thread(MathPolygraph._sympify_with_timeout, curr_str)
+                            prev_expr = primary_val
+                            prev_id = step_id
+                    except Exception:
+                        prev_sympy = None
+                        prev_expr = None
+
+        logger.info(f"[POLYGRAPH] ✅ All {len(steps)} steps passed math integrity check.")
+        return True, ""

domain/ontology.py

@@ -0,0 +1,37 @@
+# domain/ontology.py
+
+GLOBAL_ONTOLOGY = {
+    "algebra": {
+        "solve_linear_system": {
+            "concepts": ["מערכת", "מערכת משוואות", "חיתוך ישרים", "השוואת ביטויים", "נעלמים", "נציב", "נחלץ", "משוואות", "משתנה", "ערך"],
+            "tag": "השוואה"
+        },
+        "isolate_variable": {
+            "concepts": ["בידוד משתנה", "העברת אגפים", "נחלק במקדם", "נחסר", "נכנס איברים דומים", "נפשט", "איברים"],
+            "tag": "בידוד משתנה"
+        },
+        "substitute": {
+            "concepts": ["הצבה", "נציב את הערך", "משוואה מקורית", "ערך ה-y", "ערך ה-x", "משתנה שני"],
+            "tag": "הצבה"
+        },
+        "general_algebra": {
+            "concepts": ["משוואה", "נעלם", "פתרון", "הסבר", "חישוב", "שלב"],
+            "tag": "אלגברה בסיסית"
+        }
+    },
+    "geometry": {
+        # Geometry terms will go here later
+    }
+}
+
+def get_allowed_concepts(category: str, rule_id: str) -> list[str]:
+    """Fetch allowed concepts from ontology"""
+    domain = GLOBAL_ONTOLOGY.get(category.lower(), {})
+    rule_data = domain.get(rule_id, domain.get("general_algebra", {"concepts": []}))
+    return rule_data.get("concepts", [])
+
+def get_pedagogical_tag(category: str, rule_id: str) -> str:
+    """Fetch pedagogical tag from ontology"""
+    domain = GLOBAL_ONTOLOGY.get(category.lower(), {})
+    rule_data = domain.get(rule_id, domain.get("general_algebra", {"tag": "כללי"}))
+    return rule_data.get("tag", "כללי")

domain/pedagogical_renderer.py

@@ -0,0 +1,264 @@
+# domain/pedagogical_renderer.py - V7.2 (Deterministic Governed Reasoning Runtime)
+import re
+import logging
+from typing import List, Optional
+import domain.telemetry as telemetry
+from domain.semantic_bank import get_diversity_engine
+
+logger = logging.getLogger(__name__)
+
+
+
+# ==================== V7.2: PLACEHOLDER GUARD ====================
+
+def validate_placeholders(renderer_text: str, provided_ids: List[str]) -> bool:
+    """
+    V7.2: Bi-directional placeholder validation.
+    
+    Check 1: Every ID the server provided MUST appear in the text as {{id}}.
+    Check 2: No placeholder the LLM invented (not in provided_ids) may appear.
+    
+    Either failure → Fail Closed (Hint Mode).
+    """
+    # Check 1: All provided IDs must be referenced
+    for step_id in provided_ids:
+        expected = "{{" + step_id + "}}"
+        if expected not in renderer_text:
+            logger.warning(
+                f"[RENDERER GUARD] Missing placeholder for server-provided ID '{step_id}'. "
+                f"Expected '{expected}' in renderer output."
+            )
+            telemetry.emit_renderer_placeholder_violation("missing", step_id)
+            return False
+
+    # Check 2: No invented placeholders allowed
+    found_placeholders = re.findall(r'\{\{(\w+)\}\}', renderer_text)
+    for ph in found_placeholders:
+        if ph not in provided_ids:
+            logger.warning(
+                f"[RENDERER GUARD] Invented placeholder '{{{{{{ph}}}}}}'  detected! "
+                f"Not in server-provided IDs: {provided_ids}"
+            )
+            telemetry.emit_renderer_placeholder_violation("invented", ph)
+            return False
+
+    return True
+
+
+def inject_signed_results(renderer_text: str, signed_steps: List[dict]) -> str:
+    """
+    Replaces {{step_id}} placeholders in the renderer's text with the actual
+    computed expressions from the server's signed step list.
+    Only called AFTER validate_placeholders() passes.
+    """
+    result = renderer_text
+    for step in signed_steps:
+        placeholder = "{{" + step["id"] + "}}"
+        result = result.replace(placeholder, f"`{step['expression']}`")
+    return result
+
+
+# ==================== V7.2: PEDAGOGICAL RENDERER ====================
+
+class PedagogicalRenderer:
+    """
+    V7.2: LLM #2 — Pedagogical Renderer.
+    
+    Receives the server's signed step IDs (NOT expressions) and the Planner's rationale.
+    Produces a pedagogical explanation in Hebrew using only {{step_id}} placeholders.
+    Never computes or writes math itself.
+    """
+
+    def __init__(self, llm_gateway):
+        self.llm_gateway = llm_gateway
+
+    # V7.2.4 PROMPT — Updated by CTO: Pedagogical Narrator framing + 1 approved example.
+    # Any further changes require full regression (chaos_test.py 18/18) + CTO sign-off.
+    def _build_renderer_prompt(self, pedagogical_rationale: str, step_ids: List[str]) -> str:
+        ids_list = ", ".join(f"{{{{{sid}}}}}" for sid in step_ids)
+        return f"""You are a Pedagogical Narrator for a Hebrew math tutoring system.
+Your role is to explain the INTUITION behind each solution step, not to compute anything.
+The server has already computed all mathematics with certainty — your job is to tell the story.
+
+PEDAGOGICAL RATIONALE:
+{pedagogical_rationale}
+
+SERVER PLACEHOLDERS (use EXACTLY as written):
+{ids_list}
+
+RULES:
+1. Hebrew only.
+2. Explain the intuition and logic behind each step in human, encouraging language.
+   Use analogies, real-world stories, or visual metaphors.
+3. Embed ALL server placeholders exactly: {ids_list}
+4. FORBIDDEN — do NOT write: any digit, number, variable, operator, fraction, or math symbol.
+   Rule: if you feel the urge to write a number or expression, describe its meaning in words instead.
+   Use {{{{step_id}}}} to present the server's computed result. No '=', '/', '^', 'sin(x)', 'pi', etc.
+5. No invented placeholders. Only server-provided IDs above.
+
+EXAMPLE (single approved format — "math textbook narrator style"):
+  ✅ CORRECT: "כדי למצוא את נקודות החיתוך עם ציר ה-y, נציב אפס בערך ה-x ונקבל: {{{{step_1}}}}."
+  ❌ FORBIDDEN: "כדי למצוא את החיתוך נציב x=0 ונקבל y=4."  (raw numbers/symbols — blocked by Guardian)
+"""
+
+    async def render(
+        self,
+        pedagogical_rationale: str,
+        signed_steps: List[dict],
+        action: Optional[str] = None,  # V7.2.5: Planner Enum action for SemanticBank lookup
+    ) -> dict:
+        """
+        V7.2.5 Semantic Composer:
+        1. Try DiversityEngine.compose(action) — deterministic narrative from SemanticBank.
+        2. If no bank entry exists — falls back to LLM #2 (Graceful Degradation).
+        Both paths run renderer_guard() + scan_for_math_leakage() before returning.
+        """
+        step_ids = [s["id"] for s in signed_steps]
+
+        # ── Path A: Deterministic Semantic Composer ─────────────────────────────
+        if action is not None:
+            engine = get_diversity_engine()
+            composed = engine.compose(action, signed_steps)
+            if composed is not None:
+                logger.info(f"[RENDERER] 📚 SemanticBank hit for '{action}'. Using deterministic narrative.")
+                # Inject server results into {{placeholders}} in composed narrative
+                final_text = inject_signed_results(composed, signed_steps)
+                # Guard: composed output must still pass safety checks
+                if not renderer_guard(composed):  # check pre-injection text
+                    logger.error("[RENDERER] renderer_guard failed on SemanticBank output!")
+                    return {"success": False, "reason": "SEMANTIC_BANK_GUARD_VIOLATION"}
+                if not scan_for_math_leakage(final_text):
+                    logger.error("[RENDERER] Leakage scan failed on SemanticBank output!")
+                    return {"success": False, "reason": "SEMANTIC_BANK_LEAKAGE"}
+                logger.info("✅ [RENDERER] Semantic Composer output approved by all guards.")
+                return {"success": True, "rendered_text": final_text, "source": "semantic_bank"}
+
+        # ── Path B: LLM #2 Fallback (unknown action or no bank entry) ────────────
+        logger.info(f"[RENDERER] No SemanticBank entry for action='{action}'. Using LLM #2 fallback.")
+        step_ids = [s["id"] for s in signed_steps]
+
+        system_prompt = self._build_renderer_prompt(pedagogical_rationale, step_ids)
+        user_prompt = (
+            f"Write the pedagogical explanation for this solution. "
+            f"Use the placeholders: {', '.join(step_ids)}"
+        )
+
+        logger.info(f"[RENDERER] Requesting pedagogical explanation for steps: {step_ids}")
+
+        try:
+            raw_text = await self.llm_gateway.generate_raw(system_prompt, user_prompt)
+
+            # Bi-directional placeholder guard
+            if not validate_placeholders(raw_text, step_ids):
+                logger.error("[RENDERER] Placeholder guard FAILED. Failing closed.")
+                return {"success": False, "reason": "PLACEHOLDER_GUARD_VIOLATION"}
+
+            # ── Renderer Guard (V7.2.4) — strict keyword + digit blacklist ────
+            # Runs on raw LLM output BEFORE injection to catch trig keywords,
+            # individual digits, and operators the LLM "helpfully" wrote itself.
+            if not renderer_guard(raw_text):
+                logger.error("[RENDERER] renderer_guard FAILED on raw LLM output. Failing closed.")
+                telemetry.emit_renderer_leakage("renderer_guard_raw")
+                return {"success": False, "reason": "RENDERER_GUARD_VIOLATION"}
+
+            # Inject actual results from server
+            final_text = inject_signed_results(raw_text, signed_steps)
+
+            # ── Renderer Guardian Scan (V7.2.2/V7.2.3) — whitelist + consecutive chars ─
+            if not scan_for_math_leakage(final_text):
+                logger.error(
+                    "[RENDERER GUARDIAN] Math leakage in final injected text! Failing closed."
+                )
+                telemetry.emit_renderer_leakage("post-injection-leak")
+                return {"success": False, "reason": "RENDERER_GUARDIAN_LEAKAGE"}
+
+            logger.info("[RENDERER] ✅ Both guards passed. Pedagogical explanation approved.")
+            return {"success": True, "rendered_text": final_text}
+
+        except Exception as e:
+            logger.error(f"[RENDERER] LLM failure: {e}")
+            return {"success": False, "reason": f"LLM_FAILURE: {e}"}
+
+
+# ==================== V7.2.4: RENDERER GUARD (Strict Blacklist) ====================
+
+def renderer_guard(text: str) -> bool:
+    """
+    V7.2.4 Structural Output Lock — strict blacklist scan on RAW LLM output.
+    Runs BEFORE placeholder injection to catch violations at the source.
+
+    Blocks: individual digits, operator chars, named math functions (sin/cos/tan/sqrt/pi).
+    This is stricter than scan_for_math_leakage() which uses a whitelist on the FINAL text.
+
+    Returns True (safe) / False (fail closed).
+    """
+    # Remove valid server-provided {{placeholders}} first
+    clean = re.sub(r'\{\{.*?\}\}', '', text)
+
+    # Blacklist pattern: any digit, basic operator, or named math function
+    FORBIDDEN_PATTERN = r'[0-9]|[+*/^=]|(?<![a-zA-Z\u0590-\u05FF])(sin|cos|tan|sqrt|pi)(?![a-zA-Z\u0590-\u05FF])'
+
+    match = re.search(FORBIDDEN_PATTERN, clean)
+    if match:
+        logger.warning(
+            f"[RENDERER_GUARD] Forbidden content in raw LLM output: '{match.group(0)}'. "
+            f"Failing closed."
+        )
+        return False
+    return True
+
+
+# ==================== V7.2: TICKET 5 — UI GATE WHITELIST SCAN ====================
+
+def scan_for_math_leakage(rendered_text: str) -> bool:
+    """
+    V7.2.3 Hardened Whitelist Scan (NOT a blacklist).
+    After removing {{...}} placeholders, the remaining text may ONLY contain:
+    - Hebrew letters (Unicode block U+0590–U+05FF)
+    - English letters (for natural language words)
+    - Spaces and basic punctuation (. , ; : ! ? ' " -)
+
+    Two-pass enforcement:
+    Pass 1 — Full whitelist: any forbidden char → REJECT.
+    Pass 2 — Consecutive math chars: >2 consecutive math symbols outside {{}}
+              catches patterns like '3((9)*(+1))', '^2+4', '/6)' even if
+              pass 1 might miss edge-case single chars.
+    """
+    # Remove all valid server-provided {{placeholders}} first
+    clean_text = re.sub(r'\{\{\w+\}\}', '', rendered_text).strip()
+
+    # V7.2.5 FIX: Remove backtick-wrapped server-signed expressions.
+    # inject_signed_results() wraps each signed expression in `backticks`.
+    # These are TRUSTED server content (SymPy output) — NOT LLM-generated.
+    # They MUST be excluded from the leakage scan to avoid false positives.
+    clean_text = re.sub(r'`[^`]+`', '', clean_text).strip()
+
+    if not clean_text:
+        return True  # Text was purely placeholders + signed expressions — safe
+
+    # Pass 1: Full whitelist — Hebrew + English + basic punctuation + typography + backticks ONLY
+    ALLOWED_PATTERN = r'^[\u0590-\u05FFa-zA-Z\s.,;:!?\-\"\'\u2014\u2013\u2012\u200f\u200e`]+$'
+    whitelist_ok = bool(re.match(ALLOWED_PATTERN, clean_text))
+
+    if not whitelist_ok:
+        # Show all characters that were NOT in the whitelist (sync this regex with ALLOWED_PATTERN)
+        violations = re.sub(r'[\u0590-\u05FFa-zA-Z\s.,;:!?\-\"\'\u2014\u2013\u2012\u200f\u200e`]+', '', clean_text)
+        logger.warning(f"[UI_GATE] Math leakage detected! Offending chars: '{violations[:50]}'")
+        telemetry.emit_renderer_leakage(violations[:50])
+        return False
+
+    # Pass 2: Consecutive math char sequence detection (V7.2.3 hardening)
+    # Catches: '3((9', '^2+', '/6)', etc. — >2 non-whitespace math chars in a row
+    # IMPORTANT: exclude backtick (`) as it's used for styling, not as a math operator.
+    MATH_CHAR_PATTERN = r'[0-9=+\-*/^<>|\\(){}\[\]%@#&~]{3,}'
+    consecutive_match = re.search(MATH_CHAR_PATTERN, clean_text)
+    if consecutive_match:
+        chain = consecutive_match.group(0)
+        logger.warning(
+            f"[UI_GATE] Consecutive math char sequence detected: '{chain[:50]}'. "
+            f"Failing closed (Pass 2 — V7.2.3 hardening)."
+        )
+        telemetry.emit_renderer_leakage(f"consecutive_chain:{chain[:30]}")
+        return False
+
+    return True

domain/processing_strategy.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+class ProcessingStrategy(str, Enum):
+    SIMPLE_ARITHMETIC = "SIMPLE_ARITHMETIC"      # Fast Path
+    STRICT_SYMBOLIC = "STRICT_SYMBOLIC"          # דורש הוכחה / מבנה סמלי
+    HEURISTIC_DEDUCTION = "HEURISTIC_DEDUCTION"  # טקסטואלי / גנרי
+    CONVERSATIONAL = "CONVERSATIONAL"            # שיח חופשי

domain/proposal_engine.py

@@ -0,0 +1,189 @@
+# domain/proposal_engine.py - V7.2 (Deterministic Governed Reasoning Runtime)
+import json
+import logging
+from typing import List
+from enum import Enum
+from pydantic import BaseModel, ValidationError
+from .ontology import get_allowed_concepts
+import domain.telemetry as telemetry
+
+logger = logging.getLogger(__name__)
+
+# ==================== V7.2: STRICT SCHEMA DEFINITIONS ====================
+
+class ComputeAction(str, Enum):
+    """V7.3: Hardcoded allowed actions. The Planner may NOT invent new ones."""
+    # ── Algebraic (V7.2) ──────────────────────────────────────────────────
+    SOLVE_EQUATION    = "SOLVE_EQUATION"
+    SIMPLIFY          = "SIMPLIFY"
+    FIND_DERIVATIVE   = "FIND_DERIVATIVE"
+    FIND_INTEGRAL     = "FIND_INTEGRAL"
+    FACTOR            = "FACTOR"
+    EXPAND            = "EXPAND"
+    SUBSTITUTE        = "SUBSTITUTE"
+    # ── Geometry / Analytic (V7.3) ──────────────────────────────────────
+    FIND_AXIS_INTERSECTIONS  = "FIND_AXIS_INTERSECTIONS"   # הצב x=0 / y=0 ופתור
+    CALCULATE_SLOPE_AND_LINE = "CALCULATE_SLOPE_AND_LINE"  # שיפוע + משואת ישר
+    CALCULATE_DISTANCE       = "CALCULATE_DISTANCE"        # נוסחת מרחק + בדיקת מיקום
+
+class ServerComputeTask(BaseModel):
+    action: ComputeAction         # Enum enforced: unknown action → ValidationError
+    target_step_ref: str          # AST Node ID only (e.g. "ast_node_2"), NOT a math expression
+
+class PlannerResponse(BaseModel):
+    pedagogical_rationale: str
+    requires_server_compute: List[ServerComputeTask]
+
+class PlannerFormatError(Exception):
+    """Raised when the Planner's response fails structural or schema validation."""
+    pass
+
+MAX_SERVER_STEPS = 8  # DOS Prevention: Planner cannot request more than 8 server tasks
+
+
+# ==================== V7.2: SAFE JSON EXTRACTION ====================
+
+def extract_and_validate_plan(raw_response: str) -> PlannerResponse:
+    """
+    V7.2: Index-based JSON extraction with PlannerFormatError on any failure.
+    Refuses split() to avoid silent IndexError.
+    """
+    if "<JSON_START>" not in raw_response or "<JSON_END>" not in raw_response:
+        raise PlannerFormatError("Missing explicit JSON boundaries <JSON_START>/<JSON_END>.")
+
+    start = raw_response.index("<JSON_START>") + len("<JSON_START>")
+    end = raw_response.index("<JSON_END>")
+    raw_json = raw_response[start:end].strip()
+
+    try:
+        plan = PlannerResponse.model_validate_json(raw_json)
+
+        # Guard: DOS Prevention
+        if len(plan.requires_server_compute) > MAX_SERVER_STEPS:
+            raise PlannerFormatError(
+                f"DOS Guard: Plan requested {len(plan.requires_server_compute)} steps, max is {MAX_SERVER_STEPS}."
+            )
+
+        return plan
+    except (ValidationError, json.JSONDecodeError) as e:
+        raise PlannerFormatError(f"Validation failed: {e}")
+    except PlannerFormatError:
+        raise
+    except Exception as e:
+        raise PlannerFormatError(f"Unexpected extraction error: {e}")
+
+
+# ==================== V7.2: PROPOSAL ENGINE ====================
+
+class ProposalEngine:
+    """
+    V7.2 Deterministic Governed Reasoning — Pedagogical Planner (LLM #1)
+    
+    The LLM receives only AST metadata (IDs and operations) and returns
+    a structured Plan (JSON). It NEVER writes math expressions — only references AST Node IDs.
+    """
+
+    def __init__(self, llm_gateway):
+        self.llm_gateway = llm_gateway
+
+    def _build_system_prompt(self, ast_metadata: dict, prompt_specialization: str, sub_question_text: str = "") -> str:
+        """Build the strict Planner system prompt including boundary enforcement."""
+        allowed_concepts = get_allowed_concepts(
+            ast_metadata.get("detected_operations", ["general"])[0],
+            "general_algebra"
+        )
+        concepts_str = ", ".join(allowed_concepts) if allowed_concepts else "מונחי אלגברה מדויקים"
+
+        sub_q_line = f"\nSUB-QUESTION TO SOLVE NOW: {sub_question_text}" if sub_question_text else ""
+
+        return f"""You are a Pedagogical Planner for a math tutoring system. 
+Your role is to plan HOW to solve a math problem, NOT to solve it yourself.
+
+PROBLEM CONTEXT (AST Metadata):
+{json.dumps(ast_metadata, ensure_ascii=False, indent=2)}{sub_q_line}
+
+CRITICAL RULES:
+1. You MUST wrap your entire JSON response between <JSON_START> and <JSON_END> tags.
+2. Do NOT write any math expressions or compute anything yourself.
+3. When referring to AST nodes, use their IDs only (e.g. "ast_node_0").
+4. Your response MUST conform to this exact JSON schema:
+{{
+    "pedagogical_rationale": "<short explanation of the teaching strategy in Hebrew>",
+    "requires_server_compute": [
+        {{"action": "<ENUM_ACTION>", "target_step_ref": "<ast_node_id>"}},
+        ...
+    ]
+}}
+5. Allowed actions (ENUM only): SOLVE_EQUATION, SIMPLIFY, FIND_DERIVATIVE, FIND_INTEGRAL, FACTOR, EXPAND, SUBSTITUTE, FIND_AXIS_INTERSECTIONS, CALCULATE_SLOPE_AND_LINE, CALCULATE_DISTANCE.
+6. Maximum {MAX_SERVER_STEPS} compute steps.
+7. Pedagogical Constraint: {prompt_specialization}
+8. Vocabulary: Prioritize these terms: [{concepts_str}].
+9. SINGLE-ACTION CONSTRAINT (critical): For complex equations (circles, trigonometry, systems),
+   always use SOLVE_EQUATION directly on ast_node_0. DO NOT chain operations that reference
+   intermediate result nodes (ast_node_1, ast_node_2, etc.) — those nodes do not exist in
+   the server registry. The SymPy engine handles simplification and expansion internally
+   as part of SOLVE_EQUATION. Violating this rule causes a server crash.
+10. CONTEXTUAL ROUTING (V7.3 — critical): Analyze the SUB-QUESTION TO SOLVE NOW carefully.
+    Select the action that matches the specific task:
+    - "חיתוך", "צירים" → FIND_AXIS_INTERSECTIONS
+    - "ישר", "שיפוע", "משואה" → CALCULATE_SLOPE_AND_LINE
+    - "מרחק", "נקודה על המעגל" → CALCULATE_DISTANCE
+    - General algebra/equation → SOLVE_EQUATION
+    You MUST choose the action that solves specifically this sub-question.
+    Do NOT use SOLVE_EQUATION when a more specific action applies."""
+
+
+    async def generate_draft_proposal(self, context_obj, prompt_specialization: str, ast_metadata: dict = None) -> dict:
+        """
+        Asks LLM #1 (Planner) to produce a structured action plan.
+        Returns {"success": True, "plan": PlannerResponse} or {"success": False, "reason": ...}.
+        """
+        if ast_metadata is None:
+            ast_metadata = {}
+
+        system_prompt = self._build_system_prompt(
+            ast_metadata, prompt_specialization,
+            sub_question_text=getattr(context_obj, 'sub_question_text', '')
+        )
+        user_prompt = (
+            f"Plan the solution for: {context_obj.math_input}\n"
+            f"Remember: Output JSON only, wrapped in <JSON_START>...<JSON_END> tags."
+        )
+
+        logger.info(f"[PLANNER] Requesting plan for: {context_obj.math_input}")
+
+        for attempt in range(2):  # Max 1 retry (Full Strategy Re-run)
+            try:
+                raw_response = await self.llm_gateway.generate_raw(system_prompt, user_prompt)
+                plan = extract_and_validate_plan(raw_response)
+
+                logger.info(
+                    f"[PLANNER] Valid plan received on attempt {attempt + 1}. "
+                    f"Actions: {[t.action for t in plan.requires_server_compute]}"
+                )
+                # Phase 1 Live: Track which Enum actions the Planner chose (drift detection)
+                chosen_actions = [task.action.value for task in plan.requires_server_compute]
+                telemetry.emit_planner_strategy_distribution(chosen_actions)
+                return {"success": True, "plan": plan}
+
+            except PlannerFormatError as e:
+                logger.warning(f"[PLANNER] Attempt {attempt + 1} failed: {e}")
+                if attempt == 0:
+                    # Full Strategy Re-run: inject hard feedback and retry
+                    user_prompt = (
+                        f"Your previous response was invalid: {e}\n"
+                        f"Try again. Plan the solution for: {context_obj.math_input}\n"
+                        f"You MUST use <JSON_START> and <JSON_END> tags. Output valid JSON only."
+                    )
+                    continue
+                else:
+                    logger.error("[PLANNER] Max retries exhausted. Failing closed.")
+                    return {"success": False, "reason": str(e)}
+
+            except Exception as e:
+                logger.error(f"[PLANNER] LLM failure on attempt {attempt + 1}: {e}")
+                if attempt == 0:
+                    continue
+                return {"success": False, "reason": f"LLM_FAILURE: {e}"}
+
+        return {"success": False, "reason": "MAX_RETRIES_EXHAUSTED"}

domain/risk_engine.py

@@ -0,0 +1,66 @@
+# domain/risk_engine.py
+import logging
+from typing import Dict, Any, List
+from .curriculum_classifier import CurriculumClassifier
+
+logger = logging.getLogger(__name__)
+
+class CognitiveRiskEngine:
+    """
+    V6.1 Phase 4: Risk Scoring
+    Evaluates the cognitive risk of a proposal based on AST complexity, 
+    step count, retries, and symbolic stability.
+    """
+    
+    WEIGHTS = {
+        "ast_complexity": 0.30,
+        "reasoning_depth": 0.20,
+        "retry_penalty": 0.25,
+        "symbolic_instability": 0.25
+    }
+    
+    @classmethod
+    def calculate_risk_score(cls, 
+                             math_input: str, 
+                             draft_steps: List[Dict[str, Any]], 
+                             retry_count: int,
+                             validation_errors: int) -> Dict[str, Any]:
+        """
+        Calculates the Cognitive Risk Score (CRS) between 0.0 and 1.0.
+        """
+        # 1. AST Complexity (normalized 0-1)
+        # We reuse CurriculumClassifier's internal complexity estimation if possible, 
+        # but here we normalize it against a ceiling of 20.
+        raw_complexity = CurriculumClassifier.estimate_complexity(math_input)
+        ast_risk = min(raw_complexity / 20.0, 1.0)
+        
+        # 2. Reasoning Depth (normalized 0-1)
+        # 10 steps is considered high depth for our MVP
+        depth_risk = min(len(draft_steps) / 10.0, 1.0)
+        
+        # 3. Retry Penalty
+        # 0 retries = 0.0, 1 retry = 1.0 (since max retry is 1 in V6.1)
+        retry_risk = 1.0 if retry_count > 0 else 0.0
+        
+        # 4. Symbolic Instability
+        # Based on validation failures during the process
+        instability_risk = min(validation_errors / 5.0, 1.0)
+        
+        # Weighted Final Score
+        crs = (ast_risk * cls.WEIGHTS["ast_complexity"] +
+               depth_risk * cls.WEIGHTS["reasoning_depth"] +
+               retry_risk * cls.WEIGHTS["retry_penalty"] +
+               instability_risk * cls.WEIGHTS["symbolic_instability"])
+        
+        result = {
+            "risk_score": round(crs, 3),
+            "features": {
+                "ast_risk": round(ast_risk, 3),
+                "depth_risk": round(depth_risk, 3),
+                "retry_risk": retry_risk,
+                "instability_risk": round(instability_risk, 3)
+            }
+        }
+        
+        logger.info(f"🧠 [RISK_ENGINE] Calculated CRS: {result['risk_score']} (AST: {ast_risk}, Depth: {depth_risk}, Retry: {retry_risk})")
+        return result

domain/schemas.py

@@ -0,0 +1,19 @@
+from enum import Enum
+from typing import Optional, Any, Dict
+from pydantic import BaseModel, Field
+
+class BuddyState(str, Enum):
+    STRATEGY_READY = "STRATEGY_READY"
+    SECTION_WORKING = "SECTION_WORKING"
+    SECTION_READY = "SECTION_READY"
+    COMPLETE = "COMPLETE"
+    ERROR = "ERROR"
+
+class BuddyEvent(BaseModel):
+    question_id: str = Field(..., description="Unique ID for the question session")
+    state: BuddyState = Field(..., description="Current state of the micro-agent")
+    current_section_id: Optional[str] = Field(None, description="The ID of the section (e.g., 'א', 'ב') currently being processed")
+    payload: Dict[str, Any] = Field(default_factory=dict, description="Payload containing state-specific data")
+
+    class Config:
+        use_enum_values = True

domain/semantic_bank.py

@@ -0,0 +1,366 @@
+# domain/semantic_bank.py — V7.2.5: Semantic Composer
+#
+# The SemanticBank is a governed, deterministic source of pedagogical narratives.
+# Instead of letting LLM #2 generate free text (risky), the NarrativeComposer picks
+# from curated, teacher-grade Hebrew templates and injects server-signed results.
+#
+# CTO directive: text must sound like a real private tutor speaking to a 10th/12th grader.
+# Write at eye level — encouraging, intuitive, NOT like system error messages.
+
+import random
+import logging
+from dataclasses import dataclass, field
+from collections import Counter
+from typing import List, Dict, Optional
+
+from domain import telemetry
+
+logger = logging.getLogger(__name__)
+
+DRIFT_ALERT_THRESHOLD = 0.35  # Emit alert when one variant dominates above this fraction
+
+
+# ─── Data Model ───────────────────────────────────────────────────────────────
+
+@dataclass
+class SemanticEntry:
+    """
+    A single pedagogical concept in the bank.
+    Each entry holds multiple variant fragments to ensure narrative diversity.
+    """
+    concept_tag: str           # matches Planner Enum action (e.g. "SOLVE_EQUATION")
+    openings: List[str]        # 3 opening phrases — how to START the explanation
+    bridges: List[str]         # 3 logic bridges — HOW to connect the steps
+    analogies: List[str]       # 2 analogy/metaphor sentences — the "aha!" moments
+    closing: str               # 1 closing encouragement sentence
+
+
+# ─── The Bank ─────────────────────────────────────────────────────────────────
+
+SEMANTIC_BANK: Dict[str, SemanticEntry] = {
+
+    "SOLVE_EQUATION": SemanticEntry(
+        concept_tag="SOLVE_EQUATION",
+        openings=[
+            "בואו נפתור את המשוואה צעד אחר צעד, אל תדאג, זה פחות מפחיד משנראה.",
+            "כדי לגלות את ערך הנעלם, אנחנו הולכים לבודד אותו משני צידי המשוואה.",
+            "נחשוב על המשוואה כמו מאזניים: כל מה שעושים בצד ימין, עושים גם בצד שמאל.",
+        ],
+        bridges=[
+            "אחרי הפעולה הזו, כל מה שנותר הוא:",
+            "וכשנפשט את כל מה שקיבלנו, התוצאה מתגלה:",
+            "המשוואה 'התנקתה' ועכשיו ברור שהתשובה היא:",
+        ],
+        analogies=[
+            "חשוב על זה כמו חידה — אנחנו מסירים רמזים אחד אחד עד שהנעלם חשוף לגמרי.",
+            "בדיוק כמו שמשחקים מחבואים — אנחנו מחפשים את x עד שהוא כבר לא יכול להתחבא.",
+        ],
+        closing="עשית את זה! זו הדרך הרשמית שבה מתמטיקאים פותרים משוואות.",
+    ),
+
+    "SIMPLIFY": SemanticEntry(
+        concept_tag="SIMPLIFY",
+        openings=[
+            "הביטוי הזה נראה מסובך, אבל אם נסדר אותו — הוא מתקפל לצורה הרבה יותר נקייה.",
+            "בפישוט, המטרה היא לכתוב את אותו הדבר — רק בצורה המינימלית ביותר.",
+            "כמו לסדר חדר מבולגן — אנחנו אוספים איברים דומים ומסלקים מה שמיותר.",
+        ],
+        bridges=[
+            "אחרי שנאסוף את כל האיברים הדומים יחד, הביטוי הפשוט הוא:",
+            "כשמסלקים את כל 'הרעש המתמטי', מה שנשאר הוא:",
+            "הצורה הפשוטה והנקייה ביותר של הביטוי:",
+        ],
+        analogies=[
+            "דמיין שיש לך הרבה שטרות של כסף — אתה מחליף אותם לשטר אחד גדול. זה בדיוק מה שאנחנו עושים עם הביטוי.",
+            "כמו לקפל מפת ענק — בסוף קיבלת את אותו המידע, רק בגודל שנוח לשאת.",
+        ],
+        closing="יופי! פישוט זה אחת הכישורים הכי שימושיים במתמטיקה — ועכשיו אתה יודע לעשות את זה.",
+    ),
+
+    "FACTOR": SemanticEntry(
+        concept_tag="FACTOR",
+        openings=[
+            "פירוק לגורמים זה כמו למצוא את 'הבניינים' שמרכיבים את הביטוי שלנו.",
+            "במקום לראות ביטוי אחד גדול, אנחנו מחפשים שני ביטויים קטנים שמוכפלים זה בזה.",
+            "הטריק בפירוק לגורמים הוא לזהות מה 'מסתתר' בתוך הביטוי ואפשר להוציא החוצה.",
+        ],
+        bridges=[
+            "כשנוציא את הגורם המשותף, נקבל:",
+            "אחרי הפירוק, הביטוי נכתב בצורה הכפלית:",
+            "הגורמים שמרכיבים את הביטוי הם:",
+        ],
+        analogies=[
+            "פירוק לגורמים הוא כמו לפרק מספר לחלוקה ראשונית — אנחנו מוצאים את ה-DNA המתמטי של הביטוי.",
+            "דמיין שאתה מפרק ארגז גדול לקופסאות קטנות — כל קופסא היא גורם. ביחד הן מרכיבות את המקור.",
+        ],
+        closing="פירוק לגורמים הוא בדיוק מה שמאפשר לנו לפתור משוואות ריבועיות — תכיר את הכלי הזה טוב.",
+    ),
+
+    "EXPAND": SemanticEntry(
+        concept_tag="EXPAND",
+        openings=[
+            "עכשיו נפרוש את הסוגריים — נכפיל כל איבר בתוך הסוגריים עם כל מה שמחוצה להם.",
+            "פתיחת סוגריים היא כמו 'לפתוח' מתנה עטופה — מה שמסתתר בפנים יוצא לאור.",
+            "נשתמש בחוק הפילוג כדי להרחיב את הביטוי ולראות את כל האיברים בנפרד.",
+        ],
+        bridges=[
+            "לאחר פתיחת הסוגריים ואיסוף האיברים הדומים:",
+            "כשמרחיבים הכל ומסדרים:",
+            "הביטוי המורחב, עם כל האיברים גלויים:",
+        ],
+        analogies=[
+            "חשוב על זה כמו להכפיל תמחיר — אם קנית שלושה שקים, כל אחד עם תפוחים ובננות, אתה מחשב כמה תפוחים וכמה בננות יש בסך הכל.",
+            "פתיחת סוגריים היא כמו לגלגל בצק — לוחצים ומרחיבים עד שהכל שטוח ונראה.",
+        ],
+        closing="הרחבת הביטוי זו מיומנות בסיסית שתשתמש בה שוב ושוב — וכבר שלטת בה.",
+    ),
+
+    "FIND_DERIVATIVE": SemanticEntry(
+        concept_tag="FIND_DERIVATIVE",
+        openings=[
+            "הנגזרת אומרת לנו כמה מהר הפונקציה עולה או יורדת — היא כמו 'מד המהירות' של הגרף.",
+            "כדי למצוא את הנגזרת, אנחנו שואלים: אם x זז קצת קדימה — כמה y משתנה?",
+            "נחשב את הנגזרת לפי כללי הגזירה שנלמדו — זה הרבה יותר מהיר מההגדרה הבסיסית.",
+        ],
+        bridges=[
+            "לפי כלל הגזירה ורשימת הנגזרות, קיבלנו:",
+            "הנגזרת, שמייצגת את שיפוע המשיק לפונקציה, היא:",
+            "קצב השינוי המיידי של הפונקציה הוא:",
+        ],
+        analogies=[
+            "אם הפונקציה היא מסלול נסיעה, הנגזרת היא המד-מהירות — היא אומרת לך כמה מהר אתה נע בכל רגע.",
+            "דמיין שאתה מטפס על הר — הנגזרת אומרת לך בכל נקודה עד כמה התלילות. חיובית = עולים, שלילית = יורדים.",
+        ],
+        closing="הנגזרת פותחת עולם שלם — מניתוח קצוות ועד מכניקה. כל הכבוד על המיומנות הזו.",
+    ),
+
+    "FIND_INTEGRAL": SemanticEntry(
+        concept_tag="FIND_INTEGRAL",
+        openings=[
+            "האינטגרל הוא הפעולה ההפוכה לגזירה — אנחנו שואלים 'מה הפונקציה שהנגזרת שלה היא זו?'.",
+            "כדי לחשב את האינטגרל, נשתמש בנוסחאות הבסיסיות ובחוק ה-C, ה-קבוע האינטגרציה.",
+            "האינטגרל הלא מסוים נותן לנו משפחה שלמה של פונקציות — שונות זו מזו בקבוע בלבד.",
+        ],
+        bridges=[
+            "אחרי אינטגרציה לפי כלל ההפיכה של הנגזרת:",
+            "הפונקציה הפרימיטיבית שמרכיבה את האינטגרל היא:",
+            "ביצוע האינטגרציה נותן לנו:",
+        ],
+        analogies=[
+            "אם הנגזרת היא מד-המהירות, האינטגרל הוא מד-המרחק — הוא אוסף את כל השינויים הקטנים לסכום אחד.",
+            "חשוב על אינטגרציה כמו לגלגל סרט לאחור — אנחנו 'מחזירים' את הגזירה לנקודת המוצא שלה.",
+        ],
+        closing="אינטגרציה היא לב חשבון אינפיניטסימלי — ועכשיו יש לך את הכלי לחשב שטחים, נפחים ועוד.",
+    ),
+
+    "SUBSTITUTE": SemanticEntry(
+        concept_tag="SUBSTITUTE",
+        openings=[
+            "כדי לבדוק את הפתרון (או להשלים חישוב), נציב את הערך הידוע ונפשט.",
+            "ההצבה היא הדרך שלנו לחבר בין שני חלקי הבעיה — מציבים מה שיודעים ורואים מה יוצא.",
+            "נחליף את המשתנה בערך הנתון ונחשב — זה ישאיר לנו ביטוי הרבה יותר פשוט.",
+        ],
+        bridges=[
+            "לאחר ההצבה והפישוט:",
+            "כשנציב ונפשט את הביטוי שקיבלנו:",
+            "ערך ההצבה מניב:",
+        ],
+        analogies=[
+            "הצבה היא כמו למלא שם בטופס — אנחנו מחליפים את 'הנעלם' בערך הממשי שמצאנו.",
+            "דמיין מתכון שאומר 'ספל סוכר' — ברגע שאתה יודע כמה גדול הספל, אתה יכול לחשב כמות מדויקת.",
+        ],
+        closing="מצוין! ההצבה היא גם דרך מצוינת לבדוק שהפתרון שמצאת הוא נכון.",
+    ),
+
+    # ── V7.3: Geometry / Analytic Entries ────────────────────────────────────
+
+    "FIND_AXIS_INTERSECTIONS": SemanticEntry(
+        concept_tag="FIND_AXIS_INTERSECTIONS",
+        openings=[
+            "כדי לגלות איפה המעגל פוגש את הצירים, נשאל שאלה פשוטה: מה קורה כשנקודה נמצאת ממש על ציר ה-x? ה-y שלה שווה לאפס! ולהפך.",
+            "נקודות חיתוך עם הצירים הן הנקודות שבהן המעגל חוצה את 'הכבישים' של מערכת הצירים.",
+            "הדרך לאתר את נקודות החיתוך עם הצירים היא להציב אפס: פעם עבור x ופעם עבור y, ולראות מה הפתרון שיוצא.",
+        ],
+        bridges=[
+            "כשנציב ונפתור, הנקודות שמצאנו הן:",
+            "לאחר ההצבה וקבלת הפתרונות, נקודות החיתוך עם הצירים הן:",
+            "הפתרונות שקיבלנו מציינים את הנקודות שבהן המעגל חוצה את הצירים:",
+        ],
+        analogies=[
+            "חשוב על מעגל כמו כדור שמתגלגל על רצפה — נקודות החיתוך עם ציר ה-x הן בדיוק המקומות שהכדור נוגע ברצפה.",
+            "דמיין שאתה מסתכל על מפה ומחפש איפה כביש ראשי חוצה את הנהר — זה בדיוק מה שאנחנו עושים עם המעגל והצירים.",
+        ],
+        closing="מצאנו את כל נקודות המגע של המעגל עם מערכת הצירים — עבודה מדויקת!",
+    ),
+
+    "CALCULATE_SLOPE_AND_LINE": SemanticEntry(
+        concept_tag="CALCULATE_SLOPE_AND_LINE",
+        openings=[
+            "כדי למצוא את משוואת הישר העובר דרך שתי נקודות, נחשב קודם את השיפוע — כמה 'תלול' הישר.",
+            "שיפוע הישר הוא היחס בין השינוי בגובה לשינוי בהיקף: עלייה חלקי הזזה אופקית.",
+            "הישר שמחבר שתי נקודות מוגדר לחלוטין על ידי השיפוע שלו ונקודת מעבר אחת.",
+        ],
+        bridges=[
+            "לאחר חישוב השיפוע, משוואת הישר היא:",
+            "כשנוסיף את השיפוע שמצאנו לנוסחת הישר, נקבל:",
+            "הישר שמחבר מרכז המעגל לראשית הצירים הוא:",
+        ],
+        analogies=[
+            "שיפוע הוא כמו מדרגות — אם עולים ארבע קומות לכל שלושה צעדים קדימה, השיפוע הוא ארבעה חלקי שלושה.",
+            "דמיין ישר כמו דרך בין שתי ערים — השיפוע הוא כמה מטרים עולים לכל קילומטר שנוסעים.",
+        ],
+        closing="קיבלנו את משוואת הישר בצורה המפורשת — קו ישר שעובר בדיוק דרך שתי הנקודות הנתונות.",
+    ),
+
+    "CALCULATE_DISTANCE": SemanticEntry(
+        concept_tag="CALCULATE_DISTANCE",
+        openings=[
+            "כדי לבדוק האם נקודה נמצאת על המעגל, נמדוד את המרחק בינה לבין מרכז המעגל ונשווה לרדיוס.",
+            "נוסחת המרחק בין שתי נקודות היא שורש של סכום ריבועי ההפרשים — בדיוק כמו משפט פיתגורס.",
+            "השאלה פשוטה: האם הנקודה נמצאת בדיוק ברדיוס מהמרכז, קרוב יותר, או רחוק יותר?",
+        ],
+        bridges=[
+            "לאחר חישוב המרחק, הממצא הוא:",
+            "כשמשווים את המרחק שמצאנו לרדיוס המעגל, מתברר ש:",
+            "תוצאת חישוב ה��רחק מול הרדיוס:",
+        ],
+        analogies=[
+            "דמיין מדוזה עגולה — כל נקודה על גבה נמצאת בדיוק באותו מרחק מהמרכז. אם נקודה קרובה יותר — היא בתוכה. רחוקה יותר — מחוצה לה.",
+            "מרחק שתי נקודות זה כמו למדוד עם סרגל בין שתי ערים על מפה — פיתגורס עושה את העבודה.",
+        ],
+        closing="בדקנו מדויק: המרחק חושב, הושווה לרדיוס, ומיקום הנקודה נקבע בוודאות מתמטית.",
+    ),
+
+}
+
+
+# ─── Diversity Engine ──────────────────────────────────────────────────────────
+
+class DiversityEngine:
+    """
+    Selects narrative variants from the SemanticBank with diversity enforcement.
+
+    Tracks selection history per concept to detect "narrative laziness" (Drift):
+    if one variant is chosen more than DRIFT_ALERT_THRESHOLD fraction of the time,
+    emit a PEDAGOGICAL_DRIFT telemetry alert.
+    """
+
+    def __init__(self):
+        # Counter per concept_tag: tracks how many times each (variant_type, index) was picked
+        self._history: Dict[str, Counter] = {}
+
+    def _record(self, concept_tag: str, variant_key: str):
+        if concept_tag not in self._history:
+            self._history[concept_tag] = Counter()
+        self._history[concept_tag][variant_key] += 1
+
+    def drift_score(self, concept_tag: str) -> float:
+        """
+        Returns the dominance fraction of the most-selected variant for this concept.
+        Score = max_count / total_count.
+        0.0 = perfectly uniform, 1.0 = always the same variant.
+        """
+        if concept_tag not in self._history or not self._history[concept_tag]:
+            return 0.0
+        counts = self._history[concept_tag]
+        total = sum(counts.values())
+        if total == 0:
+            return 0.0
+        return max(counts.values()) / total
+
+    def _pick(self, concept_tag: str, variant_type: str, options: List[str]) -> str:
+        """
+        Weighted random selection that avoids the most recently over-used variants.
+        Falls back to uniform random if history is thin (< 5 picks).
+        """
+        n = len(options)
+        history_key_prefix = f"{variant_type}:"
+        if concept_tag not in self._history or sum(self._history[concept_tag].values()) < 5:
+            # Not enough history — uniform random
+            idx = random.randrange(n)
+        else:
+            counts = self._history[concept_tag]
+            # Weight = inverse of how often we've picked this index
+            weights = []
+            for i in range(n):
+                pick_count = counts.get(f"{history_key_prefix}{i}", 0)
+                weights.append(1.0 / (1 + pick_count))
+            # Weighted choice
+            total_w = sum(weights)
+            r = random.uniform(0, total_w)
+            cumulative = 0.0
+            idx = n - 1  # fallback
+            for i, w in enumerate(weights):
+                cumulative += w
+                if r <= cumulative:
+                    idx = i
+                    break
+
+        key = f"{history_key_prefix}{idx}"
+        self._record(concept_tag, key)
+
+        # Check drift and emit telemetry
+        score = self.drift_score(concept_tag)
+        if score > DRIFT_ALERT_THRESHOLD:
+            logger.warning(
+                f"[DRIFT_MONITOR] Pedagogical drift detected for '{concept_tag}': "
+                f"drift_score={score:.2f} > threshold={DRIFT_ALERT_THRESHOLD}. "
+                f"Selection history: {dict(self._history[concept_tag])}"
+            )
+            telemetry.emit_pedagogical_drift(concept_tag, score)
+
+        return options[idx]
+
+    def compose(self, action: str, signed_steps: list) -> str:
+        """
+        Main entry point: builds a full Hebrew pedagogical narrative for the given action.
+        Inserts {{step_id}} placeholders where the server results will be shown.
+
+        Returns a string with {{placeholder}} notation (not yet injected).
+        """
+        entry = SEMANTIC_BANK.get(action)
+        if entry is None:
+            logger.warning(
+                f"[SEMANTIC_BANK] No entry for action '{action}'. "
+                f"Falling back to LLM #2 renderer."
+            )
+            return None  # Signal to caller: use LLM fallback
+
+        concept_tag = entry.concept_tag
+
+        # Pick diverse variants
+        opening  = self._pick(concept_tag, "opening",  entry.openings)
+        bridge   = self._pick(concept_tag, "bridge",   entry.bridges)
+        analogy  = self._pick(concept_tag, "analogy",  entry.analogies)
+        closing  = entry.closing  # Always the same (one closing per concept by design)
+
+        # Build placeholder string from signed steps
+        if not signed_steps:
+            placeholder_str = ""
+        elif len(signed_steps) == 1:
+            placeholder_str = f"{{{{{signed_steps[0]['id']}}}}}"
+        else:
+            parts = [f"{{{{{s['id']}}}}}" for s in signed_steps]
+            placeholder_str = " ← ".join(parts)
+
+        # Compose the narrative (V7.2.5: no emojis/em-dashes — must pass scan_for_math_leakage)
+        narrative = (
+            f"{opening}\n\n"
+            f"{analogy}\n\n"
+            f"{bridge} {placeholder_str}\n\n"
+            f"{closing}"
+        )
+
+        logger.info(
+            f"[SEMANTIC_BANK] Composed narrative for '{action}' | "
+            f"drift_score={self.drift_score(concept_tag):.2f}"
+        )
+        return narrative
+
+
+# Module-level singleton — shared across all requests in the process
+_engine = DiversityEngine()
+
+def get_diversity_engine() -> DiversityEngine:
+    """Returns the process-level DiversityEngine singleton."""
+    return _engine

domain/step_types.py

@@ -0,0 +1,71 @@
+# domain/step_types.py - V7.4 (TYPED DOMAIN CONTRACTS)
+"""
+V7.4: Typed SignedStep — Domain-Aware Validation Contract.
+
+Replaces the raw dict `{"id", "hash", "expression"}` with a typed dataclass
+that carries a StepType so the ConsistencyGate validates by semantic domain,
+not by string shape.
+
+CTO directive:
+  - expression  → display string only (for renderer injection)
+  - payload     → semantic truth (list[str] for geometry, str for algebraic)
+  - step_type   → routing key for ConsistencyGate dispatch
+
+Backwards compatibility: SignedStep emulates a dict fully so ALL existing
+dict-access code (step["id"], step.get("hash"), "id" in step, step.items())
+in pedagogical_renderer.py / semantic_bank.py continues to work unchanged.
+"""
+from enum import Enum
+from dataclasses import dataclass, asdict
+from typing import Any, Optional
+
+
+class StepType(Enum):
+    ALGEBRAIC = "algebraic"   # SymPy-parseable expression — validated with sympify
+    GEOMETRY  = "geometry"    # Points, distances, labels — validated structurally
+    NUMERIC   = "numeric"     # Pure numeric results — future use
+
+
+@dataclass
+class SignedStep:
+    """
+    V7.4: Typed, SHA256-signed computation step.
+
+    Fields:
+        id          — step identifier used as {{id}} placeholder in renderer
+        expression  — human-readable display string (injected into pedagogy text)
+        payload     — semantic truth: list[str] for geometry, str for algebraic
+        step_type   — StepType enum — routes ConsistencyGate validation
+        hash        — SHA256 digest seeded with canonical form + problem_id + step_id
+    """
+    id: str
+    expression: str
+    payload: Any
+    step_type: StepType
+    hash: str
+
+    # ── Full dict emulation (CTO requirement) ─────────────────────────────────
+    # Allows ALL existing code using step["key"], step.get(...), "key" in step,
+    # step.items() to work without any changes.
+
+    _FIELDS = ("id", "expression", "payload", "step_type", "hash")
+
+    def __getitem__(self, key: str):
+        if key not in self._FIELDS:
+            raise KeyError(key)
+        return getattr(self, key)
+
+    def get(self, key: str, default=None):
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+    def keys(self):
+        return list(self._FIELDS)
+
+    def items(self):
+        return [(k, self[k]) for k in self._FIELDS]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._FIELDS

domain/telemetry.py

@@ -0,0 +1,177 @@
+# domain/telemetry.py - V7.2 Observability Layer
+"""
+BuddyMath V7.2 Runtime Telemetry
+Emits structured log-based metrics compatible with Datadog/Grafana log pipelines.
+
+All metrics are emitted as structured JSON log lines on the logger named "buddymath.metrics".
+DevOps should configure a log-based metric parser for lines containing "METRIC_EVENT".
+
+Metric naming convention: <component>.<event_name>
+"""
+import logging
+import json
+import time
+from datetime import datetime, timezone
+from typing import Optional
+
+metrics_logger = logging.getLogger("buddymath.metrics")
+
+# ==================== METRIC KEY CONSTANTS ====================
+# Use these constants everywhere to prevent typos and enable grep-ability.
+
+class M:
+    """V7.2 Metric Key Registry"""
+
+    # Core runtime outcome (feeds the Pie Chart)
+    RUNTIME_OUTCOME         = "runtime.outcome"        # values: success | hint_mode | planner_retry | leakage_fail | placeholder_fail | crs_block
+
+    # Fail Closed Rate (derived from RUNTIME_OUTCOME != success)
+    FAIL_CLOSED             = "fail_closed"            # emitted on any non-success outcome
+
+    # Planner (LLM #1)
+    PLANNER_RETRY           = "planner.retry.count"    # emitted on each retry attempt
+    PLANNER_ENUM_VIOLATION  = "planner.enum_violation" # emitted when ComputeAction enum is violated
+    PLANNER_JSON_ERROR      = "planner.json_error"     # emitted on JSON parse / boundary failure
+    PLANNER_STRATEGY_DIST   = "planner.strategy_distribution"  # which Enum actions are chosen (drift detection)
+
+    # Renderer (LLM #2)
+    RENDERER_LEAKAGE_FAIL       = "renderer.leakage_fail"          # Whitelist scan failed
+    RENDERER_PLACEHOLDER_FAIL   = "renderer.placeholder_violation"  # Missing or invented placeholder
+    RENDERER_LEAKAGE_CHARS      = "renderer.leakage_chars"          # Offending chars (for slicing)
+
+    # Solver / Server Determinism
+    SOLVER_EXECUTION_MS     = "solver.execution_time_ms"    # Math engine wall-clock time
+    SIGNATURE_HASH_COLLISION = "signature.hash_collision"   # MUST always be 0
+
+    # CRS Pre-Flight
+    CRS_BLOCK               = "crs.preflight_block"     # Emitted when CRS > 0.7 blocks LLM call
+    CRS_VALUE               = "crs.value"               # Raw CRS score for histogram
+
+    # Security
+    SUSPICIOUS_INPUT        = "suspicious.input_pattern"  # Potential prompt injection detected
+
+    # Pedagogical Diversity (V7.2.5)
+    PEDAGOGICAL_DRIFT       = "pedagogical.drift_score"   # Narrative laziness: > 0.35 = same template always chosen
+
+
+# ==================== EMITTER ====================
+
+def emit(metric: str, value, tags: Optional[dict] = None):
+    """
+    Emit a single metric event as a structured JSON log line.
+    Datadog/Grafana log-based metric pipelines should parse lines with 'METRIC_EVENT'.
+    
+    Format:
+    {"event": "METRIC_EVENT", "metric": "<name>", "value": <v>, "tags": {...}, "timestamp": "..."}
+    """
+    payload = {
+        "event":     "METRIC_EVENT",
+        "metric":    metric,
+        "value":     value,
+        "tags":      tags or {},
+        "timestamp": datetime.now(timezone.utc).isoformat()
+    }
+    metrics_logger.info(json.dumps(payload, ensure_ascii=False))
+
+
+def emit_runtime_outcome(outcome: str, problem_id: str = "unknown", grade: str = "unknown"):
+    """Feeds the main Pie Chart and Fail Closed Rate gauge."""
+    emit(M.RUNTIME_OUTCOME, outcome, {"problem_id": problem_id, "grade": grade})
+    if outcome != "success":
+        emit(M.FAIL_CLOSED, 1, {"reason": outcome})
+
+
+def emit_planner_retry(attempt: int, reason: str):
+    emit(M.PLANNER_RETRY, attempt, {"reason": reason})
+
+
+def emit_planner_error(error_type: str, details: str = ""):
+    """error_type: 'enum_violation' | 'json_error'"""
+    key = M.PLANNER_ENUM_VIOLATION if error_type == "enum_violation" else M.PLANNER_JSON_ERROR
+    emit(key, 1, {"details": details[:120]})
+
+
+def emit_planner_strategy_distribution(actions: list):
+    """
+    Phase 1 Live: Emit one metric event per chosen Enum action.
+    Feeds the planner.strategy_distribution dashboard panel.
+    A sudden shift in distribution signals Model Drift.
+    Example: [SOLVE_EQUATION, SIMPLIFY, SOLVE_EQUATION] → 3 events
+    """
+    for action in actions:
+        emit(M.PLANNER_STRATEGY_DIST, 1, {"action": str(action)})
+
+
+def emit_renderer_leakage(offending_chars: str):
+    emit(M.RENDERER_LEAKAGE_FAIL, 1, {"offending_chars": offending_chars[:50]})
+    emit(M.RENDERER_LEAKAGE_CHARS, offending_chars[:50])
+
+
+def emit_renderer_placeholder_violation(violation_type: str, missing_id: str = ""):
+    """violation_type: 'missing' | 'invented'"""
+    emit(M.RENDERER_PLACEHOLDER_FAIL, 1, {"type": violation_type, "id": missing_id})
+
+
+def emit_solver_timing(start_time: float):
+    """Call with time.time() snapshot taken BEFORE solver runs."""
+    elapsed_ms = round((time.time() - start_time) * 1000, 2)
+    emit(M.SOLVER_EXECUTION_MS, elapsed_ms)
+    return elapsed_ms
+
+
+def emit_hash_collision(step_id: str, problem_id: str):
+    """
+    CRITICAL: This MUST never be emitted in a correct system.
+    If it fires, it means two different expressions produced the same hash → P0 alert.
+    """
+    metrics_logger.critical(
+        json.dumps({
+            "event":      "METRIC_EVENT",
+            "metric":     M.SIGNATURE_HASH_COLLISION,
+            "value":      1,
+            "tags":       {"step_id": step_id, "problem_id": problem_id},
+            "timestamp":  datetime.now(timezone.utc).isoformat(),
+            "severity":   "P0_CRITICAL"
+        })
+    )
+
+
+def emit_crs_block(crs_value: float, problem_id: str = "unknown"):
+    emit(M.CRS_BLOCK, 1, {"crs": crs_value, "problem_id": problem_id})
+    emit(M.CRS_VALUE, crs_value)
+
+
+def emit_crs_value(crs_value: float):
+    emit(M.CRS_VALUE, crs_value)
+
+
+def emit_suspicious_input(pattern: str, problem_id: str = "unknown"):
+    emit(M.SUSPICIOUS_INPUT, 1, {"pattern": pattern[:80], "problem_id": problem_id})
+
+
+def emit_pedagogical_drift(concept_tag: str, drift_score: float):
+    """
+    V7.2.5: Emitted when DiversityEngine detects narrative laziness.
+    drift_score > 0.35 means one template variant is dominating selection.
+    Alert DevOps: Renderer is repeating the same pedagogical phrasing — student experience degrades.
+    """
+    emit(M.PEDAGOGICAL_DRIFT, round(drift_score, 3), {"concept": concept_tag})
+
+
+# ==================== TIMER CONTEXT MANAGER ====================
+
+class SolverTimer:
+    """
+    Context manager for measuring Math Engine execution time.
+    Usage:
+        with SolverTimer() as t:
+            result = sympy_solve(...)
+        print(t.elapsed_ms)
+    """
+    def __enter__(self):
+        self._start = time.time()
+        return self
+
+    def __exit__(self, *args):
+        self.elapsed_ms = round((time.time() - self._start) * 1000, 2)
+        emit(M.SOLVER_EXECUTION_MS, self.elapsed_ms)

domain/validator.py

@@ -0,0 +1,148 @@
+# domain/validator.py - V7.4 (DOMAIN-AWARE CONSISTENCY GATE)
+"""
+V7.4 ConsistencyGate: Domain-Aware Validation.
+
+Validates by StepType — NOT by string shape.
+
+  ALGEBRAIC → sympy.sympify() (existing behaviour, unchanged)
+  GEOMETRY  → structural validation of payload (list[str])
+  NUMERIC   → {future expansion point}
+
+CTO directive:
+  - Geometry steps must NEVER reach sympify (Category Error prevention)
+  - Geometry gets its own structural validator, not a "skip blind"
+  - expression is display-only — validation uses payload for geometry
+"""
+import sympy
+import logging
+from typing import List, Tuple
+from domain.step_types import StepType, SignedStep
+
+logger = logging.getLogger(__name__)
+
+
+class ConsistencyGate:
+    """
+    V7.4 Wall 3: Post-Execution Domain-Aware Consistency Gate.
+
+    Receives the list of SignedStep objects from the Deterministic Solver and
+    verifies structural and logical integrity before passing to the Renderer.
+
+    Checks performed (all domains):
+    1. Non-empty: at least one signed step exists.
+    2. Hash integrity: every step has a non-empty SHA256 hash.
+    3a. ALGEBRAIC: expression is SymPy-parseable (sympy.sympify).
+    3b. GEOMETRY:  payload is a non-empty list[str] (structural validation).
+    """
+
+    @staticmethod
+    def _validate_algebraic(step: SignedStep) -> Tuple[bool, str]:
+        """
+        Validates an ALGEBRAIC step by attempting sympy.sympify on each
+        sub-expression (split on " OR " for multi-solution results).
+        """
+        expr_str = step.expression
+        if not expr_str:
+            logger.error(f"[CONSISTENCY_GATE] Step '{step.id}' has an empty expression.")
+            return False, f"EMPTY_EXPRESSION:{step.id}"
+
+        parts = [p.strip() for p in expr_str.split(" OR ")]
+        for part in parts:
+            try:
+                sympy.sympify(part)
+            except Exception as e:
+                logger.error(
+                    f"[CONSISTENCY_GATE] Step '{step.id}' expression not parseable: "
+                    f"'{part}' — {e}"
+                )
+                return False, f"UNPARSEABLE_EXPRESSION:{step.id}"
+        return True, ""
+
+    @staticmethod
+    def _validate_geometry(step: SignedStep) -> Tuple[bool, str]:
+        """
+        Validates a GEOMETRY step structurally via payload.
+
+        Geometry output (points, distances, labels) is NOT SymPy-parseable.
+        We verify:
+          - payload is a non-empty list
+          - every element is a string
+        Hash integrity (checked earlier) is the cryptographic guarantee.
+        """
+        payload = step.payload
+        if not isinstance(payload, list) or len(payload) == 0:
+            logger.error(
+                f"[CONSISTENCY_GATE] Geometry step '{step.id}' has empty or non-list payload."
+            )
+            return False, f"GEOMETRY_EMPTY_PAYLOAD:{step.id}"
+        if not all(isinstance(p, str) for p in payload):
+            logger.error(
+                f"[CONSISTENCY_GATE] Geometry step '{step.id}' payload contains non-string items."
+            )
+            return False, f"GEOMETRY_INVALID_PAYLOAD_TYPE:{step.id}"
+        logger.info(
+            f"[CONSISTENCY_GATE] Geometry step '{step.id}' passed structural validation "
+            f"({len(payload)} point(s))."
+        )
+        return True, ""
+
+    @staticmethod
+    def validate(
+        signed_steps: List,
+        ast_registry: dict,
+        problem_id: str
+    ) -> Tuple[bool, str]:
+        """
+        Returns (True, "") if all checks pass.
+        Returns (False, reason) if any check fails → caller must Fail Closed.
+
+        Accepts both SignedStep objects and legacy dicts for backwards compatibility
+        during any partial migration.
+        """
+        # Check 1: Non-empty output
+        if not signed_steps:
+            logger.error("[CONSISTENCY_GATE] No signed steps produced by solver.")
+            return False, "EMPTY_SOLVER_OUTPUT"
+
+        for step in signed_steps:
+            step_id = step.get("id", "?") if hasattr(step, "get") else step.get("id", "?")
+
+            # Check 2: Hash presence
+            h = step.get("hash", "") if hasattr(step, "get") else step.get("hash", "")
+            if not h or len(h) < 10:
+                logger.error(f"[CONSISTENCY_GATE] Step '{step_id}' is missing a valid SHA256 hash.")
+                return False, f"MISSING_HASH:{step_id}"
+
+            # Check 3: Domain-aware expression / payload validation
+            step_type = step.get("step_type") if hasattr(step, "get") else None
+
+            if step_type == StepType.GEOMETRY:
+                ok, reason = ConsistencyGate._validate_geometry(step)
+                if not ok:
+                    return False, reason
+
+            elif step_type == StepType.ALGEBRAIC or step_type is None:
+                # None = legacy dict without step_type → treat as ALGEBRAIC (backwards compat)
+                expr_str = step.get("expression", "")
+                if not expr_str:
+                    logger.error(f"[CONSISTENCY_GATE] Step '{step_id}' has an empty expression.")
+                    return False, f"EMPTY_EXPRESSION:{step_id}"
+                parts = [p.strip() for p in expr_str.split(" OR ")]
+                for part in parts:
+                    try:
+                        sympy.sympify(part)
+                    except Exception as e:
+                        logger.error(
+                            f"[CONSISTENCY_GATE] Step '{step_id}' expression not parseable: "
+                            f"'{part}' — {e}"
+                        )
+                        return False, f"UNPARSEABLE_EXPRESSION:{step_id}"
+
+            # StepType.NUMERIC → future expansion point
+            # Other unknown types → pass through (hash check is the integrity guarantee)
+
+        logger.info(
+            f"[CONSISTENCY_GATE] ✅ {len(signed_steps)} signed steps passed all checks "
+            f"for problem '{problem_id}'."
+        )
+        return True, ""

explanation_math_firewall.py

@@ -0,0 +1,60 @@
+# explanation_math_firewall.py - V4.2 (Behavioral Firewall)
+# Prevents semantic leaks of forbidden mathematical concepts.
+
+import re
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Concepts that are often "shadow paths" or over-qualified for lower grades
+FORBIDDEN_CONCEPTS = [
+    r"נגזרת", r"נגזור", r"גזירה", r"קיצון", r"מקסימום", r"מינימום", 
+    r"אינטגרל", r"אינטגרציה", r"הפרש", r"מערכת", r"נעלמים", r"שני נעלמים",
+    r"פיתגורס", r"שורשים", r"מכנה משותף" # Add more as needed
+]
+
+# Symbols that indicate over-qualified math
+FORBIDDEN_SYMBOLS = [
+    r"'", r"\\'", r"integral", r"\\int", r"\\Sigma", r"\\Delta"
+]
+
+def scan_explanation(text: str, proof_graph) -> tuple[bool, str]:
+    """
+    Scans explanation text for concepts NOT present in the ProofGraph.
+    Returns (is_safe, violation_reason).
+    """
+    if not text:
+        return True, ""
+
+    # 1. Check for Hebrew forbidden concepts
+    for pattern in FORBIDDEN_CONCEPTS:
+        if re.search(pattern, text):
+            # Check if this concept is "allowed" because it's in the ProofGraph
+            # (e.g., if we actually used a Derivative, it's fine to say 'נגזרת')
+            is_in_proof = False
+            if proof_graph:
+                for step in proof_graph.steps:
+                    if step.operator_used and pattern in step.logic_description:
+                        is_in_proof = True
+                        break
+            
+            if not is_in_proof:
+                logger.warning(f"🛡️ [FIREWALL] Semantic violation detected: '{pattern}'")
+                return False, f"Concept '{pattern}' found in text but not in ProofGraph."
+
+    # 2. Check for forbidden mathematical symbols
+    for symbol in FORBIDDEN_SYMBOLS:
+        if symbol in text:
+            # Similar logic: check if the symbol appears in math_content of proof_graph
+            is_in_proof = False
+            if proof_graph:
+                for step in proof_graph.steps:
+                    if symbol in str(step.math_content):
+                        is_in_proof = True
+                        break
+            
+            if not is_in_proof:
+                logger.warning(f"🛡️ [FIREWALL] Symbol violation detected: '{symbol}'")
+                return False, f"Symbol '{symbol}' found in text but not in ProofGraph."
+
+    return True, ""

find_models.py

@@ -0,0 +1,8 @@
+from google import genai
+
+client = genai.Client(api_key="YOUR_GEMINI_API_KEY_HERE")
+
+print("מחפש מודלי Pro זמינים למפתח שלך...")
+for model in client.models.list():
+    if "pro" in model.name:
+        print(model.name)

firebase_manager.py

@@ -0,0 +1,68 @@
+import logging
+import os
+import firebase_admin
+from firebase_admin import credentials, storage
+
+# Initialize logging
+logger = logging.getLogger("BIT-LOG")
+
+class FirebaseManager:
+    """
+    V261.17: Manages Firebase Storage uploads for resilient audio playback.
+    Replaces local static file serving which causes timeouts and 404s.
+    """
+    
+    _instance = None
+    _bucket = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(FirebaseManager, cls).__new__(cls)
+            cls._instance._initialize()
+        return cls._instance
+
+    def _initialize(self):
+        """Initialize Firebase Admin SDK with service account."""
+        try:
+            from config import FIREBASE_CREDENTIALS_PATH, STORAGE_BUCKET, IS_PRODUCTION
+
+            cred_path = FIREBASE_CREDENTIALS_PATH
+            
+            if not os.path.exists(cred_path):
+                logger.warning(f"MISSING: [FIREBASE] Missing credentials at {cred_path}. Audio/Storage will fail!")
+                return
+
+            if not firebase_admin._apps:
+                cred = credentials.Certificate(cred_path)
+                firebase_admin.initialize_app(cred, {
+                    'storageBucket': STORAGE_BUCKET
+                })
+                logger.info(f"SUCCESS: [FIREBASE] Initialized successfully for {'PROD' if IS_PRODUCTION else 'DEV'}.")
+            
+            self._bucket = storage.bucket()
+            
+        except Exception as e:
+            logger.error(f"ERROR: [FIREBASE] Initialization failed: {e}")
+
+    def upload_file(self, local_path: str, destination_blob_name: str) -> str:
+        """
+        Uploads a local file to the bucket and returns the public URL.
+        """
+        if not self._bucket:
+            logger.error("❌ [FIREBASE] Not initialized. Cannot upload.")
+            return None
+
+        try:
+            blob = self._bucket.blob(destination_blob_name)
+            blob.upload_from_filename(local_path)
+            blob.make_public()
+            
+            logger.info(f"UPLOAD: [FIREBASE] Uploaded {local_path} -> {blob.public_url}")
+            return blob.public_url
+            
+        except Exception as e:
+            logger.error(f"ERROR: [FIREBASE] Upload failed for {local_path}: {e}")
+            return None
+
+# Singleton accessor
+firebase_manager = FirebaseManager()

fix_welcome_audio.py

@@ -0,0 +1,35 @@
+import asyncio
+import os
+from audio_generator import generate_teacher_audio
+
+# הטקסט של המורה מדף הבית
+WELCOME_SCRIPT = (
+    "היי! ברוכים הבאים למורה למתמטיקה. איזה כיף שהצטרפתם אליי! "
+    "אני כאן כדי להפוך את המתמטיקה לחוויה ברורה וחזותית. "
+    "במסך כאן תמצאו שני כפתורים עיקריים. "
+    "לחצו על הכפור הירוק פתרי לי תרגיל, אם אתם צריכים פתרון מלא ומודרך מאפס. "
+    "או על הכפתור הוורוד בדקי לי תשובה, כדי שאעבור על הדרך שאתם עשיתם ואגיד לכם אם צדקתם. "
+    "חשוב שתדעו, אני תמיד כאן בשבילכם. "
+    "אם סיימתי לפתור ועדיין משהו לא מובן, פשוט תלחצו על הכפתור שאל את המורה. "
+    "אני אשמח להסביר הכל שוב עד שהכל יהיה ברור ומסודר בראש. "
+    "ועוד טיפ קטן ממני. "
+    "אם אתם יושבים ללמוד למבחן, הכי כדאי לעבוד עם מחשב ולא עם הטלפון, כי שם הכל הרבה יותר ברור. "
+    "כדי להתחבר, פשוט נכנסים לאתר מהמחשב ומאשרים את הכניסה דרך הטלפון שלכם. "
+    "שיהיה המון בהצלחה!"
+)
+
+async def fix_welcome():
+    print("TTS: Generating welcome audio in MP3 format...")
+    output_path = "static/welcome_teacher_v1.mp3"
+    
+    # שימוש במחולל האודיו הקיים שכבר יודע להעלות ל-Firebase
+    public_url = await generate_teacher_audio(WELCOME_SCRIPT, output_path)
+    
+    if public_url:
+        print(f"SUCCESS: Welcome audio fixed and uploaded!")
+        print(f"URL: {public_url}")
+    else:
+        print("ERROR: Failed to generate or upload welcome audio.")
+
+if __name__ == "__main__":
+    asyncio.run(fix_welcome())

generate_new_welcome.py

@@ -0,0 +1,102 @@
+import os
+import re
+import time
+import torch
+import torchaudio
+import warnings
+from pydub import AudioSegment
+
+warnings.filterwarnings("ignore")
+
+# =========================================================================
+# פתרון חסין לטעינה על CPU
+# =========================================================================
+original_load = torch.load
+
+def safe_load(*args, **kwargs):
+    if 'map_location' not in kwargs:
+        kwargs['map_location'] = 'cpu'
+    if 'weights_only' in kwargs:
+        kwargs['weights_only'] = False
+    return original_load(*args, **kwargs)
+
+torch.load = safe_load
+# =========================================================================
+
+try:
+    from chatterbox.mtl_tts import ChatterboxMultilingualTTS
+    from phonikud_onnx import Phonikud
+    from phonikud import lexicon
+except ImportError:
+    print("❌ שגיאה: חסרות ספריות. וודא שאתה ב-venv_fix והרצת pip install.")
+    exit()
+
+class TTSManager:
+    def __init__(self, reference_audio_path="new_teacher_reference.wav"):
+        print("⚙️  טוען מנוע 'המורה למתמטיקה' (ZipVoice Mode)...")
+        self.device = "cpu"
+        self.ref_audio_path = reference_audio_path
+        self.phonikud_model = Phonikud("phonikud-1.0.int8.onnx")
+        self.tts_model = ChatterboxMultilingualTTS.from_pretrained(device=self.device)
+        print("✅ המנוע מוכן.")
+
+    def _split_to_sentences(self, text):
+        return [s.strip() for s in re.split(r'(?<=[.!?]) +', text) if s.strip()]
+
+    def generate_audio(self, text, output_filename="welcome_speech_v2.wav"):
+        sentences = self._split_to_sentences(text)
+        print(f"📝 מעבד {len(sentences)} משפטים קצרים (למניעת 'נשימות')...")
+        
+        combined = AudioSegment.empty()
+        silence = AudioSegment.silent(duration=250) 
+
+        for i, sentence in enumerate(sentences):
+            temp_file = f"temp_part_{i}.wav"
+            print(f"🎙️  משפט {i+1}/{len(sentences)}: {sentence[:30]}...")
+            
+            # שלב 1: ניקוד אוטומטי
+            voweled = self.phonikud_model.add_diacritics(sentence)
+            voweled = re.sub(fr"[{lexicon.NON_STANDARD_DIAC}]", "", voweled)
+            
+            # שלב 2: תיקון כפוי לנקבה! מחליף "מורֶה" ב-"מורָה"
+            voweled = voweled.replace("מוֹרֶה", "מוֹרָה").replace("מּוֹרֶה", "מּוֹרָה")
+            
+            # ייצור הקול
+            wav = self.tts_model.generate(
+                voweled, 
+                language_id="he", 
+                audio_prompt_path=self.ref_audio_path,
+                cfg_weight=0.90 
+            )
+            torchaudio.save(temp_file, wav, self.tts_model.sr)
+            combined += AudioSegment.from_wav(temp_file) + silence
+            os.remove(temp_file)
+
+        combined.export(output_filename, format="wav")
+        print(f"✨ הושלם! הקובץ מחכה ב: {output_filename}")
+
+if __name__ == "__main__":
+    REFERENCE_FILE = "new_teacher_reference.wav"
+    
+    if not os.path.exists(REFERENCE_FILE):
+        print(f"❌ שגיאה: קובץ דגימה '{REFERENCE_FILE}' לא נמצא.")
+    else:
+        tts = TTSManager(reference_audio_path=REFERENCE_FILE)
+        
+        # הטקסט פוצל למשפטים קצרים עם נקודות למניעת רעשי נשימה ועומס על המודל
+        script = (
+            "היי! ברוכים הבאים למורה למתמטיקה. איזה כיף שהצטרפתם אליי! "
+            "אני כאן כדי להפוך את המתמטיקה לחוויה ברורה וחזותית. "
+            "במסך כאן תמצאו שני כפתורים עיקריים. "
+            "לחצו על הכפתור הירוק פתרי לי תרגיל, אם אתם צריכים פתרון מלא ומודרך מאפס. "
+            "או על הכפתור הוורוד בדקי לי תשובה, כדי שאעבור על הדרך שאתם עשיתם ואגיד לכם אם צדקתם. "
+            "חשוב שתדעו, אני תמיד כאן בשבילכם. "
+            "אם סיימתי לפתור ועדיין משהו לא מובן, פשוט תלחצו על הכפתור שאל את המורה. "
+            "אני אשמח להסביר הכל שוב עד שהכל יהיה ברור ומסודר בראש. "
+            "ועוד טיפ קטן ממני. "
+            "אם אתם יושבים ללמוד למבחן, הכי כדאי לעבוד עם מחשב ולא עם הטלפון, כי שם הכל הרבה יותר ברור. "
+            "כדי להתחבר, פשוט נכנסים לאתר מהמחשב ומאשרים את הכניסה דרך הטלפון שלכם. "
+            "שיהיה המון בהצלחה!"
+        )
+        
+        tts.generate_audio(script, "welcome_speech_v2.wav")

gibberish_detector.py

@@ -0,0 +1,240 @@
+# gibberish_detector.py - V274.0 (Multi-line LaTeX Fix)
+# STABLE VERSION - No aggressive Hebrew removal!
+import re, copy, asyncio
+from typing import Tuple, Dict, Any, List
+
+print("[BIT-LOG: GibberishDetector V274.0 Loaded (Multi-line LaTeX Fix)]")
+
+# ==================== REPAIR MAPS ====================
+
+# Simple replace fixes (Not regex)
+REPAIR_MAP = {
+    '\\\\\\\\\\\\\\\\': '\\\\\\\\',
+    '\\\\\\\\': '\\\\',
+    '$$$': '$$',
+    'תוילקבמ': 'מקביליות',
+    'םיחטש': 'שטחים',
+    'הדוקנה': 'הנקודה',
+}
+
+# Broken LaTeX patterns (Regex)
+LATEX_FIXES = {
+    r'\\rac\{': r'\\frac{',  # Missing 'f'
+    r'\\eta\{': r'\\beta{',  # Wrong letter
+    r'\\sqr\{': r'\\sqrt{',  # Missing 't'
+    r'(?<!\\)\b(sin|cos|tan|log|ln)\b': r'\\\1', # Missing backslash for funcs
+    r'(?<!\\)\b(alpha|beta|gamma|cdot)\b': r'\\\1', # Missing backslash for greek/symbols
+}
+
+PROTECTED_FIELDS = {'section_title', 'title', 'teacher_tip', 'teacher_closing'}
+MATH_ALLOWED_FIELDS = {'block_math', 'formulas', 'final_answer', 'function', 'derivative'}
+
+# ==================== DETECTION ====================
+
+def detect_gibberish_advanced(text: str) -> dict:
+    """
+    Advanced gibberish detection.
+    
+    Returns:
+        {
+            "has_issues": bool,
+            "issues": [...]
+        }
+    """
+    issues = []
+    
+    # 1. Reversed Hebrew
+    for wrong, correct in REPAIR_MAP.items():
+        if wrong in text and len(wrong) > 3:
+            issues.append({
+                "type": "REVERSED_HEBREW",
+                "wrong": wrong,
+                "correct": correct,
+                "fixable": True
+            })
+    
+    # 2. Broken LaTeX
+    for pattern, fix in LATEX_FIXES.items():
+        if re.search(pattern, text):
+            issues.append({
+                "type": "BROKEN_LATEX",
+                "pattern": pattern,
+                "fix": fix,
+                "fixable": True
+            })
+    
+    # 3. Hebrew inside $...$
+    hebrew_in_math = re.findall(r'\$[^$]*[\u0590-\u05FF][^$]*\$', text)
+    for match in hebrew_in_math:
+        issues.append({
+            "type": "HEBREW_IN_MATH",
+            "line": match,
+            "fixable": False,
+            "needs_llm": True
+        })
+    
+    # 4. Double $$ issues
+    if '$$$$' in text or '$$ $' in text:
+        issues.append({
+            "type": "DOUBLE_DOLLARS",
+            "fixable": True,
+            "fix": "$$"
+        })
+    
+    return {
+        "has_issues": len(issues) > 0,
+        "issues": issues
+    }
+
+
+# ==================== AUTO-FIX ====================
+
+def fix_multiline_latex_blocks(text: str) -> str:
+    """
+    V274.0: Fix multi-line LaTeX blocks that Flutter can't render.
+    
+    Converts:
+      $$$$line1
+      line2
+      line3$$$$
+    
+    To:
+      $$line1$$
+      $$line2$$
+      $$line3$$
+    """
+    def split_block(match):
+        content = match.group(1)
+        lines = [line.strip() for line in content.split('\n') if line.strip()]
+        return '\n'.join(f'$${line}$$' for line in lines)
+    
+    return re.sub(r'\$\$\$\$(.*?)\$\$\$\$', split_block, text, flags=re.DOTALL)
+
+
+def auto_fix_gibberish(text: str) -> str:
+    """Auto-fix simple gibberish issues with regex/replace."""
+    if not text:
+        return text
+
+    fixed = text
+    
+    # V274.0: Fix multi-line LaTeX blocks FIRST
+    fixed = fix_multiline_latex_blocks(fixed)
+    
+    # Fix simple artifacts
+    for wrong, correct in REPAIR_MAP.items():
+        fixed = fixed.replace(wrong, correct)
+    
+    # Fix broken LaTeX
+    for pattern, replacement in LATEX_FIXES.items():
+        fixed = re.sub(pattern, replacement, fixed)
+    
+    # Fix dollar sign glitches
+    fixed = fixed.replace('$$ $', '$$')
+    fixed = fixed.replace('$ $$', '$$')
+    
+    return fixed
+
+
+# ==================== LLM RETRY ====================
+
+async def fix_line_with_llm(problematic_line: str, llm_model) -> str:
+    """Use LLM to fix complex gibberish (e.g., Hebrew in math)."""
+    prompt = f"""FIX THIS LINE ONLY:
+Problematic: "{problematic_line}"
+
+Rules:
+1. Hebrew text OUTSIDE $...$
+2. Math INSIDE $...$
+3. NO Hebrew inside math delimiters
+
+Output: Fixed line ONLY (one line, no explanation)
+"""
+    
+    try:
+        response = await asyncio.wait_for(
+            llm_model.generate_content_async(prompt),
+            timeout=10.0
+        )
+        return response.text.strip()
+    except Exception as e:
+        print(f"⚠️ [GIBBERISH] LLM fix failed: {e}")
+        return problematic_line
+
+
+# ==================== SMART FIX ====================
+
+async def fix_gibberish_smart(text: str, llm_model=None) -> str:
+    """Smart gibberish fixing."""
+    fixed = auto_fix_gibberish(text)
+    result = detect_gibberish_advanced(fixed)
+    
+    if not result["has_issues"]:
+        return fixed
+    
+    if llm_model:
+        for issue in result["issues"]:
+            if issue.get("needs_llm"):
+                line = issue["line"]
+                fixed_line = await fix_line_with_llm(line, llm_model)
+                fixed = fixed.replace(line, fixed_line)
+    
+    return fixed
+
+
+# ==================== LEGACY INTERFACE ====================
+
+def validate_and_fix_solution(solution: Dict[str, Any]) -> Tuple[Dict[str, Any], bool, str]:
+    """Legacy interface - now uses auto-fix"""
+    fixed = copy.deepcopy(solution)
+    
+    def process(obj, field=""):
+        if isinstance(obj, dict):
+            return {k: process(v, k) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return [process(i, field) for i in obj]
+        if isinstance(obj, str):
+            return auto_fix_gibberish(_fix_string(obj, field))
+        return obj
+    
+    return process(fixed), False, ""
+
+
+def _fix_string(text: str, field: str) -> str:
+    """Legacy string fixing"""
+    if not text or text.lower() in ["none", "null"]:
+        return text
+    
+    res = text.replace(r'\f\frac', r'\frac')
+    
+    # V231.2: Skip $$ wrapping for :: format
+    if '::' in res:
+        for bad, good in REPAIR_MAP.items():
+            res = res.replace(bad, good)
+        return res
+    
+    # Hebrew-Safe $$ Rule — only for pure-math fields
+    if '\\' in res and '$$' not in res and field in MATH_ALLOWED_FIELDS:
+        if not bool(re.search(r'[\u0590-\u05FF]', res)):
+            res = f"$${res.replace('$', '')}$$"
+    
+    for bad, good in REPAIR_MAP.items():
+        res = res.replace(bad, good)
+    
+    return res
+
+
+def format_solution(data):
+    return data
+
+
+# ==================== USAGE EXAMPLE ====================
+
+if __name__ == "__main__":
+    test_text = "נשתמש בנוסחה $x = \\frac{1}{2}$ ונקבל \\rac{x}{y}"
+    
+    result = detect_gibberish_advanced(test_text)
+    print(f"Issues found: {result}")
+    
+    fixed = auto_fix_gibberish(test_text)
+    print(f"Auto-fixed: {fixed}")

main.py

@@ -0,0 +1,220 @@
+# main.py - V5.8.0 (MULTIPART & OPENCV BASE + INFRA HARDENING)
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException, Request
+from fastapi.responses import JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from sse_starlette.sse import EventSourceResponse
+from typing import Optional
+import logging
+import base64
+import json
+import io
+import sys
+import os
+import asyncio
+from pydantic import BaseModel
+from typing import Any
+
+class AskQuestionRequest(BaseModel):
+    context_data: dict | Any
+    question: str
+    student_name: str = "תלמיד"
+
+# --- HEALTH CHECK : Top-level Dependency Verification ---
+# We do this before standard imports to ensure a clear error message 
+# if the virtual environment is inactive and libraries are missing.
+try:
+    import cv2
+    import numpy as np
+except ModuleNotFoundError as e:
+    print(f"🔥 [HEALTH-CHECK FAILED] Missing critical dependency: {e}. Are you running inside the .venv?")
+    sys.exit(1)
+
+from orchestrator import orchestrator, build_standard_response
+from quota_system import quota_manager
+from config import IS_PRODUCTION, ENV
+
+if hasattr(sys.stdout, 'reconfigure'):
+    sys.stdout.reconfigure(encoding='utf-8')
+
+# הגדרת לוגר HamoraServer
+try:
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        handlers=[
+            logging.FileHandler("server.log", encoding="utf-8"),
+            logging.StreamHandler(sys.stdout)
+        ]
+    )
+except PermissionError:
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        handlers=[logging.StreamHandler(sys.stdout)]
+    )
+
+logger = logging.getLogger("HamoraServer")
+
+# --- INFRA HARDENING: Global Async Exception Handler ---
+def custom_async_exception_handler(loop, context):
+    """
+    Catches unhandled asynchronous exceptions to prevent the Event Loop from crashing.
+    """
+    msg = context.get("exception", context["message"])
+    logger.critical(f"🚨 [ASYNC-CRASH-PREVENTION] Caught unhandled exception in Event Loop: {msg}")
+    # The loop remains alive. We just log the critical error.
+
+# --- INFRA HARDENING: Health Check Function ---
+def verify_system_health():
+    """
+    Verifies execution environment and critical dependencies.
+    """
+    logger.info("🩺 [HEALTH-CHECK] Verifying core dependencies and environment...")
+    
+    # Check if running in a virtual environment
+    if sys.prefix == sys.base_prefix:
+        logger.warning("⚠️ [HEALTH-CHECK] Not running inside a virtual environment (.venv). Proceeding anyway...")
+        
+    logger.info(f"✅ [HEALTH-CHECK] cv2 version: {cv2.__version__}, numpy: {np.__version__}")
+    logger.info(f"✅ [HEALTH-CHECK] Environment: {ENV.upper()}, Production Mode: {IS_PRODUCTION}")
+
+# --- INFRA HARDENING: Lifespan Context Manager ---
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup Phase
+    verify_system_health()
+    
+    # Register Global Async Exception Handler
+    loop = asyncio.get_running_loop()
+    loop.set_exception_handler(custom_async_exception_handler)
+    logger.info("🛡️ [STARTUP] Global Async Exception Handler registered.")
+    
+    yield # Yield control back to FastAPI
+    
+    # Shutdown Phase
+    logger.info("🛑 [SHUTDOWN] BuddyMath Server is shutting down cleanly.")
+
+
+# Application Setup
+app = FastAPI(title="BuddyMath Server - OpenCV Engine", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Static files for audio fallback
+os.makedirs("/tmp/static", exist_ok=True)
+app.mount("/static", StaticFiles(directory="/tmp/static"), name="static")
+
+@app.get("/")
+async def root():
+    return {"status": f"BuddyMath API V5.8.0 ({ENV.upper()})", "engine": "OpenCV Base + Infra Hardening"}
+
+@app.post("/solve_stream")
+async def solve_stream(
+    user: Optional[str] = Form(None),
+    student_name: Optional[str] = Form(None),
+    grade: str = Form("י'"),
+    student_gender: str = Form("M"),
+    mode: str = Form("solve"),
+    user_note: Optional[str] = Form(None),
+    file: UploadFile = File(...)
+):
+    """
+    V5.8.0: המורה למתמטיקה - Multipart & OpenCV Base.
+    מקבל קובץ ישירות מהפלאטר ומפענח אותו עם OpenCV.
+    """
+    final_student_name = student_name or user or "תלמיד"
+    print(f"🚀 🟢 BIT-LOG: Received Multipart request from {final_student_name}. Grade: {grade}")
+    
+    # Quota Check
+    is_allowed, msg, current_usage, limit = quota_manager.check_limit(final_student_name)
+    if not is_allowed:
+        response_content = build_standard_response(
+            final_answer=f"הגעת למכסה היומית ({limit} שאלות)",
+            teacher_summary="נא להמתין למחר לקבלת מכסה חדשה.",
+            logic_error=True,
+            response_type="error"
+        )
+        response_content["error"] = "QUOTA_EXCEEDED" 
+        return JSONResponse(status_code=429, content=response_content)
+    quota_manager.increment_usage(final_student_name)
+
+    try:
+        # 1. קריאת הבינארי
+        image_bytes = await file.read()
+        print(f"📸 [BIT-LOG] Image received. Size: {len(image_bytes)} bytes")
+
+        # 2. OpenCV Decoder
+        nparr = np.frombuffer(image_bytes, np.uint8)
+        img_cv2 = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+        
+        if img_cv2 is None:
+            print("❌ [BIT-LOG] OpenCV failed to decode image!")
+            raise HTTPException(status_code=400, detail="Invalid image data")
+
+        print(f"✅ [BIT-LOG] OpenCV Matrix Ready: {img_cv2.shape}")
+
+        # 3. OCR & Solving Pipeline (Streaming)
+        print("🚀 [TRACE-MAIN] Initiating streaming orchestrator.solve_problem...")
+
+        async def event_generator():
+            try:
+                async for event in orchestrator.solve_problem(
+                    problem_text="", # Will be extracted by OCR
+                    grade=grade,
+                    student_name=final_student_name,
+                    student_gender=student_gender,
+                    user_note=user_note,
+                    image_data=image_bytes,
+                    mode=mode
+                ):
+                    # SSE Protocol: yield a dict with "data" key
+                    yield {
+                        "event": "message",
+                        "id": event.question_id,
+                        "data": event.model_dump_json() # Pydantic v2
+                    }
+            except Exception as e:
+                logger.error(f"STREAMING ERROR: {e}")
+                yield {
+                    "event": "error",
+                    "data": json.dumps({"error": str(e)})
+                }
+
+        return EventSourceResponse(event_generator())
+
+    except Exception as e:
+        logger.exception("CRITICAL FLOW ERROR")
+        print(f"🔥 [BIT-LOG] CRITICAL ERROR: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        response_content = build_standard_response(
+            final_answer="שגיאה בפענוח התמונה או התרגיל",
+            teacher_summary="המורה למתמטיקה מתנצל, אך חלה שגיאה לא צפויה.",
+            logic_error=True,
+            response_type="error"
+        )
+        return JSONResponse(status_code=500, content=response_content)
+
+@app.post("/explain_step")
+async def explain_step(request: Request):
+    data = await request.json()
+    res = await orchestrator.explain_specific_step(data.get("context"), data.get("step_text"), data.get("student_name"))
+    return JSONResponse(content=res)
+
+@app.post("/ask_question")
+async def ask_question(request: AskQuestionRequest):
+    data = request.dict()
+    res = await orchestrator.ask_question(data.get("context_data"), data.get("question"), data.get("student_name"))
+    return JSONResponse(content=res)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

math_engine.py

@@ -0,0 +1,154 @@
+import sympy as sp
+
+class MathContext:
+    """
+    A sandbox for the LLM to execute mathematics.
+    Each operation is recorded with Hebrew context and exact LaTeX representation.
+    """
+    def __init__(self):
+        self.steps = []
+        
+        # Injected SymPy helpers
+        self.sp = sp
+        self.Eq = sp.Eq
+        self.solve = sp.solve
+        self.expand = sp.expand
+        self.simplify = sp.simplify
+        self.sqrt = sp.sqrt
+        self.diff = sp.diff
+
+    def _format_latex(self, expr) -> str:
+        """Converts SymPy to precise LaTeX, without $$ so it renders correctly in Flutter."""
+        if isinstance(expr, str):
+            # If the LLM passed a string instead of SymPy object, try parsing it
+            try:
+                expr = sp.sympify(expr)
+            except:
+                pass # Return as-is if not parseable
+
+        latex_str = sp.latex(expr)
+        return latex_str
+
+    def explain(self, text: str):
+        """Adds a pure Hebrew explanation step without math."""
+        self.steps.append({
+            "content_mixed": text,
+            "block_math": ""
+        })
+
+    def declare_equation(self, text: str, eq: sp.Eq):
+        """Prints a known equation with its explanation."""
+        self.steps.append({
+            "content_mixed": text,
+            "block_math": self._format_latex(eq)
+        })
+        return eq
+
+    def expand_expr(self, text: str, expr):
+        """Expands an expression completely (e.g. squaring a root)."""
+        expanded = sp.expand(expr)
+        self.steps.append({
+            "content_mixed": text,
+            "block_math": self._format_latex(expanded)
+        })
+        return expanded
+
+    def solve_equation(self, text: str, eq: sp.Eq, var):
+        """Solves an equation for a specific variable."""
+        solutions = sp.solve(eq, var)
+        
+        # Format solutions nicely
+        if isinstance(solutions, list):
+            if len(solutions) == 1:
+                math_result = sp.Eq(var, solutions[0])
+            else:
+                # E.g. x_1 = 2, x_2 = -2
+                parts = [f"{sp.latex(var)}_{{{i+1}}} = {sp.latex(sol)}" for i, sol in enumerate(solutions)]
+                math_result = " \\text{ ואו } ".join(parts)
+        else:
+            math_result = sp.Eq(var, solutions)
+
+        self.steps.append({
+            "content_mixed": text,
+            "block_math": math_result if isinstance(math_result, str) else self._format_latex(math_result)
+        })
+        return solutions
+
+    def finish(self, final_answer: str, teacher_summary: str = ""):
+        """Sets the final human-readable answer for the UI."""
+        self.final_answer = final_answer
+        self.teacher_summary = teacher_summary
+
+def run_llm_code(python_code: str) -> dict:
+    """
+    Executes the LLM-generated Python code in our secure MathContext.
+    Returns the step-by-step UI format required by BuddyMath.
+    """
+    ctx = MathContext()
+    
+    # Secure Globals the LLM is allowed to use
+    safe_globals = {
+        "ctx": ctx,
+        "x": sp.Symbol('x'),
+        "y": sp.Symbol('y'),
+        "a": sp.Symbol('a'),
+        "b": sp.Symbol('b'),
+        "c": sp.Symbol('c'),
+        "m": sp.Symbol('m'),
+        "R": sp.Symbol('R'),
+        "sp": sp,
+    }
+
+    try:
+        # Execute the LLM's dynamically generated mathematics
+        exec(python_code, safe_globals)
+        
+        return {
+            "success": True,
+            "steps": ctx.steps,
+            "final_answer": getattr(ctx, 'final_answer', "הגענו לפתרון."),
+            "teacher_summary": getattr(ctx, 'teacher_summary', "")
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+if __name__ == "__main__":
+    # Simulate LLM output to solve a Locus / Parabola problem:
+    # "The distance from (x, y) to (2, 0) is equal to its distance to x = -2."
+    
+    llm_code = """
+ctx.explain("נסמן את הנקודה הכללית על המקום הגיאומטרי כ- (x,y). לפי הנתון, המרחק מהמוקד שווה למרחק מהמדריך.")
+d1 = sp.sqrt((x - 2)**2 + (y - 0)**2)  # מוקד
+d2 = sp.sqrt((x - (-2))**2)          # מדריך
+
+eq1 = ctx.declare_equation("המשוואה המשווה בין המרחקים היא:", ctx.Eq(d1, d2))
+
+ctx.explain("נעלה את שני האגפים בריבוע כדי להיפטר מהשורש:")
+# SymPy understands squaring both sides! We square them and declare equality.
+squared_eq = ctx.Eq(d1**2, d2**2)
+ctx.steps[-1]["block_math"] = ctx._format_latex(squared_eq) # Override previous block math
+
+# Now expand and simplify it beautifully
+expanded_eq = ctx.declare_equation("נרחיב את הביטויים (פתיחת סוגריים מלאה):", ctx.Eq(ctx.expand(squared_eq.lhs), ctx.expand(squared_eq.rhs)))
+
+# SymPy's powerful simplify equation solver (subtract RHS from LHS)
+simplified_expr = ctx.simplify(expanded_eq.lhs - expanded_eq.rhs)
+final_eq = ctx.declare_equation("לאחר כינוס איברים והעברת אגפים, נקבל את צורת הפרבולה הפשוטה:", ctx.Eq(simplified_expr, 0))
+
+# Also isolate y^2 if needed
+y_sq_isolated = ctx.solve(final_eq, y**2)
+if y_sq_isolated:
+    ctx.declare_equation("נבודד את y^2 במשוואה:", ctx.Eq(y**2, y_sq_isolated[0]))
+
+ctx.finish("$$ y^2 = 8x $$")
+"""
+    
+    print("🚀 Running LLM Mathematics Script:")
+    result = run_llm_code(llm_code)
+    
+    import json
+    # Print the resulting UI object
+    print(json.dumps(result, indent=2, ensure_ascii=False))

math_intent_detector.py

@@ -0,0 +1,132 @@
+# math_intent_detector.py - V4.2 (Intent Lockdown)
+# Rigidly classifies user intent before mathematical planning.
+
+import re
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Rigid intent categories
+INTENT_SIMPLE_LINEAR = "SIMPLE_LINEAR_SOLVE"
+INTENT_WORD_PROBLEM_BASIC = "WORD_PROBLEM_BASIC"
+INTENT_FUNCTION_ANALYSIS = "FUNCTION_ANALYSIS"
+INTENT_SYSTEM_EQUATIONS = "SYSTEM_EQUATIONS"
+INTENT_GENERAL = "GENERAL"
+# V286.0: New intent categories for 5-unit math coverage
+INTENT_VECTORS_3D = "VECTORS_3D"
+INTENT_SOLID_GEOMETRY = "SOLID_GEOMETRY"
+INTENT_OPTIMIZATION = "OPTIMIZATION"
+INTENT_PROBABILITY = "PROBABILITY"
+INTENT_TRIGONOMETRY = "TRIGONOMETRY"
+INTENT_LOGARITHMS = "LOGARITHMS"
+INTENT_LIMITS = "LIMITS"
+
+def detect_intent(text: str, grade_num: int) -> str:
+    """
+    Detects the rigid intent category based on keywords and grade boundaries.
+    Focuses on 'Simplifying' intent for lower grades.
+    """
+    text_lower = text.lower()
+    
+    # 1. Simple Linear Solve (Grade 7 focus)
+    # Check for basic algebra keywords and lack of complex concepts
+    simple_linear_keywords = ["x=", "פתור", "משוואה", "נעלם"]
+    is_simple_algebra = any(kw in text_lower for kw in simple_linear_keywords)
+    
+    # Exclusion markers for simple intent
+    complex_markers = ["נגזרת", "קיצון", "מערכת", "שני נעלמים", "x^2", "x²"]
+    has_complex_content = any(cm in text_lower for cm in complex_markers)
+    
+    if grade_num == 7 and is_simple_algebra and not has_complex_content:
+        print("🎯 [INTENT] Classified as SIMPLE_LINEAR_SOLVE (Grade 7 Lockdown)")
+        return INTENT_SIMPLE_LINEAR
+
+    # 2. Word Problem Basic
+    word_problem_keywords = ["בעיה", "מילולית", "קנה", "מחיר", "סך הכל"]
+    if any(kw in text_lower for kw in word_problem_keywords):
+        print("🎯 [INTENT] Classified as WORD_PROBLEM_BASIC")
+        return INTENT_WORD_PROBLEM_BASIC
+
+    # 3. System of Equations
+    if "מערכת" in text_lower or "שני נעלמים" in text_lower:
+        print("🎯 [INTENT] Classified as SYSTEM_EQUATIONS")
+        return INTENT_SYSTEM_EQUATIONS
+
+    # 4. Function Analysis
+    function_markers = ["נגזרת", "קיצון", "חקירה", "פונקציה", "f(x)"]
+    if any(fm in text_lower for fm in function_markers):
+        print("🎯 [INTENT] Classified as FUNCTION_ANALYSIS")
+        return INTENT_FUNCTION_ANALYSIS
+
+    # V286.0: 5-unit intent categories
+    # 5. Vectors 3D
+    if any(kw in text_lower for kw in ["וקטור", "וקטורים", "מכפלה סקלרית", "מכפלה וקטורית"]):
+        if any(kw in text_lower for kw in ["מרחב", "מישור", "תלת", "z"]):
+            print("🎯 [INTENT] Classified as VECTORS_3D")
+            return INTENT_VECTORS_3D
+
+    # 6. Solid Geometry
+    if any(kw in text_lower for kw in ["פירמידה", "מנסרה", "תיבה", "חתך", "אפותם", "פאות"]):
+        print("🎯 [INTENT] Classified as SOLID_GEOMETRY")
+        return INTENT_SOLID_GEOMETRY
+
+    # 7. Optimization
+    if any(kw in text_lower for kw in ["מקסימום", "מינימום", "מקסימלי", "מינימלי", "ערך מרבי", "ערך מזערי", "שטח גדול ביותר", "נפח מקסימלי"]):
+        print("🎯 [INTENT] Classified as OPTIMIZATION")
+        return INTENT_OPTIMIZATION
+
+    # 8. Probability
+    if any(kw in text_lower for kw in ["הסתברות", "קומבינטור", "תמורה", "צירוף", "בייס"]):
+        print("🎯 [INTENT] Classified as PROBABILITY")
+        return INTENT_PROBABILITY
+
+    # 9. Trigonometry
+    if any(kw in text_lower for kw in ["sin", "cos", "tan", "טריגונומטר", "סינוס", "קוסינוס"]):
+        print("🎯 [INTENT] Classified as TRIGONOMETRY")
+        return INTENT_TRIGONOMETRY
+
+    # 10. Logarithms
+    if any(kw in text_lower for kw in ["לוגריתם", "log", "ln", "מעריכי"]):
+        print("🎯 [INTENT] Classified as LOGARITHMS")
+        return INTENT_LOGARITHMS
+
+    # 11. Limits
+    if any(kw in text_lower for kw in ["גבול", "lim", "שואף", "לופיטל"]):
+        print("🎯 [INTENT] Classified as LIMITS")
+        return INTENT_LIMITS
+
+def _extract_grade_number(text: str) -> int:
+    import re
+    # מחלץ מספר מתוך מחרונה (למשל "ז׳" או "כיתה 7")
+    match = re.search(r'\d+', text)
+    if match:
+        return int(match.group())
+    # מיפוי ידני למקרים של אותיות
+    mapping = {'ז': 7, 'ח': 8, 'ט': 9, 'י': 10, 'יא': 11, 'יב': 12}
+    for char, num in mapping.items():
+        if char in text:
+            return num
+    return -1
+
+def get_intent_contract(intent: str, grade_num: int) -> dict:
+    """
+    Returns the 'Action Contract' for the given intent.
+    This contract is used to constrain the LLM/Solver.
+    """
+    if intent == INTENT_SIMPLE_LINEAR and grade_num == 7:
+        return {
+            "max_variables": 1,
+            "allowed_operators": ["ADD", "SUB", "MUL", "DIV"],
+            "forbidden_strategies": ["DERIVATIVES", "SYSTEM_OF_EQUATIONS", "COMPLEX_SUBSTITUTION"],
+            "variable_preference": "x",
+            "narrative_tone": "simple_step_by_step"
+        }
+    
+    if intent == INTENT_WORD_PROBLEM_BASIC:
+        return {
+             "max_variables": 2 if grade_num > 8 else 1,
+             "focus": "translation_to_algebra",
+             "forbidden_strategies": ["CALCULUS"]
+        }
+        
+    return {"status": "unconstrained"}

math_parser.py

@@ -0,0 +1,183 @@
+import re
+import json
+import logging
+from typing import List, Dict
+from enum import Enum
+
+logger = logging.getLogger("MathParser")
+
+class MathMode(Enum):
+    INLINE = "inline"
+    DISPLAY = "display"
+
+class MathSegmenter:
+    @staticmethod
+    def segment_text_with_math(text: str) -> List[Dict]:
+        """
+        Convert natural text with $math$ to structured segments.
+        Combines V68 protections with V70 logic.
+        """
+        # 1. Memory Protection (V68 Feature)
+        if not text:
+            return [{"type": "text", "value": "", "direction": "rtl"}]
+        
+        if len(text) > 50000:
+             logger.warning(f"⚠️ Input text too long ({len(text)}), truncating.")
+             text = text[:50000] + "... (truncated)"
+
+        if '$' not in text:
+            return [{"type": "text", "value": text.strip(), "direction": "rtl"}]
+        
+        segments = []
+        pos = 0
+        text_len = len(text)
+        max_iterations = 5000 # Safety limit
+        
+        iteration = 0
+        while pos < text_len and iteration < max_iterations:
+            iteration += 1
+            dollar_idx = text.find('$', pos)
+            
+            if dollar_idx == -1:
+                remaining = text[pos:]
+                if remaining.strip():
+                    segments.append(MathSegmenter._create_text_segment(remaining))
+                break
+            
+            is_double = (dollar_idx + 1 < text_len and text[dollar_idx + 1] == '$')
+            
+            if dollar_idx > pos:
+                text_before = text[pos:dollar_idx]
+                if text_before.strip():
+                    segments.append(MathSegmenter._create_text_segment(text_before))
+            
+            if is_double:
+                close_idx = text.find('$$', dollar_idx + 2)
+                if close_idx == -1:
+                    segments.append(MathSegmenter._create_text_segment('$$'))
+                    pos = dollar_idx + 2
+                    continue
+                math_content = text[dollar_idx + 2:close_idx].strip()
+                if math_content:
+                    segments.append({"type": "math", "mode": "display", "value": math_content, "direction": "ltr"})
+                pos = close_idx + 2
+            else:
+                close_idx = text.find('$', dollar_idx + 1)
+                if close_idx == -1:
+                    segments.append(MathSegmenter._create_text_segment('$'))
+                    pos = dollar_idx + 1
+                    continue
+                math_content = text[dollar_idx + 1:close_idx].strip()
+                if math_content:
+                    segments.append({"type": "math", "mode": "inline", "value": math_content, "direction": "ltr"})
+                pos = close_idx + 1
+        
+        if not segments:
+            return [{"type": "text", "value": text, "direction": "rtl"}]
+        
+        return MathSegmenter._merge_text_segments(segments)
+    
+    @staticmethod
+    def _create_text_segment(text: str) -> Dict:
+        cleaned = text
+        # Safe RLM injection (V70 Logic)
+        RLM = chr(0x200f)
+        if cleaned.strip() and MathSegmenter._ends_with_hebrew(cleaned.strip()):
+            cleaned = cleaned.rstrip() + RLM
+        return {"type": "text", "value": cleaned, "direction": "rtl"}
+    
+    @staticmethod
+    def _ends_with_hebrew(text: str) -> bool:
+        if not text: return False
+        last_char = text[-1]
+        return '\u0590' <= last_char <= '\u05FF'
+    
+    @staticmethod
+    def _merge_text_segments(segments: List[Dict]) -> List[Dict]:
+        if not segments: return []
+        merged = []
+        curr_text = ""
+        for seg in segments:
+            if seg["type"] == "text":
+                curr_text += seg["value"]
+            else:
+                if curr_text:
+                    merged.append(MathSegmenter._create_text_segment(curr_text))
+                    curr_text = ""
+                merged.append(seg)
+        if curr_text:
+            merged.append(MathSegmenter._create_text_segment(curr_text))
+        return merged
+
+    @staticmethod
+    def segments_to_safe_string(segments: List[Dict]) -> str:
+        """
+        Reconstructs string safely.
+        Uses ONLY RLM (V70 Safe Logic) - NO LRE/PDF to avoid stream crashes.
+        """
+        result_parts = []
+        RLM = chr(0x200f)
+        
+        for i, segment in enumerate(segments):
+            if segment["type"] == "text":
+                text = segment["value"]
+                # Ensure Hebrew ends with RLM
+                if text.strip() and MathSegmenter._ends_with_hebrew(text.strip()):
+                     if not text.endswith(RLM):
+                        text += RLM
+                result_parts.append(text)
+            
+            elif segment["type"] == "math":
+                math_val = segment["value"]
+                
+                # Spacing logic
+                prefix = ""
+                suffix = ""
+                if i > 0 and segments[i-1]["type"] == "text":
+                    if not segments[i-1]["value"].endswith(" ") and not segments[i-1]["value"].endswith(RLM):
+                         prefix = " "
+                if i < len(segments)-1 and segments[i+1]["type"] == "text":
+                    if not segments[i+1]["value"].startswith(" "):
+                        suffix = " "
+
+                # Simple wrap: Just Math + RLM.
+                if segment.get("mode") == "display":
+                    formatted_math = f"$${math_val}$${RLM}"
+                else:
+                    formatted_math = f"${math_val}${RLM}"
+                
+                result_parts.append(prefix + formatted_math + suffix)
+                
+        return "".join(result_parts)
+
+    @staticmethod
+    def aggregate_math(segments: List[Dict]) -> str:
+        """
+        Collects all math for the gray box.
+        Uses simple keywords (V70 Safe Logic) to avoid Regex OOM.
+        """
+        math_blocks = []
+        keywords = ['=', '\\frac', '\\sqrt', '\\cdot', 'A', 'B', 'C', 'D', 'M', 'x', 'y']
+        
+        for seg in segments:
+            if seg["type"] == "math":
+                val = seg["value"]
+                if seg.get("mode") == "display":
+                    clean_val = val.replace('$$', '')
+                    math_blocks.append(clean_val)
+                else:
+                    if len(val) > 1 and any(k in val for k in keywords):
+                         math_blocks.append(val)
+        
+        seen = set()
+        unique_blocks = []
+        for m in math_blocks:
+            if m not in seen:
+                unique_blocks.append(m)
+                seen.add(m)
+        
+        # Guard against huge aggregation (V68 Protection)
+        result = " \\\\ ".join(unique_blocks)
+        if len(result) > 2000:
+            return result[:2000] + "..."
+        return result

math_sanitizer.py

@@ -0,0 +1,94 @@
+# math_sanitizer.py - V1.1 ProductionMathSanitizer
+import re
+import logging
+
+logger = logging.getLogger(__name__)
+
+class ProductionMathSanitizer:
+    @staticmethod
+    def normalize_latex(latex_str: str) -> str:
+        """
+        V1.1: Standardizes LaTeX for SymPy and LLM comparison.
+        """
+        if not latex_str: return ""
+        
+        # 1. Basic Cleaning
+        clean = latex_str.strip()
+        clean = clean.replace(r'\ ', '')
+        clean = clean.replace(r'\times', '*')
+        clean = clean.replace(r'\cdot', '*')
+        
+        # 2. Bracket Normalization
+        clean = clean.replace(r'\left(', '(').replace(r'\right)', ')')
+        clean = clean.replace(r'\left[', '[').replace(r'\right]', ']')
+        clean = clean.replace('{', '(').replace('}', ')')
+        
+        # 3. Fractions
+        while r'\frac' in clean:
+            clean = re.sub(r'\\frac\s*\((.*?)\)\((.*?)\)', r'(\1)/(\2)', clean)
+            if r'\frac' in clean and '(' not in clean: # Fallback for simple fractions
+                 clean = re.sub(r'\\frac\s*(.*?)\s*(.*?)', r'(\1)/(\2)', clean)
+        
+        # 4. Implicit Multiplication Guard (V1.1)
+        clean = re.sub(r'(\d)([a-zA-Z(])', r'\1*\2', clean)
+        clean = re.sub(r'\)([a-zA-Z0-9(])', r')*\1', clean)
+        
+        return clean
+
+    @staticmethod
+    def validate_semantic_completeness(anchor_data: dict, formula_tokens: list[str]) -> bool:
+        """
+        V1.1: Partial Semantic Recovery Check.
+        Returns True if the missing tokens are non-critical.
+        """
+        # Logic to check if critical variables/values are missing
+        # For now, a simple check if the main function key is present.
+        critical_keys = ['function_equations', 'equations']
+        for key in critical_keys:
+            if key in anchor_data and anchor_data[key]:
+                return True
+        return False
+
+    @staticmethod
+    def get_symbolic_bridge(proof_graph) -> str:
+        """
+        V1.1: Zero Hallucination Bridge.
+        Converts the Immutable ProofGraph to a clean mathematical context for the LLM.
+        """
+        bridge = "════════════════════════════════════════\n"
+        bridge += "📜 VERIFIED SYMBOLIC BRIDGE (V1.1):\n"
+        bridge += "════════════════════════════════════════\n"
+        for step in proof_graph.steps:
+            bridge += f"Step {step.step_id}: {step.math_content} ({step.logic_description or ''})\n"
+            
+            # V6 Ontology Injection
+            if hasattr(step, 'allowed_concepts') and getattr(step, 'allowed_concepts'):
+                concepts_str = ", ".join(step.allowed_concepts)
+                tag = getattr(step, 'pedagogical_tag', 'כללי')
+                bridge += f"For step {step.step_id}, your pedagogical_tag is '{tag}'. You MUST build your explanation using ONLY the concepts from this list: [{concepts_str}]. Do NOT introduce any other mathematical concepts. Keep it under 2 sentences.\n"
+
+        bridge += "════════════════════════════════════════\n"
+        bridge += "RULE: USE ONLY THE DATA ABOVE. DO NOT HALLUCINATE OR CHANGE MATH.\n"
+        return bridge
+
+def sanitize_math_ocr_hotfix(text: str) -> str:
+    """
+    V1.1.1 Aggressive Sanitizer: Removes all spaces and fixes frac regex.
+    Fixes failures caused by leading spaces or visual artifacts.
+    """
+    if not text: return ""
+
+    # תיקון קריטי: הסרת כל הרווחים למניעת כשלי Regex (פתרון לשאלה 2 ו-3)
+    text = text.replace(" ", "")
+
+    # ניקוי שאריות ויזואליות
+    text = text.replace("\\left", "").replace("\\right", "")
+
+    # נרמול שברים (עובד עכשיו על מחרוזת נקייה מרווחים)
+    import re
+    text = re.sub(
+        r"frac\(([^()]+)\)\(([^()]+)\)",
+        lambda m: f"(({m.group(1)})/({m.group(2)}))",
+        text
+    )
+    return text.strip()

memory_service.py

@@ -0,0 +1,155 @@
+# memory_service.py
+"""
+Buddy Math - Memory Service (Pinecone Edition)
+==============================================
+גרסה v2.1: שיפור מנגנון זיהוי הדמיון.
+במקום לבדוק סדר מילים (שנשבר ב-OCR), בודקים חפיפת מילים (Jaccard).
+"""
+
+import os
+import json
+import logging
+import uuid
+import re
+from typing import Optional, Dict
+
+from sentence_transformers import SentenceTransformer
+from pinecone import Pinecone
+
+logger = logging.getLogger("MemoryService")
+
+class MemoryService:
+    def __init__(self):
+        self.api_key = os.environ.get("PINECONE_API_KEY")
+        
+        if not self.api_key:
+            logger.warning("⚠️ PINECONE_API_KEY not found! Memory will be disabled.")
+            self.index = None
+            return
+
+        try:
+            self.pc = Pinecone(api_key=self.api_key)
+            self.index_name = "buddy-math"
+            self.index = self.pc.Index(self.index_name)
+            
+            logger.info("⏳ Loading embedding model...")
+            self.embedder = SentenceTransformer('all-MiniLM-L6-v2')
+            
+            logger.info("✅ Brain initialized (Pinecone + MiniLM)")
+            
+        except Exception as e:
+            logger.error(f"❌ Failed to init Pinecone: {e}")
+            self.index = None
+
+    def find_similar_solution(self, problem_text: str, vector_threshold: float = 0.85) -> Optional[Dict]:
+        """
+        מחפש פתרון בזיכרון. 
+        מבצע אימות כפול: וקטורי (משמעות) + חפיפת מילים (תוכן).
+        """
+        if not self.index: return None
+        
+        try:
+            # 1. חיפוש וקטורי (מהיר)
+            vector = self.embedder.encode(problem_text).tolist()
+            
+            results = self.index.query(
+                vector=vector,
+                top_k=1,
+                include_metadata=True
+            )
+            
+            if not results['matches']:
+                return None
+                
+            match = results['matches'][0]
+            vector_score = match['score']
+            
+            # בדיקת סף וקטורי
+            if vector_score < vector_threshold:
+                return None
+
+            # שליפת הטקסט המקורי מהזיכרון
+            cached_text = match['metadata'].get('text', '')
+            
+            # 2. בדיקת דמיון משופרת (Jaccard Similarity)
+            # בודקים כמה מילים משותפות יש, בלי קשר לסדר
+            text_similarity = self._calculate_jaccard_similarity(problem_text, cached_text)
+            
+            logger.info(f"🧠 Brain Check: Vector={vector_score:.3f}, Jaccard={text_similarity:.3f}")
+
+            # הורדנו את הרף ל-30% חפיפה (מספיק לזיהוי אותה שאלה ב-OCR משובש)
+            if text_similarity < 0.3:
+                logger.warning("⚠️ High vector score but low text overlap. Ignoring.")
+                return None
+                
+            # שליפת ה-JSON
+            solution_json = match['metadata'].get('solution_json')
+            if solution_json:
+                logger.info("🧠 Brain HIT! Verified match found.")
+                return json.loads(solution_json)
+            
+            return None
+            
+        except Exception as e:
+            logger.error(f"Memory search failed: {e}")
+            return None
+
+    def learn_solution(self, problem_text: str, solution_data: dict):
+        """שומר פתרון חדש"""
+        if not self.index: return
+        
+        try:
+            clean_text = problem_text.strip()
+            if len(clean_text) < 10: return
+
+            vector = self.embedder.encode(clean_text).tolist()
+            json_str = json.dumps(solution_data, ensure_ascii=False)
+            
+            # הגנה: Pinecone מגביל Metadata ל-40KB
+            if len(json_str.encode('utf-8')) > 38000:
+                logger.warning("⚠️ Solution too big for memory. Skipping save.")
+                return
+
+            metadata = {
+                "text": clean_text[:1000], 
+                "topic": solution_data.get("meta", {}).get("topic", "unknown"),
+                "solution_json": json_str
+            }
+            
+            self.index.upsert(vectors=[{
+                "id": str(uuid.uuid4()),
+                "values": vector,
+                "metadata": metadata
+            }])
+            
+            logger.info("🧠 Brain LEARNED and saved to Cloud!")
+            
+        except Exception as e:
+            logger.error(f"Memory learn failed: {e}")
+
+    def _calculate_jaccard_similarity(self, text1: str, text2: str) -> float:
+        """
+        מחשב דמיון לפי חפיפת מילים (מתעלם מסדר המילים).
+        טוב ל-OCR עברית/אנגלית שמתהפך.
+        """
+        # ניקוי ופירוק למילים ייחו��יות (Tokens)
+        tokens1 = self._tokenize(text1)
+        tokens2 = self._tokenize(text2)
+        
+        if not tokens1 or not tokens2:
+            return 0.0
+            
+        # חיתוך (מילים משותפות) חלקי איחוד (כל המילים)
+        intersection = len(tokens1.intersection(tokens2))
+        union = len(tokens1.union(tokens2))
+        
+        return intersection / union
+
+    def _tokenize(self, text: str) -> set:
+        """מפרק טקסט לסט של מילים נקיות"""
+        # משאיר רק אותיות ומספרים
+        clean = re.sub(r'[^\w\s]', '', text)
+        # פירוק למילים
+        words = clean.lower().split()
+        # מסנן מילים קצרות מדי (כמו "של", "את")
+        return {w for w in words if len(w) > 1}

micro_prompts.py

@@ -0,0 +1,200 @@
+# micro_prompts.py — Textbook JSON / Hebrew Centric
+
+# Topic-specific micro-prompts for BuddyMath
+# ALL TEMPLATES: enforce [{type: "text"|"math", content: "..."}] JSON only.
+# ZERO mentions of ctx, sp, sympy, MathEngine, or Python.
+
+"""
+Micro-Prompt Library
+Each entry adds topic-specific focus on TOP of the specialist prompt in prompts.py.
+The specialist prompt already defines the full Textbook JSON schema — these just
+focus the LLM on which formula/technique to use.
+"""
+
+import json  # needed by get_general_prompt
+
+# ==================== MICRO-PROMPT TEMPLATES ====================
+# Each template is a SHORT topic-focused instruction.
+# It is prepended to the full specialist prompt (which already has the JSON schema).
+# DO NOT add any output format instructions here — the specialist prompt handles that.
+
+MICRO_PROMPTS = {
+
+    # ========== GEOMETRY ==========
+
+    "CIRCLE_EQUATION": {
+        "template": """🎯 נושא: משוואת מעגל / מקום גיאומטרי
+השתמש בנוסחה: (x-a)² + (y-b)² = r²
+זהה: מרכז (a,b) ורדיוס r מהנתונים. הצב. פשט. הגדר.</p>""",
+        "tokens": 60,
+        "requires": []
+    },
+
+    "CIRCLE_TANGENT": {
+        "template": """🎯 נושא: משיק למעגל בנקודה
+שלב 1: בדוק שהנקודה על המעגל.
+שלב 2: מצא שיפוע הרדיוס (מהמרכז לנקודה).
+שלב 3: שיפוע המשיק = -1 / שיפוע הרדיוס (מאונך). כתוב משוואת ישר.""",
+        "tokens": 70,
+        "requires": []
+    },
+
+    "TRIANGLE_AREA": {
+        "template": """🎯 נושא: שטח משולש
+נוסחה: S = ½ × בסיס × גובה. הצב וחשב.""",
+        "tokens": 40,
+        "requires": []
+    },
+
+    "LINE_EQUATION": {
+        "template": """🎯 נושא: משוואת ישר
+מצא שיפוע m ונקודת חיתוך b. כתוב: y = mx + b.""",
+        "tokens": 40,
+        "requires": []
+    },
+
+    "LINE_PERPENDICULAR": {
+        "template": """🎯 נושא: ישר מאונך
+כלל: m₁ × m₂ = -1. מצא שיפוע המאונך, הצב נקודה, כתוב משוואה.""",
+        "tokens": 50,
+        "requires": []
+    },
+
+    "DISTANCE_FORMULA": {
+        "template": """🎯 נושא: מרחק בין שתי נקודות
+נוסחה: d = √[(x₂-x₁)² + (y₂-y₁)²]. הצב מספרים. פשט.""",
+        "tokens": 50,
+        "requires": []
+    },
+
+    # ========== CALCULUS ==========
+
+    "DERIVATIVE_POWER": {
+        "template": """🎯 נושא: נגזרת — כלל החזקה
+כלל: (xⁿ)' = n·xⁿ⁻¹. גזור כל איבר בנפרד. פשט.""",
+        "tokens": 50,
+        "requires": []
+    },
+
+    "DERIVATIVE_QUOTIENT": {
+        "template": """🎯 נושא: נגזרת — כלל המנה
+כלל: (u/v)' = (u'v - uv') / v². זהה u ו-v. גזור כל אחד. הצב.""",
+        "tokens": 60,
+        "requires": []
+    },
+
+    "DERIVATIVE_PRODUCT": {
+        "template": """🎯 נושא: נגזרת — כלל המכפלה
+כלל: (u·v)' = u'v + uv'. זהה u ו-v. גזור כל אחד. הצב.""",
+        "tokens": 60,
+        "requires": []
+    },
+
+    "DERIVATIVE_CHAIN": {
+        "template": """🎯 נושא: נגזרת — כלל השרשרת
+כלל: [f(g(x))]' = f'(g(x)) · g'(x). זהה פונקציה חיצונית ופנימית. גזור.""",
+        "tokens": 70,
+        "requires": []
+    },
+
+    "INVESTIGATION_EXTREMA": {
+        "template": """🎯 נושא: חישוב נקודות קיצון
+שלב 1: f'(x) = 0 — מצא נקודות אפשריות.
+שלב 2: בדוק ב-f''(x) — f''>0 → מינימום, f''<0 → מקסימום.
+שלב 3: הצב בחזרה ב-f(x) למציאת ערך y.""",
+        "tokens": 90,
+        "requires": []
+    },
+
+    "INVESTIGATION_MONOTONICITY": {
+        "template": """🎯 נושא: עליה וירידה של פונקציה
+מצא f'(x). פתור f'(x) = 0. בדוק סימן f'(x) בכל קטע.
+f'>0 → עולה, f'<0 → יורדת.""",
+        "tokens": 80,
+        "requires": []
+    },
+
+    # ========== ALGEBRA ==========
+
+    "LINEAR_EQUATION": {
+        "template": """🎯 נושא: משוואה לינארית
+פתור שלב-אחר-שלב: בודד x בצד אחד.""",
+        "tokens": 30,
+        "requires": []
+    },
+
+    "QUADRATIC_EQUATION": {
+        "template": """🎯 נושא: משוואה ריבועית
+השתמש בנוסחת פתרון: x = [-b ± √(b²-4ac)] / 2a
+חשב דיסקרימיננטה. מצא שתי תשובות (או שורש כפול).""",
+        "tokens": 60,
+        "requires": []
+    },
+
+    "SYSTEM_EQUATIONS": {
+        "template": """🎯 נושא: מערכת משוואות
+פתור בשיטת הצבה או החסרה. הצב x חזרה למשוואה לווידוא.""",
+        "tokens": 60,
+        "requires": []
+    },
+}
+
+
+# ==================== PROMPT BUILDER ====================
+
+def get_micro_prompt(topic_id: str, data: dict, grade: str = "10") -> str:
+    """
+    Returns topic-focused prefix only.
+    Safety filter: Middle school (7-9) cannot use CALCULUS topics.
+    """
+    if topic_id not in MICRO_PROMPTS:
+        raise KeyError(f"Topic '{topic_id}' not found in MICRO_PROMPTS")
+
+    # Safety Filter for V4.2.11
+    is_middle_school = False
+    try:
+        grade_val = int(re.search(r'\d+', str(grade)).group())
+        is_middle_school = 7 <= grade_val <= 9
+    except:
+        pass
+
+    if is_middle_school and ("DERIVATIVE" in topic_id or "INVESTIGATION" in topic_id):
+        print(f"🛡️ [Safety Filter] Micro-Prompt Filter: Topic {topic_id} blocked for Grade {grade}. Falling back to GENERAL.")
+        return get_general_prompt(data)
+
+    config = MICRO_PROMPTS[topic_id]
+    template = config["template"]
+
+    # No required fields anymore — all templates are self-contained
+    focus_block = template.strip()
+
+    # Prepend focus to the general prompt (which has the anchor + schema)
+    return f"{focus_block}\n\n{get_general_prompt(data)}"
+
+
+def get_prompt_token_count(topic_id: str) -> int:
+    """Get estimated token count for topic's micro-prompt"""
+    return MICRO_PROMPTS.get(topic_id, {}).get("tokens", 60)
+
+
+def get_general_prompt(data_anchor: dict) -> str:
+    """
+    Clean context provider. 
+    Provides the data anchor without conflicting schemas.
+    """
+    anchor_json = json.dumps(data_anchor, ensure_ascii=False, indent=2)
+    return f"""📊 [DATA ANCHOR] Problem context (Absolute Truth):
+{anchor_json}
+
+Instruction: Use the specific data above to solve the problem.
+Do not provide any explanations outside the required JSON structure."""
+
+
+
+# ==================== USAGE EXAMPLE ====================
+
+if __name__ == "__main__":
+    test_data = {"equations": ["x^2 - 4 = 0"], "function_equations": ["f(x) = ln(x)/(x^2-4)"]}
+    for topic in ["CIRCLE_EQUATION", "DERIVATIVE_QUOTIENT", "LINEAR_EQUATION"]:
+        prompt = get_micro_prompt(topic, test_data)
+        print(f"=== {topic} ===\n{prompt[:200]}\n")

ocr_strip_engine.py

@@ -0,0 +1,290 @@
+# ocr_strip_engine.py - V303.2 (Adaptive Pipeline & Two-Pass Sniper)
+import os
+import io
+import json
+import re
+import logging
+import asyncio
+from pathlib import Path
+import numpy as np
+from PIL import Image
+import cv2
+from utils.safe_json import safe_extract_json  # V1.0: Canonical JSON extractor
+
+logger = logging.getLogger(__name__)
+
+DEBUG_DIR = Path("temp/debug_ocr")
+DEBUG_DIR.mkdir(parents=True, exist_ok=True)
+
+# --- Constants for block detection ---
+MIN_BLOCK_W      = 50
+MIN_BLOCK_H      = 10
+LARGE_BLOCK_H    = 100
+ROW_MERGE_GAP    = 2
+
+def _adaptive_preprocess(image_bytes: bytes) -> np.ndarray:
+    """ 
+    V303.2: Adaptive Preprocessing Pipeline
+    Decides how aggressively to process based on image size.
+    """
+    np_img_raw = np.frombuffer(image_bytes, np.uint8)
+    img_bgr = cv2.imdecode(np_img_raw, cv2.IMREAD_COLOR)
+    file_size_kb = len(image_bytes) / 1024
+    
+    logger.info(f"📸 [OCR-ADAPTIVE] Input image size: {file_size_kb:.1f} KB")
+
+    if file_size_kb < 500:
+        # --- LOW-RES MODE (PC Screenshots / Snips) ---
+        logger.info("🔧 [OCR-ADAPTIVE] Low-Res mode triggered: Upscaling and applying heavy morphology.")
+        # 1. Upscale x2 to save thin pixels
+        img_bgr = cv2.resize(img_bgr, None, fx=2.0, fy=2.0, interpolation=cv2.INTER_CUBIC)
+        gray = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2GRAY)
+        # 2. Strong CLAHE
+        clahe = cv2.createCLAHE(clipLimit=2.5, tileGridSize=(8,8))
+        cl1 = clahe.apply(gray)
+        # 3. Morph Close (thicken lines)
+        kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (2, 2))
+        processed = cv2.morphologyEx(cl1, cv2.MORPH_CLOSE, kernel)
+    else:
+        # --- HIGH-RES MODE (Phone Camera in Production) ---
+        logger.info("📱 [OCR-ADAPTIVE] High-Res mode triggered: Mild enhancement only.")
+        gray = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2GRAY)
+        
+        # V1.1: Pre-normalization (Contrast/Brightness Balance)
+        alpha = 1.2 # Contrast
+        beta = 10   # Brightness
+        gray = cv2.convertScaleAbs(gray, alpha=alpha, beta=beta)
+        
+        # Mild CLAHE just to balance lighting, NO morphological distortion
+        clahe = cv2.createCLAHE(clipLimit=1.5, tileGridSize=(8,8))
+        processed = clahe.apply(gray)
+
+    return cv2.cvtColor(processed, cv2.COLOR_GRAY2BGR)
+
+
+def _find_raw_blocks(np_bgr: np.ndarray) -> list[tuple]:
+    gray  = cv2.cvtColor(np_bgr, cv2.COLOR_BGR2GRAY)
+    blur  = cv2.GaussianBlur(gray, (7, 7), 0)
+    thresh = cv2.adaptiveThreshold(blur, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY_INV, 11, 2)
+    # Kernel optimized for both modes
+    kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (60, 3))
+    dilate = cv2.dilate(thresh, kernel, iterations=1)
+    contours, _ = cv2.findContours(dilate, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    blocks = []
+    for c in contours:
+        x, y, w, h = cv2.boundingRect(c)
+        if w >= MIN_BLOCK_W and h >= MIN_BLOCK_H:
+            blocks.append((x, y, w, h))
+    blocks.sort(key=lambda b: b[1])
+    return blocks
+
+def _filter_nested(blocks: list[tuple]) -> list[tuple]:
+    filtered = []
+    for i, (x1, y1, w1, h1) in enumerate(blocks):
+        r1, b1 = x1 + w1, y1 + h1
+        nested = False
+        for j, (x2, y2, w2, h2) in enumerate(blocks):
+            if i == j: continue
+            r2, b2 = x2 + w2, y2 + h2
+            if x1 >= x2 and y1 >= y2 and r1 <= r2 and b1 <= b2:
+                nested = True
+                break
+        if not nested: filtered.append((x1, y1, w1, h1))
+    return filtered
+
+def _merge_same_row(blocks: list[tuple]) -> list[tuple]:
+    if not blocks: return []
+    merged = []
+    cur_x, cur_y, cur_w, cur_h = blocks[0]
+    for (x, y, w, h) in blocks[1:]:
+        cur_b = cur_y + cur_h
+        if cur_h >= LARGE_BLOCK_H or h >= LARGE_BLOCK_H:
+            merged.append((cur_x, cur_y, cur_w, cur_h))
+            cur_x, cur_y, cur_w, cur_h = x, y, w, h
+            continue
+        if y <= cur_b + ROW_MERGE_GAP:
+            union_x, union_y = min(cur_x, x), min(cur_y, y)
+            union_r, union_b = max(cur_x + cur_w, x + w), max(cur_y + cur_h, y + h)
+            cur_x, cur_y, cur_w, cur_h = union_x, union_y, union_r - union_x, union_b - union_y
+        else:
+            merged.append((cur_x, cur_y, cur_w, cur_h))
+            cur_x, cur_y, cur_w, cur_h = x, y, w, h
+    merged.append((cur_x, cur_y, cur_w, cur_h))
+    return merged
+
+def _extract_blocks(np_bgr: np.ndarray) -> list[tuple]:
+    raw = _find_raw_blocks(np_bgr)
+    dedup = _filter_nested(raw)
+    return _merge_same_row(dedup)
+
+def get_best_sniper_roi(img):
+    """
+    V1.1: Math Structural Heatmap Prior.
+    תעדוף אזורים עם צפיפות סמלים מתמטיים גבוהה.
+    """
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    _, thresh = cv2.threshold(gray, 150, 255, cv2.THRESH_BINARY_INV)
+    contours, _ = cv2.findContours(thresh, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    
+    ROI_HOMOGRAPHY_THRESHOLD = 50000  # Threshold for local correction (w*h)
+    candidates = []
+    
+    for cnt in contours:
+        x, y, w, h = cv2.boundingRect(cnt)
+        if w < 20 or h < 10: continue
+        
+        # V1.1: Symbol Density Check (Heatmap Prior)
+        roi_thresh = thresh[y:y+h, x:x+w]
+        pixel_count = np.sum(roi_thresh == 255)
+        density = pixel_count / (w * h)
+        
+        # Feature Clustering (Heatmap Weighting)
+        # Higher score for small but high-density clusters (usually math symbols)
+        heatmap_prior = density * (1.5 if density > 0.15 else 1.0)
+        
+        # Position Weighting (Top-heavy bias)
+        position_weight = (1.0 / (1.0 + 0.005 * y))
+        
+        confidence_score = heatmap_prior * position_weight
+        
+        candidates.append({
+            'confidence': confidence_score,
+            'box': (x, y, w, h),
+            'needs_local_homography': (w * h) > ROI_HOMOGRAPHY_THRESHOLD
+        })
+
+    if not candidates:
+        logger.warning("⚠️ No valid candidates found. Fallback.")
+        return img[:350, :], 0.0
+    
+    best = max(candidates, key=lambda c: c['confidence'])
+    x, y, w, h = best['box']
+
+    # V8.6.4: ROI Hardening — Safe Margins (Padding 50px)
+    # Prevent cutting off minus signs from exponents (e.g., e^-x becoming e^x)
+    SAFE_PADDING = 50
+    y_start = max(0, y - SAFE_PADDING)
+    y_end   = min(img.shape[0], y + h + SAFE_PADDING)
+    
+    logger.info(
+        f"📐 [OCR-BBOX] Sniper ROI (V8.6.4) — x={x}, y={y}, w={w}, h={h} | "
+        f"img=({img.shape[1]}x{img.shape[0]}) | "
+        f"crop=[{y_start}:{y_end}, :] | "
+        f"confidence={best['confidence']:.3f}"
+    )
+
+    # Conditional Local Homography Warning (Bit-log only for now)
+    if best['needs_local_homography']:
+        logger.info(f"📐 [V1.1] ROI ({w}x{h}) exceeds threshold. Local adjustment recommended.")
+    
+    return img[y_start:y_end, :], best['confidence']
+
+def apply_conditional_homography(roi_img: np.ndarray) -> np.ndarray:
+    """
+    V1.1: Local Homography Warning.
+    Only applies alignment if the ROI is large enough to warrant it.
+    Small ROIs stay original to prevent distortion.
+    """
+    h, w = roi_img.shape[:2]
+    area = h * w
+    
+    if area < 5000: # Small ROI - keep original (Prevent distortion)
+        logger.info(f"📐 [V1.1] ROI too small ({area}) - skipping local homography.")
+        return roi_img
+        
+    # Placeholder for actual homography warp
+    # In production, this would involve findHomography + warpPerspective
+    logger.info(f"📐 [V1.1] ROI large enough ({area}) - ready for local perspective correction.")
+    return roi_img
+
+async def transcribe(image_bytes: bytes, vision_model, debug_mode: bool = False) -> tuple[list[dict], float]:
+    logger.info("🪡 [OCR-STRIP] V303.6 Production Lock Pipeline Starting...")
+    
+    # 1. Adaptive Preprocessing
+    np_enhanced_bgr = _adaptive_preprocess(image_bytes)
+    img_h, img_w = np_enhanced_bgr.shape[:2]
+    
+    # 2. Get Sniper ROI (V1.1)
+    sniper_bgr, roi_confidence = get_best_sniper_roi(np_enhanced_bgr)
+    
+    # 2b. Apply Local Homography if needed (V1.1)
+    # Note: Full homography implementation requires feature matching, 
+    # for now we implement the threshold logic.
+    sniper_bgr = apply_conditional_homography(sniper_bgr)
+    
+    sniper_image = Image.fromarray(cv2.cvtColor(sniper_bgr, cv2.COLOR_BGR2RGB))
+    
+    # 3. Reader Pass (Rest of the image)
+    # Note: For V303.6 unified/single pass, we still use the full image for the reader or keep it split if preferred.
+    # The user instruction implies a "Single Pass" logic for Strategy, but OCR can stay multi-pass as long as it's targeted.
+    # We'll stick to a high-quality reader image of the original.
+    pil_enhanced = Image.fromarray(cv2.cvtColor(np_enhanced_bgr, cv2.COLOR_BGR2RGB))
+    reader_image = pil_enhanced # Full image for context
+    
+    if debug_mode:
+        sniper_image.save(DEBUG_DIR / "ocr_pass1_sniper.jpg")
+        reader_image.save(DEBUG_DIR / "ocr_pass2_reader.jpg")
+
+    # 4. The Prompts
+    sniper_prompt = (
+        "Extract ONLY the main mathematical function defined in this image. "
+        "It is usually preceded by words like 'נתונה הפונקציה'. "
+        "CRITICAL: If any exponent or fraction bar appears small or ambiguous, zoom mentally and transcribe it explicitly using ^ notation. "
+        "RETURN ONLY A JSON ARRAY: [{\"type\": \"math\", \"content\": \"...\"}]"
+    )
+    
+    reader_prompt = (
+        "Extract all Hebrew text and secondary mathematical content from this image. "
+        "RETURN ONLY A JSON ARRAY: [{\"type\": \"text\"|\"math\", \"content\": \"...\"}]"
+    )
+    
+    # 5. Concurrent Processing
+    try:
+        from google.generativeai.types import GenerationConfig
+        gen_config = GenerationConfig(temperature=0.0, top_p=0.1, top_k=1)
+        pass1_task = vision_model.generate_content_async([sniper_prompt, sniper_image], generation_config=gen_config)
+        pass2_task = vision_model.generate_content_async([reader_prompt, reader_image], generation_config=gen_config)
+        
+        pass1_response, pass2_response = await asyncio.gather(pass1_task, pass2_task)
+        
+        blocks_pass1 = _parse_structured_json(pass1_response.text)
+        blocks_pass2 = _parse_structured_json(pass2_response.text)
+        
+        # Merge, prioritizing pass 1 for the function definition
+        final_blocks = blocks_pass1 + [b for b in blocks_pass2 if b not in blocks_pass1]
+        
+        logger.info(f"✅ V303.6 Complete. Sniper: {len(blocks_pass1)}, Reader: {len(blocks_pass2)} (Confidence: {roi_confidence:.2f})")
+        return final_blocks, roi_confidence
+        
+    except Exception as e:
+        logger.exception("CRITICAL FLOW ERROR")
+        logger.error(f"❌ OCR V303.6 FAILED: {e}")
+        return [{"type": "text", "content": "שגיאת תקשורת בפענוח."}], 0.0
+
+def _parse_structured_json(raw_text: str) -> list[dict]:
+    """V1.0: Uses canonical safe_extract_json (logs RAW, fail-closed)."""
+    result = safe_extract_json(raw_text, caller="OCR", allow_array=True)
+    if isinstance(result, list):
+        # Flatten nested lists (LLM sometimes wraps array in array)
+        flat = []
+        for item in result:
+            if isinstance(item, list):
+                flat.extend(item)
+            elif isinstance(item, dict):
+                flat.append(item)
+        return [p for p in flat if isinstance(p, dict)]
+    if isinstance(result, dict) and not result.get("logic_error"):
+        return [result]
+    logger.error(f"[OCR] _parse_structured_json: parse failed for: {raw_text[:200]!r}")
+    return []
+
+
+def paginate_image(image_bytes, debug_mode=False):
+    return [Image.open(io.BytesIO(image_bytes)).convert("RGB")] 
+    
+def flatten_to_text(structured: list[dict]) -> str:
+    parts = []
+    for item in structured:
+        if item.get("type") == "math": parts.append(f"${item.get('content', '')}$")
+        else: parts.append(item.get("content", ""))
+    return " ".join(parts)

pedagogical_builder.py

@@ -0,0 +1,850 @@
+# pedagogical_builder.py - V231.18
+# Server-side pedagogical templates for BuddyMath
+# Adds detailed explanations WITHOUT using LLM tokens!
+
+"""
+Pedagogical Builder for BuddyMath
+Follows Iron Law #4: CHILD-FRIENDLY ALWAYS
+
+LLM returns ONLY mathematical core (100-200 tokens).
+Server adds full pedagogical wrapper (0 tokens!).
+"""
+
+import re
+from domain.processing_strategy import ProcessingStrategy
+
+class LLMSchemaError(Exception):
+    """Custom error for LLM output validation failures."""
+    pass
+
+# validate_narrative_density (Unified at line 362)
+
+
+
+# ==================== PEDAGOGICAL TEMPLATES ====================
+
+PEDAGOGICAL_TEMPLATES = {
+    # ========== GEOMETRY ==========
+    
+    "CIRCLE_EQUATION": {
+        "intro": {
+            "title": "מקום גיאומטרי או משוואת מעגל",
+            "content": "בואו נפתור צעד אחר צעד ונשתמש במשוואת המעגל והמרחק לפי הצורך.",
+            "tip": "חשוב להבין את המשמעות הגיאומטרית של הנתונים"
+        },
+        "steps": [
+            {
+                "title": "מה נתון לנו?",
+                "uses_llm": "approach",
+                "tip": "תמיד מסדרים את הנתונים קודם"
+            },
+            {
+                "title": "איך מחשבים מרחק?",
+                "content": "נזכיר את נוסחת המרחק: המרחק מנקודה $(x,y)$ לנקודה $(a,b)$ הוא $d = \\sqrt{{(x-a)^2 + (y-b)^2}}$",
+                "block_math": "d = \\sqrt{(x-a)^2 + (y-b)^2}",
+                "tip": "זו נוסחת פיתגורס במסווה!"
+            },
+            {
+                "title": "חישוב הפתרון",
+                "uses_llm": "steps"
+            },
+            {
+                "title": "התשובה הסופית",
+                "content": "קיבלנו את התשובה הסופית!",
+                "uses_llm": "solution"
+            }
+        ],
+        "closing": "כל הכבוד! הצלחנו לפתור את השאלה המורכבת הזו! 🎉"
+    },
+    
+    "DERIVATIVE_QUOTIENT": {
+        "intro": {
+            "title": "נגזרת של מנה",
+            "content": "כשיש לנו פונקציה שהיא מנה (חילוק) של שתי פונקציות, נשתמש בכלל המנה.",
+            "tip": "כלל המנה: $(\\frac{u}{v})' = \\frac{u'v - uv'}{v^2}$"
+        },
+        "steps": [
+            {
+                "title": "זיהוי המונה והמכנה",
+                "template": "המונה: $u = {numerator}$\nהמכנה: $v = {denominator}$"
+            },
+            {
+                "title": "נגזרת המונה",
+                "content": "נמצא את $u'$ (נגזרת המונה):",
+                "uses_llm": "u_prime"
+            },
+            {
+                "title": "נגזרת המכנה",
+                "content": "נמצא את $v'$ (נגזרת המכנה):",
+                "uses_llm": "v_prime"
+            },
+            {
+                "title": "נציב בכלל המנה",
+                "content": "עכשיו נציב בנוסחה: $(\\frac{u}{v})' = \\frac{u'v - uv'}{v^2}$",
+                "uses_llm": "derivative",
+                "tip": "שים לב לסדר: u'v **פחות** uv'"
+            }
+        ],
+        "closing": "מעולה! שלטת בכלל המנה! 💪"
+    },
+    
+    "LINEAR_EQUATION": {
+        "intro": {
+            "title": "פתרון משוואה לינארית",
+            "content": "משוואה לינארית היא משוואה שבה המשתנה מופיע בחזקה 1 בלבד. המטרה: לבודד את x.",
+            "tip": "כלל הזהב: מה שעושים בצד אחד, עושים גם בצד השני!"
+        },
+        "steps": [
+            {
+                "title": "המשוואה שלנו",
+                "template": "נתון: ${equation}$"
+            },
+            {
+                "title": "פתרון שלב אחר שלב",
+                "uses_llm": "steps",
+                "tip": "בכל שלב, נקרב את x לבידוד"
+            },
+            {
+                "title": "התשובה",
+                "template": "הפתרון: $x = {solution}$"
+            }
+        ],
+        "closing": "יפה! פתרת את המשוואה! ✅"
+    },
+
+    # ========== GENERAL / ALGEBRA ==========
+    "GENERAL": {
+        "intro": {
+            "title": "ניתוח השאלה",
+            "content": "בואו נראה מה נתון לנו ומה צריך למצוא. נפרק את הבעיה לשלבים פשוטים.",
+            "tip": "קריאה נכונה של השאלה היא 50% מהפתרון!"
+        },
+        "steps": [
+            {
+                "title": "מה נתון?",
+                "content": "נסדר את הנתונים והמשוואות בצורה ברורה.",
+                "uses_llm": "approach" # Use approach/strategy as step 1
+            },
+            {
+                "title": "דרך הפתרון",
+                "uses_llm": "steps",
+                "tip": "נפתור שלב אחר שלב בצורה מסודרת"
+            },
+            {
+                "title": "תשובה סופית",
+                "template": "הגענו לתוצאה: {solution}",
+                "uses_llm": "solution"
+            }
+        ],
+        "closing": "מצוין! סיימנו את הסעיף הזה בהצלחה."
+    },
+    
+    # Alias for Rational Function (uses General structure but refined)
+    "RATIONAL_FUNCTION": {
+        "intro": {
+            "title": "חקירת פונקציה רציונלית",
+            "content": "פונקציה רציונלית היא מנה של פולינומים. נבדוק תחום הגדרה, אסימפטוטות ונקודות מיוחדות.",
+            "tip": "חשוב לבדוק מתי המכנה מתאפס!"
+        },
+        "steps": [
+            {
+                "title": "ניתוח הפונקציה",
+                "content": "נסתכל על המונה והמכנה ונראה אם אפשר לפשט.",
+                "uses_llm": "approach"
+            },
+            {
+                "title": "הפתרון המלא",
+                "uses_llm": "steps",
+                "tip": "עבודה מסודרת מונעת טעויות חישוב"
+            },
+            {
+                "title": "סיכום",
+                "uses_llm": "solution"
+            }
+        ],
+        "closing": "כל הכבוד! חקירה יסודית היא המפתח."
+    },
+
+    # ========== TRIGONOMETRY ==========
+    "TRIGONOMETRY": {
+        "intro": {
+            "title": "חשבון טריגונומטרי",
+            "content": "נשתמש בזהויות טריגונומטריות ובתכונות המשולש כדי לפתור.",
+            "tip": "זכור: sin²x + cos²x = 1"
+        },
+        "steps": [
+            {
+                "title": "זיהוי המצב",
+                "content": "נבדוק אילו זווית וצלעות נתונות לנו.",
+                "uses_llm": "approach"
+            },
+            {
+                "title": "ביצוע החישוב",
+                "uses_llm": "steps",
+                "tip": "שימו לב יחידות מעלות/רדיאנים!"
+            },
+            {
+                "title": "התשובה",
+                "template": "התוצאה: {solution}",
+                "uses_llm": "solution"
+            }
+        ],
+        "closing": "מצוין! הטריגונומטריה בידינו! 📐"
+    },
+    # Alias for basic trig
+    "TRIG_BASIC": {
+         "intro": { "title": "טריגונומטריה בסיסית", "content": "חישוב זוויות וצלעות במשולש ישר זווית." },
+         "steps": [{"title": "פתרון", "uses_llm": "steps"}, {"title": "תשובה", "uses_llm": "solution"}],
+         "closing": "יופי!"
+    }
+}
+
+def build_pedagogical_response(
+    topic_id: str,
+    llm_output: dict,
+    data_anchor: dict,
+    custom_title: str = None,  # V260.3: Allow override
+    proof_graph = None,        # V1.1: Immutable ProofGraph
+    processing_strategy: ProcessingStrategy = None # V5.8.0: Intent Contract
+) -> dict:
+    """
+    V4.2 (Behavioral Firewall): Projection-Only Builder.
+    The UI serves ONLY as a projection of the mathematical ProofGraph.
+    LLM math generation is strictly forbidden.
+    """
+    try:
+        print(f"🧱 [V4.2] Projection-Only Mode: topic={topic_id}, ProofGraph={proof_graph is not None}")
+        print(f"DEBUG [PRE-SCRUB]: LLM generated raw narrative: {llm_output}")
+
+        if not proof_graph or not proof_graph.steps:
+            # V5.8.0: Enforce Intent Matrix! If strategy is STRICT_SYMBOLIC, failure to provide graph is a fatal error.
+            if processing_strategy == ProcessingStrategy.STRICT_SYMBOLIC:
+                print(f"🛑 [V5.8.0] STRICT_SYMBOLIC Violation: No ProofGraph provided. Blocking response.")
+                raise LLMSchemaError("Truth Authority Violation: STRICT_SYMBOLIC strategy requires a verified ProofGraph.")
+                
+            if processing_strategy == ProcessingStrategy.HEURISTIC_DEDUCTION:
+                print(f"✅ [V7.3] HEURISTIC_DEDUCTION detected. Bypassing Truth Authority.")
+                return _build_generic_response(llm_output, custom_title=custom_title)
+
+            if isinstance(llm_output, list) and len(llm_output) > 0:
+                print(f"✅ [V7.3] Hybrid Navigation detected (List Segment). Bypassing ProofGraph requirement.")
+                return _build_generic_response(llm_output, custom_title=custom_title)
+
+            if isinstance(llm_output, dict) and ("solution_markdown" in llm_output or "steps" in llm_output or "chain_of_thought" in llm_output):
+                return _build_generic_response(llm_output, custom_title=custom_title)
+            
+            # V8.5 RESILIENCE: One more attempt to find steps if we're failing
+            if isinstance(llm_output, dict) and "sections" in llm_output:
+                 return _build_generic_response(llm_output, custom_title=custom_title)
+
+            # If no clues at all, THEN we raise
+            logger.warning(f"⚠️ [V8.5] Truth Authority Violation: Falling back to generic due to invalid structure: {llm_output}")
+            return _build_generic_response(llm_output, custom_title=custom_title)
+
+        # 1. Map ProofGraph to Immutable Truth Nodes
+        sympy_nodes = []
+        for step in proof_graph.steps:
+            sympy_nodes.append({
+                "step_id": step.step_id,
+                "block_math": step.math_content,
+                "title": step.logic_description or f"שלב {step.step_id}"
+            })
+
+        # 2. Extract explanations from LLM (The "Skin") - V4.2.7 supports list or dict
+        if isinstance(llm_output, list):
+            llm_explanations = llm_output
+        else:
+            # V5.8.2: Support parsing nested 'sections' from the LLM output
+            llm_explanations = llm_output.get("steps_explanations", llm_output.get("steps", []))
+            if not llm_explanations and "sections" in llm_output:
+                for section in llm_output["sections"]:
+                    if "steps" in section:
+                        llm_explanations.extend(section["steps"])
+
+        if not llm_explanations:
+             # Internal Fallback: If LLM failed, use generic text to preserve UI
+             llm_explanations = [{"step_id": s["step_id"], "explanation_text": "נבצע את החישוב המתמטי"} for s in sympy_nodes]
+        else:
+            # V276.1: Normalize explanations to handle structured content/type keys
+            for node in llm_explanations:
+                if "explanation_text" not in node or not node["explanation_text"]:
+                    node["explanation_text"] = node.get("content_mixed", node.get("content", node.get("explanation", "")))
+                
+                # Unpack dict if still found
+                if isinstance(node["explanation_text"], dict):
+                    node["explanation_text"] = node["explanation_text"].get("content", node["explanation_text"].get("text", str(node["explanation_text"])))
+             
+        # V5.8.2: Layer 2 Runtime Validator (The Kill Switch)
+        for node in llm_explanations:
+            text = node.get("explanation_text", "")
+            if not validate_narrative_density(text):
+                print(f"🛑 [V5.8.2] KILL SWITCH TRIGGERED on text: {text}")
+                raise LLMSchemaError("NARRATIVE_OVERFLOW: Explanation is too dense or contains forbidden math/English characters.")
+        
+        # 3. Deterministic Merge (Iron Law) - V4.2.7: explanation_text
+        merged_steps = merge_and_verify_explanations(sympy_nodes, llm_explanations)
+        
+        # 5. UI Projection (Hard Decoupling V4.2.10)
+        ui_steps = []
+        for i, node in enumerate(merged_steps):
+            # V8.6.2: Ensure LaTeX preserved in content_mixed (removed aggressive $ and \ stripping)
+            explanation = sanitize_math_text(node["explanation_text"])
+            
+            math_content = node["block_math"]
+            
+            ui_steps.append({
+                "step_id": node["step_id"],
+                "step_number": i + 1, 
+                "explanation_text": explanation,
+                "math_artifact": {
+                    "type": "equation",
+                    "latex": math_content,
+                    "table_data": ""
+                },
+                # We keep these for one more version as 'Ghost Keys' for extreme backward compatibility
+                # but they now mirror the structured data perfectly.
+                "content_mixed": explanation,
+                "block_math": math_content
+            })
+
+        # V8.6: Inject 'approach' as Step 0 to ensure Flutter displays it
+        approach = llm_output.get("approach")
+        if approach and isinstance(approach, str):
+            ui_steps.insert(0, {
+                "step_id": 0,
+                "step_number": 0,
+                "title": "איך ניגשים לזה? 🧭",
+                "explanation_text": sanitize_math_text(approach),
+                "content_mixed": sanitize_math_text(approach),
+                "math_artifact": {"type": "equation", "latex": ""},
+                "block_math": ""
+            })
+
+        # V8.6.2: Final check on teacher_summary from LLM
+        summary = llm_output.get("teacher_summary") or llm_output.get("summary")
+
+        response = {
+            "sections": [{
+                "section_title": custom_title or "פתרון מלא ומדויק",
+                "steps": ui_steps,
+                "section_result": merged_steps[-1]["block_math"] if merged_steps else ""
+            }],
+            "final_answer": merged_steps[-1]["block_math"] if merged_steps else "",
+            "teacher_closing": llm_output.get("teacher_closing", "כל הכבוד על פתרון התרגיל! 🎉"),
+            "approach": approach,
+            "teacher_summary": summary 
+        }
+        
+        # V260.5: Propagate Investigation Data (Crucial for Table UI)
+        if "investigation" in llm_output:
+            response["investigation"] = llm_output["investigation"]
+        elif "investigation_table" in llm_output:
+            response["investigation"] = llm_output["investigation_table"]
+            
+        return apply_cognitive_load_limiter(response)
+    except Exception as e:
+        logger.error(f"🚨 [V8.5 RESILIENCE] Builder Crash: {e}. Falling back to generic.")
+        return _build_generic_response(llm_output, custom_title=custom_title)
+
+def apply_cognitive_load_limiter(response: dict) -> dict:
+    """
+    V1.1: Cognitive Load Limiter.
+    Ensures steps are revealed gradually.
+    """
+    if "sections" not in response: return response
+    
+    # Limit to first 2 steps if complex, mark others as 'hidden'
+    step_count = 0
+    for section in response["sections"]:
+        if "steps" in section:
+            for step in section["steps"]:
+                step_count += 1
+                # V1.1 Rule: If more than 3 steps, flag the rest for gradual disclosure
+                if step_count > 3:
+                     step["disclosure_state"] = "HIDDEN"
+                else:
+                     step["disclosure_state"] = "VISIBLE"
+    
+    return response
+
+def validate_narrative_density(text: str) -> bool:
+    """
+    V5.8.2: Layer 2 Runtime Validator (Kill Switch).
+    Checks if the pedagogical explanation adheres to the Hard Doctrine.
+    
+    V8.5: RESILIENCE - Relaxed to allow math symbols in text-only steps.
+    Returns False ONLY if it is too long (runaway LLM) or contains dangerous code.
+    """
+    if len(text) > 400:
+        return False
+    # V8.5: Increased tolerance for English letters (ABC labels) and math signs.
+    # We only block forbidden programmatic keywords like 'def', 'class', etc.
+    import re
+    if re.search(r'\b(import|def|class|lambda)\b', text):
+        return False
+    return True
+
+def merge_and_verify_explanations(sympy_nodes: list[dict], llm_explanations: list[dict]) -> list[dict]:
+    """
+    V2.5.3: The Swiss Watch Maneuver.
+    V3.1.3: Hardened Merge Phase with robust guards.
+    V5.8.2: Robust Merge (Option 1) to ignore LLM self-referencing narrative drift.
+    Merges Immutable SymPy math (Truth) with LLM explanations (Skin).
+    """
+    final_nodes = [] # V3.1.3: Mandatory initialization
+
+    try:
+        # V5.8.2 Robust Merge
+        for step in sympy_nodes:
+            sid = step["step_id"]
+            
+            # Find all LLM explanations for this step
+            candidates = [
+                s for s in llm_explanations
+                if s.get("step_id") == sid and "explanation_text" in s
+            ]
+            
+            if not candidates:
+                # If LLM completely missed a step, fallback to generic
+                final_nodes.append({
+                    **step,
+                    "explanation_text": "נבצע את החישוב המתמטי."
+                })
+                continue
+            
+            # Take the last candidate to ignore preamble/meta-commentary drift
+            best_candidate = candidates[-1]
+            explanation_text = best_candidate["explanation_text"]
+            
+            # V6 Narrative Drift Telemetry
+            if "allowed_concepts" in step and step["allowed_concepts"]:
+                import re
+                words = [w for w in re.split(r'\s+', explanation_text) if len(w) > 2] # simple word split ignoring short connectives
+                allowed_words = set()
+                for concept in step["allowed_concepts"]:
+                    allowed_words.update(concept.split())
+                
+                unauthorized_words = [w for w in words if w not in allowed_words]
+                drift_percentage = (len(unauthorized_words) / max(len(words), 1)) * 100
+                
+                if drift_percentage > 50.0:
+                    import logging
+                    logger = logging.getLogger(__name__)
+                    logger.warning(f"⚠️ [V6 TELEMETRY] Drift Warning: {drift_percentage:.1f}% concept drift in Step {sid} (unauthorized: {unauthorized_words[:3]}...)")
+
+            # V5.8.2 Kill Switch Validator Call
+            if not validate_narrative_density(explanation_text):
+                msg = f"NARRATIVE_OVERFLOW: Explanation rejected by Kill Switch: {explanation_text[:20]}..."
+                print(f"🚨 [V5.8.2] {msg}")
+                raise LLMSchemaError("NARRATIVE_OVERFLOW")
+                
+            merged_node = {
+                **step, 
+                "explanation_text": explanation_text
+            }
+            final_nodes.append(merged_node)
+
+        return final_nodes
+
+    except LLMSchemaError:
+        raise
+    except Exception as e:
+        import logging
+        logger = logging.getLogger(__name__)
+        logger.error(f"🚨 [V3.1.3] Merge Phase Failed: {e}")
+        # Since orchestrator is downstream, we re-raise or return something that indicates failure.
+        raise LLMSchemaError(f"Merge failure: {str(e)}")
+
+def _normalize_llm_keys(llm_output: dict) -> dict:
+    """V275.3: Map alternative LLM output keys to expected template keys.
+    E.g., CIRCLE_EQUATION returns 'equation' but GENERAL template expects 'solution'."""
+    result = dict(llm_output)
+    # Map equation -> solution if solution is missing
+    if "solution" not in result and "equation" in result:
+        result["solution"] = result["equation"]
+    # Map approach alternatives
+    if "approach" not in result and "strategy" in result:
+        result["approach"] = result["strategy"]
+    return result
+
+
+def _build_template_response(topic_id: str, llm_output: dict, data_anchor: dict) -> dict:
+    """Build response using topic-specific template."""
+    
+    template = PEDAGOGICAL_TEMPLATES[topic_id]
+    
+    # V275.3: Normalize LLM keys so templates always find what they need
+    llm_output = _normalize_llm_keys(llm_output)
+    
+    # Build response
+    section_data = {
+        "section_title": "פתרון מלא",
+        "steps": [],
+        "section_result": llm_output.get("equation") or llm_output.get("solution") or llm_output.get("derivative")  # V262.0: Per-section result
+    }
+    
+    response = {
+        "sections": [section_data],
+        "final_answer": section_data["section_result"],
+        "teacher_closing": template.get("closing", "כל הכבוד! 🎉"),
+        "teacher_summary": llm_output.get("teacher_summary") # V262.2: Propagate explicit summary
+    }
+    
+    # Add intro step
+    if "intro" in template:
+        intro = template["intro"]
+        response["sections"][0]["steps"].append({
+            "step_number": 0,
+            "title": intro["title"],
+            "content_mixed": intro["content"],
+            "teacher_tip": intro.get("tip", "")
+        })
+    
+    # Add main steps
+    for i, step_template in enumerate(template["steps"], start=1):
+        
+        # V275.2 FIX: Handle unpacking of 'steps' list from llm_output gracefully!
+        if step_template.get("uses_llm") == "steps" and isinstance(llm_output.get("steps"), list):
+            for s in llm_output["steps"]:
+                steps_count = len(response["sections"][0]["steps"])
+                # V275.3: Check multiple content key names (different micro-prompts use different schemas)
+                content = s.get("content_mixed", s.get("content", s.get("explanation", "")))
+                new_step = {
+                    "step_number": steps_count + 1,
+                    "title": s.get("title", f"שלב {steps_count + 1}"),
+                    "content_mixed": sanitize_math_text(content),
+                    "block_math": s.get("block_math", s.get("result", "")),
+                    "teacher_tip": s.get("teacher_tip", step_template.get("tip"))
+                }
+                response["sections"][0]["steps"].append(new_step)
+            continue
+            
+        step = {
+            "step_number": len(response["sections"][0]["steps"]) + 1,
+            "title": step_template["title"]
+        }
+        
+        # Fill content
+        if "template" in step_template:
+            # Template with data substitution (merge with llm_output to prevent KeyError)
+            try:
+                content = step_template["template"].format(**{**data_anchor, **llm_output})
+            except KeyError:
+                # V275.3: Strip unresolved {variable} placeholders instead of showing them raw
+                content = re.sub(r'\{\w+\}', '', step_template["template"]).strip()
+            step["content_mixed"] = content
+        
+        if "content" in step_template:
+            step["content_mixed"] = step_template["content"]
+        
+        if "block_math" in step_template:
+            step["block_math"] = step_template["block_math"]
+        
+        if "uses_llm" in step_template:
+            # Use LLM output
+            llm_key = step_template["uses_llm"]
+            if llm_key in llm_output:
+                if llm_key == "solution" or llm_key == "approach":
+                    # Solutions and approaches usually have Hebrew, put them in content to prevent flutter crash
+                    # If there's already template content, append to it
+                    if step.get("content_mixed"):
+                        step["content_mixed"] += "\n" + sanitize_math_text(str(llm_output[llm_key]))
+                    else:
+                        step["content_mixed"] = sanitize_math_text(str(llm_output[llm_key]))
+                else:    
+                    step["block_math"] = sanitize_math_text(str(llm_output[llm_key]))
+        
+        if "tip" in step_template:
+            step["teacher_tip"] = step_template["tip"]
+        
+        response["sections"][0]["steps"].append(step)
+    
+    return response
+
+
+
+import gibberish_detector  # V231.25: Fix gibberish!
+
+def sanitize_math_text(text: str) -> str:
+    """
+    V231.23: Remove English math artifacts and enforce Hebrew/Latex conventions.
+    Forces 'Angle' -> '\\angle', 'Triangle' -> '\\triangle', 'Area' -> 'S'.
+    V260.4: Also runs auto_fix_gibberish (reversed Hebrew, broken Latex).
+    """
+    if not text:
+        return text
+
+    # V260.4: First, fix structural gibberish (reversed Hebrew, broken LaTeX)
+    text = gibberish_detector.auto_fix_gibberish(text)
+
+    # V275.3: Fix quadruple dollars $$$$ -> $$ EARLY (before any block processing)
+    text = re.sub(r'\${3,}', '$$', text)
+
+    # V275.4: CRITICAL - Detect and unwrap $$Hebrew paragraph$$ blocks
+    # The LLM wraps Hebrew explanations in $$...$$ which renders as garbled "mirror text"
+    # Key insight: Hebrew text mixed with g(x), \ln(x) etc has Hebrew ratio ~30%,
+    # so we need a lower threshold AND a consecutive Hebrew words heuristic.
+    def _unwrap_hebrew_math_block(match):
+        content = match.group(1).strip()
+        # Count Hebrew chars vs total
+        hebrew_chars = len(re.findall(r'[\u0590-\u05FF]', content))
+        total_chars = len(content.replace(' ', ''))
+        if total_chars == 0:
+            return ''  # Empty block, remove it
+        hebrew_ratio = hebrew_chars / total_chars
+        # Heuristic 1: >25% Hebrew with enough chars = text paragraph
+        if hebrew_ratio > 0.25 and hebrew_chars > 8:
+            print(f"🧹 [SANITIZE] Unwrapped Hebrew-in-math block ({hebrew_chars} Hebrew chars, ratio={hebrew_ratio:.1%})")
+            return content  # Return as plain text without $$
+        # Heuristic 2: Has 3+ consecutive Hebrew words (even if ratio is low)
+        if re.search(r'[\u0590-\u05FF]+\s+[\u0590-\u05FF]+\s+[\u0590-\u05FF]+', content):
+            print(f"🧹 [SANITIZE] Unwrapped Hebrew-in-math (consecutive Hebrew words detected)")
+            return content
+        return match.group(0)  # Keep as-is for real math
+    
+    text = re.sub(r'\$\$(.+?)\$\$', _unwrap_hebrew_math_block, text, flags=re.DOTALL)
+
+    # V231.25: Fix corrupted LaTeX escapes (form feed \f, invalid \3)
+    text = text.replace('\x0c', r'\f')
+    text = re.sub(r'\\(\d)', r'\1', text)
+    
+    # V275.2: Fix double backslash newlines inside $$...$$ which crash flutter_math_fork
+    # Split blocks safely instead of using \newline
+    def safe_split_newlines(match):
+        block = match.group(1)
+        if r'\begin{' in block:
+            # Leave environments like \begin{cases} alone, they support \\
+            return match.group(0)
+        # Split by \\ or \newline
+        parts = re.split(r'\\\\|\\newline', block)
+        # V280.3: Ensure we don't strip the outer $$ markers when splitting blocks!
+        joined = '$$\n$$'.join(p.strip() for p in parts if p.strip())
+        return f"$${joined}$$" if joined else ""
+    
+    text = re.sub(r'\$\$(.+?)\$\$', safe_split_newlines, text, flags=re.DOTALL)
+    
+    # 1. English Geometrical terms (Case Insensitive)
+    # \\b matches word boundaries to avoid replacing substrings
+    text = re.sub(r'\\bAngle\\b', r'\\angle', text, flags=re.IGNORECASE)
+    text = re.sub(r'\\bTriangle\\b', r'\\triangle', text, flags=re.IGNORECASE)
+    text = re.sub(r'\\bDeg\\b', r'^{\\circ}', text, flags=re.IGNORECASE)
+    
+    # 2. "Area" -> S (e.g. "Area of triangle" -> "S of triangle")
+    # Be careful not to replace valid words, but "Area" in math context is usually S
+    text = re.sub(r'\\bArea\\b', r'S', text, flags=re.IGNORECASE)
+
+    # V262.1: Auto-wrap Hebrew inside LaTeX blocks (The "Escaping Lines" Fix)
+    text = _auto_wrap_hebrew_in_latex(text)
+
+    return text
+
+def _auto_wrap_hebrew_in_latex(text: str) -> str:
+    """
+    Scans for Hebrew characters inside $$...$$ or $...$ blocks.
+    If found, wraps them in \\text{...} to prevent rendering crashes.
+    """
+    if not text: return text
+    
+    # Regex for Hebrew chars (including nikud/punctuation common in Hebrew)
+    hebrew_pattern = r'([\u0590-\u05FF\s\.\,\:\-]+)' 
+
+    def replacer(match):
+        content = match.group(1) # The content inside the dollars
+        # Check if there is Hebrew in this block
+        if re.search(r'[\u0590-\u05FF]', content):
+            # There is Hebrew! Let's wrap the Hebrew parts in \text{...}
+            # We split by math/hebrew chunks or just wrap the whole Hebrew phrase
+            # Simple approach: Find Hebrew chunks and wrap them
+            new_content = re.sub(hebrew_pattern, r'\\text{\1}', content)
+            # Cleanup: \text{ } (empty) or double wrapping check could be added if needed
+            return f"${new_content}$"
+        return match.group(0)
+
+    # Replace inline math $...$ (using naive non-nested check)
+    # We use a trick to avoid matching $$...$$ first if we aren't careful, 
+    # but specific regex for $$...$$ should come first if we supported it fully as separate.
+    # For now, let's handle $...$ which often covers $$...$$ in simple regex unless distinct.
+    # Actually, $$ is just two $s. Let's try to be safe.
+    
+    # Strategy: Split by '$' and process every odd element (1, 3, 5...) as Math?
+    # This is safer than regex for nested/complex strings.
+    
+    parts = text.split('$')
+    if len(parts) < 3: return text # No math blocks
+    
+    new_parts = []
+    for i, part in enumerate(parts):
+        if i % 2 == 1: # This is a MATH block (inside $...$)
+            if re.search(r'[\u0590-\u05FF]', part):
+                # Found Hebrew inside Math! Wrap it.
+                # Note: We must be careful not to wrap existing \text{...} again if possible,
+                # but simple wrapping usually doesn't hurt: \text{\text{...}} is valid-ish or we can ignore.
+                
+                # Better: only wrap Hebrew that is NOT already in \text{...}? 
+                # That's complex. Let's do the simple "Wrap Hebrew Chars" regex.
+                # We exclude commands commands like \frac, \cdot etc.
+                
+                def wrap_hebrew(m):
+                    s = m.group(1)
+                    if len(s.strip()) == 0: return s # Don't wrap just whitespace
+                    if '\\text' in s: return s # Already wrapped (naive check)
+                    return f"\\text{{{s}}}"
+
+                # Apply wrapping to identified hebrew chunks
+                # Note: we use a simplified version of the regex for local substitution
+                part = re.sub(hebrew_pattern, wrap_hebrew, part)
+            
+            new_parts.append(part)
+        else:
+            # This is a REGULAR block (outside/between $...$)
+            new_parts.append(part)
+
+    return '$'.join(new_parts)
+
+def _build_generic_response(llm_output: dict, custom_title: str = None) -> dict:
+    """
+    V231.20: Rich UI formatter — restores 'Old Look' with green box and mixed text/math.
+    ...
+    """
+    # Extract steps
+    steps = []
+    
+    # helper for clean content
+    def get_content(s):
+        if isinstance(s, dict):
+            # Check multiple content key names (different micro-prompts use different schemas)
+            content = s.get("content_mixed", s.get("content", s.get("explanation", s.get("explanation_text", ""))))
+            
+            # V275.5: If content is still a dict (e.g. from structured JSON fragments), extract text
+            if isinstance(content, dict):
+                content = content.get("text", content.get("content", str(content)))
+            return content
+        return str(s)
+
+    # V4.3 Unified Markdown Path
+    if isinstance(llm_output, dict) and "solution_markdown" in llm_output:
+        steps.append({
+            "step_id": 1,
+            "step_number": 1,
+            "title": "פתרון מלא",
+            "explanation_text": sanitize_math_text(str(llm_output["solution_markdown"])),
+            "content_mixed": sanitize_math_text(str(llm_output["solution_markdown"])),
+            "math_artifact": {"type": "equation", "latex": ""},
+            "is_unified_markdown": True
+        })
+    elif (isinstance(llm_output, list)) or (isinstance(llm_output, dict) and "steps" in llm_output and isinstance(llm_output["steps"], list)):
+        raw_steps = llm_output if isinstance(llm_output, list) else llm_output["steps"]
+        for i, s in enumerate(raw_steps, 1):
+            content = get_content(s)
+            if isinstance(content, str):
+                content = sanitize_math_text(content)
+            
+            math_latex = ""
+            if isinstance(s, dict):
+                math_latex = s.get("math_latex", s.get("block_math", s.get("result", "")))
+
+            steps.append({
+                "step_id": s.get("step_id", i) if isinstance(s, dict) else i,
+                "step_number": i,
+                "title": s.get("title", f"שלב {i}") if isinstance(s, dict) else f"שלב {i}",
+                "explanation_text": content,
+                "content_mixed": content,
+                "math_artifact": {
+                    "type": "equation",
+                    "latex": math_latex
+                },
+                "block_math": math_latex,
+                "teacher_tip": s.get("teacher_tip") if isinstance(s, dict) else None
+            })
+    elif isinstance(llm_output, dict) and "chain_of_thought" in llm_output:
+        # Fallback for old models
+        cot = sanitize_math_text(str(llm_output["chain_of_thought"]))
+        steps.append({
+            "step_id": 1,
+            "step_number": 1,
+            "title": "דרך הפתרון",
+            "explanation_text": cot,
+            "content_mixed": cot,
+            "math_artifact": {"type": "equation", "latex": ""}
+        })
+    else:
+        # Last resort - use get_content helper to handle single dict blocks correctly
+        content = get_content(llm_output)
+        if isinstance(content, str):
+            content = sanitize_math_text(content)
+        
+        steps.append({
+            "step_id": 1,
+            "step_number": 1,
+            "title": "הפתרון",
+            "explanation_text": content,
+            "content_mixed": content,
+            "math_artifact": {"type": "equation", "latex": ""}
+        })
+
+    # Extract final answer
+    # Extract final answer with improved fallback logic (V261.16)
+    final_answer = (
+        llm_output.get("final_answer") or 
+        llm_output.get("equation") or 
+        llm_output.get("solution") or 
+        llm_output.get("derivative") or
+        llm_output.get("integral") or
+        llm_output.get("limit") or
+        llm_output.get("x_intercepts") or
+        llm_output.get("min_max_points")
+    )
+    
+    # If it's a list or dict (e.g. points), convert to string representation
+    if isinstance(final_answer, (list, dict)):
+        final_answer = str(final_answer)
+        
+    if not final_answer:
+        final_answer = "ראה שלבים"
+
+    # V8.6: Inject 'approach' as Step 0
+    approach = llm_output.get("approach")
+    if approach and isinstance(approach, str):
+        steps.insert(0, {
+            "step_id": 0,
+            "step_number": 0,
+            "title": "איך ניגשים לזה? 🧭",
+            "explanation_text": sanitize_math_text(approach),
+            "content_mixed": sanitize_math_text(approach),
+            "math_artifact": {"type": "equation", "latex": ""},
+            "block_math": ""
+        })
+
+    response_obj = {
+        "sections": [{
+            "section_title": custom_title or "הפתרון",
+            "steps": steps,
+            "section_result": str(final_answer) # V262.0: Per-section result
+        }],
+        "final_answer": str(final_answer),
+        "teacher_closing": llm_output.get("teacher_closing", "כל הכבוד! 🎉"),
+        "approach": approach, # V8.6: Explicit approach field
+        "teacher_summary": llm_output.get("teacher_summary") # V262.2: Propagate explicit summary
+    }
+    
+    # V260.5: Propagate Investigation Data (Crucial for Table UI)
+    if "investigation" in llm_output:
+        response_obj["investigation"] = llm_output["investigation"]
+    elif "investigation_table" in llm_output:
+        response_obj["investigation"] = llm_output["investigation_table"]
+        
+    return response_obj
+
+if __name__ == "__main__":
+    import json
+    
+    # Test circle equation
+    llm_out = {
+        "equation": "(x-3)^2 + (y-5)^2 = 25",
+        "center": [3, 5],
+        "radius": 5
+    }
+    data = {"center": "(3,5)", "radius": 5}
+    
+    response = build_pedagogical_response("CIRCLE_EQUATION", llm_out, data)
+    print(json.dumps(response, indent=2, ensure_ascii=False))

problem_understanding.py

@@ -0,0 +1,152 @@
+# problem_understanding.py - V231.14
+# Analyzes problem structure BEFORE solving
+
+"""
+Problem Understanding Module
+Ensures we understand WHAT is being asked before attempting to solve.
+"""
+
+import json
+import re
+from utils.safe_json import safe_extract_json  # V1.0: Canonical extractor
+
+
+def get_problem_understanding_prompt(ocr_text: str, data_anchor: dict) -> str:
+    """
+    Prompt LLM to analyze problem structure.
+    
+    Returns JSON with:
+    - problem_type
+    - sub_questions (all parts א, ב, ג, etc.)
+    - solving_order
+    - dependencies
+    """
+    return f"""
+ANALYZE this math problem structure. DO NOT SOLVE - only understand what is being asked.
+
+Problem Text:
+{ocr_text}
+
+Extracted Data:
+{json.dumps(data_anchor, ensure_ascii=False, indent=2)}
+
+Your task: Identify ALL parts of this problem and create a solving plan.
+
+Return JSON:
+{{
+  "problem_type": "CIRCLE_EQUATION | LINE_EQUATION | GEOMETRIC_LOCUS | DERIVATIVE_QUOTIENT | etc.",
+  "main_question": "Brief description of main question",
+  "sub_questions": [
+    {{
+      "id": "א",
+      "question": "Full text of sub-question א",
+      "requires": ["center", "radius"],
+      "expected_output": "equation | number | point | etc.",
+      "topic": "CIRCLE_EQUATION"
+    }},
+    {{
+      "id": "ב",
+      "question": "Full text of sub-question ב",
+      "requires": ["equation_from_א", "point"],
+      "expected_output": "line_equation",
+      "topic": "LINE_TANGENT"
+    }}
+  ],
+  "solving_order": ["א", "ב", "ג"],
+  "dependencies": {{
+    "ב": ["א"],
+    "ג": ["א"]
+  }}
+}}
+
+CRITICAL RULES:
+1. Include ALL sub-questions (א, ב, ג, ד, etc.)
+2. **EXCEPTION:** If the problem asks for a **Geometric Locus (מקום גיאומטרי)**:
+   - This is a SINGLE QUESTION (even if it looks long).
+   - Set `problem_type` = "GEOMETRIC_LOCUS".
+   - Create ONLY ONE sub-question (id="א") containing the entire text.
+3. Identify dependencies (ב needs א's result)
+4. Determine topic for EACH sub-question
+5. DO NOT solve - only analyze structure
+
+Return ONLY valid JSON.
+"""
+
+
+def parse_understanding(response_text: str) -> dict:
+    """Parse LLM understanding response using canonical safe_extract_json."""
+    result = safe_extract_json(response_text, caller="PROBLEM_UNDERSTANDING")
+    # If parsing failed, return a minimal fallback so the pipeline continues
+    if isinstance(result, dict) and result.get("logic_error"):
+        return {
+            "problem_type": "UNKNOWN",
+            "sub_questions": [],
+            "solving_order": [],
+            "dependencies": {}
+        }
+    return result
+
+
+
+def validate_understanding(understanding: dict) -> bool:
+    """Validate understanding structure."""
+    required_keys = ["problem_type", "sub_questions", "solving_order"]
+    
+    if not all(key in understanding for key in required_keys):
+        return False
+    
+    if not isinstance(understanding["sub_questions"], list):
+        return False
+    
+    if len(understanding["sub_questions"]) == 0:
+        return False
+    
+    # Validate each sub-question
+    for sq in understanding["sub_questions"]:
+        if not all(key in sq for key in ["id", "question", "topic"]):
+            return False
+    
+    return True
+
+def enforce_locus_rule(understanding: dict, ocr_text: str) -> dict:
+    """
+    V260.2: Hard Rule - If 'מקום גיאומטרי' exists, FORCE Locus type.
+    """
+    if any(k in ocr_text for k in ["מקום גיאומטרי", "Locus", "מצא את המקום", "המקום הגיאומטרי"]):
+        print("🛡️ [BIT-LOG] Hard Logic: Detected 'Geometric Locus' - Forcing Single Question structure.")
+        return {
+            "problem_type": "GEOMETRIC_LOCUS",
+            "main_question": understanding.get("main_question", "Find the Locus"),
+            "sub_questions": [{
+                "id": "א",
+                "question": ocr_text, # Give the WHOLE text to the single sub-question
+                "requires": [],
+                "expected_output": "equation",
+                "topic": "GEOMETRIC_LOCUS"
+            }],
+            "solving_order": ["א"],
+            "dependencies": {}
+        }
+    return understanding
+
+
+# ==================== USAGE EXAMPLE ====================
+
+if __name__ == "__main__":
+    # Test understanding prompt
+    ocr = """
+    מעגל עם משוואה x² + y² = 12
+    א. מצא את משוואת המעגל
+    ב. מצא משיק למעגל בנקודה A
+    ג. מצא את שטח המעגל
+    """
+    
+    data = {
+        "function_equations": ["x^2 + y^2 = 12"],
+        "points": ["A"],
+        "specific_values": [],
+        "constraints": []
+    }
+    
+    prompt = get_problem_understanding_prompt(ocr, data)
+    print(prompt)

prompts.py

@@ -0,0 +1,815 @@
+# 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"⚠️ הנחיה קריטית: אל תנחש את הצורה! פתח את המשוואה צעד-אחר-צעד מההגדרה (למשל d1=d2).")
+             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"CRITICAL GEOMETRY RULE: NEVER invent or alter the position of points, lines, or intersections. You MUST strictly adhere to the geometric layout described in the problem text. If your calculation leads to a paradox (e.g., length 0 or negative area), YOUR geometric assumption is wrong. Recalculate based strictly on the given text constraints.")
+
+    if category in ["CALCULUS", "FUNCTION_ANALYSIS", "INVESTIGATION"]:
+        rules.append(r"GRAPH IDENTIFICATION RULE: To match a function to its graph, rely STRICTLY on mathematical anchors you calculated (e.g., axis intersections, positive/negative domains, extrema). Deduce the correct graph logically. DO NOT blindly trust the visual labels (I, II, 1, 2) from the image context, as they might be read incorrectly by the OCR.")
+
+    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$")
+            rules.append(r"מכפלה וקטורית: $\\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"משוואת מישור: $Ax + By + Cz + D = 0$ כאשר $(A,B,C)$ הוא וקטור נורמלי למישור.")
+            rules.append(r"ישר במרחב (הצגה פרמטרית): $\\vec{r} = \\vec{p} + t\\vec{v}$ כלומר $x=p_1+tv_1, y=p_2+tv_2, z=p_3+tv_3$")
+            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"זווית בין שני מישורים: $\\cos\\alpha = \\frac{|\\vec{n_1}\\cdot\\vec{n_2}|}{|\\vec{n_1}||\\vec{n_2}|}$ (נורמלים)")
+            rules.append(r"זווית בין ישר לבין מישור: $\\sin\\alpha = \\frac{|\\vec{v}\\cdot\\vec{n}|}{|\\vec{v}||\\vec{n}|}$")
+            rules.append(r"שני ישרים מקבילים אם $\\vec{v_1} = k\\vec{v_2}$. מישורים מקבילים אם $\\vec{n_1} = k\\vec{n_2}$.")
+            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"⚠️ אסטרטגיה: זהה את המשולש ישר-הזווית החבוי בתוך הגוף המרחבי (בד\"כ בין גובה, מקצוע צדדי, אפותם).")
+        rules.append(r"זווית בין מקצוע צדדי לבסיס: מצא משולש ישר-זווית שמכיל את הגובה ואת ההטל של המקצוע על הבסיס.")
+        rules.append(r"זווית בין פאה צדדית לבסיס: מצא את האפותם של הפאה ואת גובה הפירמידה. $\\tan\\alpha = \\frac{h}{apothem}$")
+        rules.append(r"שטח פנים כולל = שטח בסיס + סכום שטחי הפאות הצדדיות.")
+        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"⚠️ אסטרטגיית בעיית קיצון (מלל): 1) הגדר משתנה. 2) בנה את פונקציית המטרה $f(x)$. 3) אם יש אילוץ — בטא משתנה אחד בעזרת האחר. 4) גזור ושווה ל-0. 5) ודא מקסימום/מינימום ע\"י נגזרת שנייה. 6) הצב חזרה לתשובה.")
+        rules.append(r"שיטת הקצוות: בקטע סגור $[a,b]$, בדוק גם ב-$f(a)$, $f(b)$ וגם בנקודות קריטיות.")
+        rules.append(r"סיווג נקודת קיצון: $f''(x_0) > 0$ ⟹ מינימום, $f''(x_0) < 0$ ⟹ מקסימום.")
+
+    # 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.13: Extract ALL equations, not just functions."""
+    return fr"""
+EXTRACT key mathematical data from this problem. Return ONLY valid JSON.
+
+Problem:
+{problem_text}
+
+Extract:
+1. **function_equations**: ALL equations with '=' sign
+   - 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!
+
+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 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.
+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 "    (לא זוהו כללים ספציפיים — בחר רק כללים רלוונטיים לקטגוריה {category})"
+    
+    # Anchor Block — DATA INTEGRITY RULE
+    anchor_block = ""
+    if data_anchor:
+        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).
+    """
+
+
+    # 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}! 👑 {student_gender == 'F' and 'פתרת' or 'פתרת'} מעולה. אני גאה בך!"
+        }
+    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)"]
+    }
+    """
+
+    return f"""
+    🎓 תפקיד: אתה "המורה למתמטיקה" — מורה פרטית חמה ומעודדת בגישת 'הנסיך והנסיכה'.
+    🌟 הנחיה עליונה: הפוך את הלמידה לחוויה מעצימה, אישית ונעימה עבור {student_name}.
+    👑 מגדר: התלמיד/ה הוא/היא {g['royal']}. השתמש/י בלשון התאימה למגדר זה.
+    
+    🏰 חוק הזרימה והפרסונליזציה (Continuous Persona Rule):
+
+    • הקשר רציף: אתה פותר עכשיו סעיף אחד מתוך שאלה גדולה. אל תתחיל כל סעיף בברכת שלום דרמטית או היכרות מחודשת! זרום ישירות להסבר עם מילת קישור (למשל: "כעת נמשיך ל...", "כדי למצוא את...", "בסעיף זה נתמקד ב...").
+
+    • התאמת גיל ופרופיל: התלמיד מולך הוא {student_name} הלומד בכיתה {grade}. דברו אליו בגובה העיניים, בשפה שמתאימה לגילו. בלי התיילדות יתר, אלא בטון מקצועי, מעצים ובוגר.
+
+    • חיזוקים טבעיים: שלבו חיזוקים חיוביים בצורה עדינה וטבעית בסוף הסעיף, לא בכל משפט (למשל: "יופי של עבודה עד כה", "הבנת את העיקרון המרכזי כאן").
+
+    • ספציפיות קריטית (V261.16): אסור לכתוב "לפי המשפט" או "כפי שלמדנו" בלי לפרט איזה משפט ומה הוא אומר.
+      - לא טוב: "לפי המשפט, הזוויות שוות."
+      - מצוין: "בגלל שזוויות מתחלפות בין ישרים מקבילים הן שוות, אז זווית A שווה לזווית B."
+
+    • אימות OCR והשגחה:
+    • אסור בהחלט לשנות את הפונקציה או הנתונים שהתקבלו מה-OCR! 🚫
+    • אם ה-OCR זיהה $\frac{{x^2}}{{x^2-4}}$ — חובה לפתור בדיוק את הפונקציה הזו!
+    • אם נקודות $A, D$ נמצאות על ציר $y$ — זה אומר $x = 0$! לא $y = 0$!
+
+    🔒 חוקי אימות חישובי (V282.3 — CRITICAL):
+    • **אסור להניח מיקום נקודה בלי חישוב אלגברי.** אם נתונות משוואות ישרים — חשב נקודת חיתוך ע"י פתרון מערכת המשוואות. לעולם אל תניח שנקודה או מרכז מעגל נמצאים על ציר ספציפי (למשל x=0) בלי הוכחה מתמטית אלגברית ברורה בצעדים.
+    • **הצבה חוזרת חובה:** אחרי שמצאת שיעורי נקודה — הצב אותם בחזרה בכל המשוואות הנתונות כדי לוודא שהם מקיימים את כולן.
+    • **בדיקה עצמית לפני תשובה סופית:** לפני שאתה כותב את התשובה הסופית — עבור על כל תוצאת ביניים ובדוק שהיא עקבית עם כל הנתונים.
+
+    {anchor_block}
+    
+    📚 רקע תיאורטי לשאלה (§4.1 — רלוונטי בלבד):
+{rules_str}
+
+    🎯 קטגוריה: {category}
+    📊 רמת הכיתה: {grade} ({features['depth']})
+    
+    {proof_block}
+    {investigation_block}
+    """
+
+
+# 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. **SCAN STRUCTURE FIRST**
+       Before writing anything, identify the STRUCTURE:
+       - Is there a fraction? Look for horizontal lines
+       - Is there nesting? (something inside something else)
+       - Are there exponents? Look for small raised text
+       - Are there subscripts? Look for small lowered text
+    
+    2. **WORK OUTSIDE-IN**
+       For complex expressions:
+       - First identify the OUTERMOST structure
+       - Then identify what's INSIDE each part
+       - Write the LaTeX from outside to inside
+    
+    3. **FRACTION DETECTION**
+       When you see a horizontal line:
+       - Everything ABOVE the line is the numerator
+       - Everything BELOW the line is the denominator
+       - If there's ANOTHER horizontal line inside → nested fraction!
+       - Use \\frac{numerator}{denominator}
+    
+    4. **PARENTHESES CONTENT**
+       When you see parentheses/brackets:
+       - Transcribe EVERYTHING inside, no matter how complex
+       - Don't summarize or skip parts
+       - Use \\left( and \\right) for large parentheses
+    
+    5. **EXPONENTS AND SUBSCRIPTS**
+       - Small text ABOVE the line → exponent: x^{...}
+       - Small text BELOW the line → subscript: x_{...}
+       - If the exponent is complex (like n-1), use braces: x^{n-1}
+    
+    6. **HEBREW TEXT**
+       - Transcribe ALL Hebrew instructions exactly
+       - Fully transcribe any top-level header or main question text before the sub-questions
+       - Include all list items formatting and sub-question letters
+       - Include ALL conditions and constraints
+    
+    🚫 FORBIDDEN:
+    - Do NOT simplify expressions
+    - Do NOT skip "obvious" parts
+    - Do NOT assume you know what the function should be
+    - Do NOT change the structure you see
+    
+    ✅ 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.
+    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():
+    """
+    V8.6.8: The Anchor Stability Fix.
+    Prevents NameErrors and UI rendering crashes.
+    """
+    return 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:** The equations in the JSON Data Anchor are the ABSOLUTE TRUTH. Ignore any conflicting OCR text.
+    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. **UI CONTENT STRATEGY (CRITICAL - MATH SEPARATION & MULTI-STEP LOGIC):**
+       - `content_mixed`: ONLY for your warm Hebrew explanation and short inline variables (e.g. $x=5$). Do NOT put long equations, derivatives, or multi-line steps here!
+       - `block_math`: This is where the ACTUAL CALCULATION goes. It must contain the main equation or algebraic step in PURE LaTeX.
+       - IF there is any mathematical derivation or calculation in a step, it MUST go into `block_math` and NOT into `content_mixed`. NEVER put an equation on a new line inside `content_mixed`.
+       - **MULTI-STEP DERIVATIONS:** If a calculation requires multiple algebraic lines (like a complex derivative or expanding brackets), DO NOT SKIP THEM! Break them down into **MULTIPLE JSON steps**! Explain ONE part in `content_mixed`, show the intermediate math in `block_math`, then create a NEW step for the next part.
+       - NEVER put Hebrew inside `block_math` (no \\text{עברית}), it will crash the app!
+    5. **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).
+    6. **STRICT JSON ONLY:** No preamble, no post-amble, no markdown.
+    7. **PARADOX PROTOCOL (V8.6.6):**
+       - If your mathematical calculation contradicts the question's premise (e.g., calculation shows $e^x$ but objective is to find info for $e^{-x}$), DO NOT APOLOGIZE or hallucinate. 
+       - State factually in `content_mixed`: "אני מזהה סתירה בנתונים, בואו נבדוק שוב את הפונקציה המקורית. על פי החישוב שלי [הסבר קצר...]."
+       - Focus on the TRUTH of your calculation. Never force a derivation to match a (likely misread) OCR error.
+       - **Mathematical Logic (V8.6.6):** If OCR is ambiguous (e.g. $e^x$ vs $e^{-x}$), use the overall context of the question (e.g., domain, asymptotes, or known behavior) to determine the logically correct formula.
+    8. **ANTI-NEWLINE RULE (V8.6.8):**
+       - In the `final_answer` field, NEVER use `\\` or `\newline` for line breaks. 
+       - If there are multiple answers, separate them with commas or Hebrew text (e.g., "x=1, x=2" or "x=1 או x=2").
+    9. **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 IN LATEX OR ANSWERS (CRITICAL FOR UI RENDERER):**
+        - NEVER include Hebrew words inside LaTeX math blocks (like `formulas` or `block_math`). The UI renderer cannot handle RTL properly inside math blocks.
+        - Use English/Greek letters for indices (e.g. $S_{total}$ and NOT $S_{סך_הכל}$).
+        - The `final_answer` field MUST contain ONLY the mathematical answer (e.g. `x=5`). Do NOT write "תשובה: x=5" inside the field!
+    12. **PEDAGOGICAL HIGHLIGHTING (CRITICAL):**
+        - When performing a substitution, showing a change in sign, taking a derivative, or highlighting a key transition in a calculation inside `block_math` or `content_mixed`, use `\\color{red}{...}` or `\\color{blue}{...}` to visually highlight the element that changed. (e.g., `\\color{red}{x^2}`, `\\color{blue}{+4}`).
+        - Only wrap valid Math inside the color tag. Do not color Hebrew text.
+
+
+    ═══════════════════════════════════════════
+    REQUIRED JSON STRUCTURE (EXACT KEYS):
+    ═══════════════════════════════════════════
+    {
+      "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 נקי (ללא סוגרי דולר)"]
+      }
+    }
+    
+    CRITICAL: Output ONLY the JSON block. No text before, no text after. No markdown formatting.
+    """
+
+def get_master_prompt_v430():
+    """V4.3.0: Legacy placeholder, redirecting to V8.6.0 for 'The Golden Merge'"""
+    return get_master_prompt_v860()
+
+
+# ==================== V285.0: CHECK ME PROMPT (HOMEWORK VERIFICATION) ====================
+
+def get_check_me_prompt(grade: str, student_name: str, student_gender: str = "M"):
+    """
+    V285.0: Dedicated prompt for the "Check Me" feature.
+    The LLM acts as a homework checker, NOT a solver.
+    It receives the student's image and analyzes their work step-by-step.
+    """
+    # 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} יקר"
+
+    return f"""
+    🎓 תפקיד: אתה בודקת שיעורי בית — מורה פרטית חמה שבודקת את העבודה של תלמיד.
+    🚫 אתה לא פותר את התרגיל מחדש! אתה מנתח את מה שהתלמיד כתב.
+
+    👤 התלמיד: {student_name}, כיתה {grade}.
+    👑 מגדר: {"נקבה" if student_gender == "F" else "זכר"}. השתמש/י בלשון מתאימה.
+
+    ═══════════════════════════════════════════════════
+    📐 שלוש שלבי הבדיקה (חובה לבצע לפי הסדר):
+    ═══════════════════════════════════════════════════
+
+    שלב א' — בדיקת מתודולוגיה (אסטרטגיה):
+    • זהה את התרגיל מתוך התמונה.
+    • בדוק: האם התלמיד בכלל בחר בשיטת פתרון נכונה?
+    • למשל: האם השתמש בנוסחת השורשים כשצריך פירוק? האם גזר כשצריך אינטגרל?
+    • אם השיטה שגויה מיסודה — עצור כאן. הסבר את הטעות התפיסתית בלבד.
+
+    שלב ב' — אימות אלגברי צעד-אחר-צעד:
+    • סרוק את שורות הפתרון שהתלמיד כתב.
+    • בדוק כל מעבר: העברת אגפים, כינוס איברים, סימנים, חזקות.
+    • ברגע שמזהה שבירה של חוק אלגברי — בודד את השורה המדויקת.
+    • ציין מה היה צריך להיות ולמה.
+
+    שלב ג' — רכיבים ויזואליים:
+    • אם התלמיד צייר גרף, שרטוט גיאומטרי, או טבלת סימנים שגויים — ציין מה שגוי.
+    • אם אין רכיב ויזואלי — דלג על שלב זה.
+
+    ═══════════════════════════════════════════════════
+    🎯 כללי ברזל:
+    ═══════════════════════════════════════════════════
+    1. אל תפתור את התרגיל מחדש! רק בדוק את מה שהתלמיד כתב.
+    2. אם הכל נכון — תן חיזוק חיובי אמיתי ומפורט.
+    3. אם יש טעות — הצבע על השורה המדויקת, הסבר מה שגוי, ומה היה צריך להיות.
+    4. טון: חם, מעודד, מקצועי. כמו מורה פרטית שבודקת מבחן עם העט האדום, אבל בלב חם.
+    5. כל התשובה בעברית.
+    6. אם אתה לא מצליח לזהות את כתב היד — ציין זאת בנימוס ובקש צילום ברור יותר.
+
+    ═══════════════════════════════════════════════════
+    📋 פורמט JSON נדרש (STRICT — ללא טקסט לפני או אחרי):
+    ═══════════════════════════════════════════════════
+    {{
+        "verdict": "correct" | "has_errors" | "methodology_error" | "unreadable",
+        "problem_identified": "מה התרגיל שזוהה מהתמונה (LaTeX)",
+        "methodology_ok": true | false,
+        "methodology_note": "הערה על השיטה שנבחרה (ריק אם הכל תקין)",
+        "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"
+    }}
+
+    CRITICAL: Output ONLY the JSON block. No text before, no text after.
+    """

proof_graph.py

@@ -0,0 +1,41 @@
+# proof_graph.py - Immutable Mathematical Structure
+
+from pydantic import BaseModel, Field
+from typing import Optional, List, Dict, Any
+
+class ProofStep(BaseModel):
+    step_id: int
+    math_content: str  # Immutable SymPy/LaTeX (or math_artifact)
+    logic_description: str = ""
+    operator_used: str = ""
+    # V6 Additions:
+    rule_id: str = "general_algebra"
+    allowed_concepts: List[str] = Field(default_factory=list)
+    complexity_score: float = 1.0
+    pedagogical_tag: str = "כללי"
+
+class ProofGraph:
+    def __init__(self, steps: list[ProofStep]):
+        self.steps = steps
+        self.is_verified = False
+
+    def verify_consistency(self):
+        # SymPy identity checks between steps
+        pass
+
+def validate_pedagogical_legality(proof_graph: ProofGraph, curriculum_rules: dict) -> tuple[bool, str]:
+    """
+    V4.0: The Hard Enforcement Rule.
+    Checks if any step in the proof graph uses a forbidden math operator.
+    """
+    forbidden = curriculum_rules.get("forbidden", [])
+    reason_map = curriculum_rules.get("reason_map", {})
+    
+    for step in proof_graph.steps:
+        if step.operator_used in forbidden:
+            detailed_reason = reason_map.get(step.operator_used, step.operator_used)
+            msg = f"Forbidden operator used: {detailed_reason}. Not allowed for this grade/level."
+            print(f"🚨 [PEDAGOGY-GUARD] REJECTED: {msg}")
+            return False, msg
+            
+    return True, "Solution is pedagogically legal."

quota_system.py

@@ -0,0 +1,211 @@
+import json
+import os
+import datetime
+from threading import Lock
+from config import IS_PRODUCTION  # Added for V3.1.3 Quota Override
+
+import tempfile
+import shutil
+
+LIMITS_FILE = "student_limits.json"
+# V260.9: Use /tmp or local for usage stats to avoid permission errors
+USAGE_FILENAME = "usage_stats.json"
+
+# Function to get writable usage path
+def get_usage_file_path():
+    # Try local first
+    if os.access(".", os.W_OK):
+        return USAGE_FILENAME
+    # Fallback to temp dir
+    return os.path.join(tempfile.gettempdir(), USAGE_FILENAME)
+
+USAGE_FILE = get_usage_file_path()
+
+# V261: Persistent user tracking
+ALL_USERS_FILE = "all_users.json"
+
+class QuotaManager:
+    def __init__(self):
+        self.lock = Lock()
+        print(f"📊 [QUOTA] Using stats file: {USAGE_FILE}")
+        self._load_limits()
+        self._ensure_files()
+
+    def _ensure_files(self):
+        if not os.path.exists(LIMITS_FILE):
+            try:
+                with open(LIMITS_FILE, 'w', encoding='utf-8') as f:
+                    json.dump({"default_limit": 30, "students": {}}, f)
+            except PermissionError:
+                print(f"⚠️ [QUOTA] Cannot create defaults limits file (Read-only fs)")
+
+        if not os.path.exists(USAGE_FILE):
+             try:
+                with open(USAGE_FILE, 'w', encoding='utf-8') as f:
+                    json.dump({}, f)
+             except Exception as e:
+                 print(f"⚠️ [QUOTA] Failed to init usage file: {e}")
+
+        # V261: Ensure persistent user list exists
+        if not os.path.exists(ALL_USERS_FILE):
+            try:
+                with open(ALL_USERS_FILE, 'w', encoding='utf-8') as f:
+                    json.dump({}, f)
+                print(f"📊 [QUOTA] Created {ALL_USERS_FILE}")
+            except Exception as e:
+                print(f"⚠️ [QUOTA] Failed to init all_users file: {e}")
+
+    def _load_limits(self):
+        try:
+            with open(LIMITS_FILE, 'r', encoding='utf-8') as f:
+                self.limits_config = json.load(f)
+        except Exception as e:
+            print(f"⚠️ [QUOTA] Failed to load limits: {e}")
+            self.limits_config = {"default_limit": 30, "students": {}, "blocked_users": []}
+
+        # V3.1.3: DEV Quota Reset
+        if not IS_PRODUCTION:
+            self.limits_config["default_limit"] = 1000
+
+    def _load_usage(self):
+        try:
+            with open(USAGE_FILE, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except Exception:
+            return {}
+
+    def _save_usage(self, usage_data):
+        try:
+            with open(USAGE_FILE, 'w', encoding='utf-8') as f:
+                json.dump(usage_data, f, indent=2)
+        except Exception as e:
+            print(f"⚠️ [QUOTA] Failed to save usage: {e}")
+
+    def _load_all_users(self):
+        try:
+            with open(ALL_USERS_FILE, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except:
+            return {}
+
+    def _save_all_users(self, data):
+        try:
+            with open(ALL_USERS_FILE, 'w', encoding='utf-8') as f:
+                json.dump(data, f, indent=2)
+        except Exception as e:
+            print(f"⚠️ [QUOTA] Failed to save all_users: {e}")
+
+    def get_today_key(self):
+        return datetime.date.today().isoformat()
+
+    def track_user(self, student_name):
+        """V261: Updates the last_seen for a user in persistent storage"""
+        if not student_name: return
+        try:
+            with self.lock:
+                users = self._load_all_users()
+                users[student_name] = {
+                    "last_seen": datetime.datetime.now().isoformat(),
+                    "id": student_name
+                }
+                self._save_all_users(users)
+        except Exception as e:
+            print(f"⚠️ [QUOTA] Failed to track user: {e}")
+
+    def check_limit(self, student_name):
+        """
+        Returns:
+            (allowed: bool, message: str, current_usage: int, limit: int)
+        """
+        if not student_name:
+            return True, "No name", 0, 9999
+
+        # V261: Track user on every check
+        self.track_user(student_name)
+
+        # Refresh limits config in case it changed manually
+        self._load_limits()
+
+        if student_name in self.limits_config.get("blocked_users", []):
+             return False, "User is blocked", 0, 0
+
+        limit = self.limits_config.get("students", {}).get(student_name, self.limits_config.get("default_limit", 30))
+        
+        # Admin override or high limit
+        if limit < 0: 
+            return True, "Unlimited", 0, -1
+
+        today = self.get_today_key()
+        with self.lock:
+            usage_data = self._load_usage()
+            today_usage = usage_data.get(today, {})
+            current_count = today_usage.get(student_name, 0)
+
+        if current_count >= limit:
+            return False, f"Daily limit reached ({limit})", current_count, limit
+
+        return True, "Allowed", current_count, limit
+
+    def increment_usage(self, student_name):
+        if not student_name:
+            return
+            
+        today = self.get_today_key()
+        with self.lock:
+            usage_data = self._load_usage()
+            if today not in usage_data:
+                usage_data[today] = {}
+            
+            usage_data[today][student_name] = usage_data[today].get(student_name, 0) + 1
+            self._save_usage(usage_data)
+            
+        print(f"📊 [QUOTA] Incremented for {student_name}. Date: {today}")
+
+    # ================= ADMIN METHODS (V261) =================
+
+    def get_all_users_data(self):
+        """Merges all_users (history), limits (config), and usage (today)"""
+        all_users = self._load_all_users() # {id: {last_seen...}}
+        limits = self.limits_config
+        today_usage = self._load_usage().get(self.get_today_key(), {})
+        
+        result = []
+        # Merge known users from history
+        for uid, udata in all_users.items():
+            limit = limits.get("students", {}).get(uid, limits.get("default_limit", 30))
+            usage = today_usage.get(uid, 0)
+            result.append({
+                "id": uid,
+                "last_seen": udata.get("last_seen"),
+                "limit": limit,
+                "usage_today": usage,
+                "is_blocked": uid in limits.get("blocked_users", [])
+            })
+            
+        # Also include users in limits config who might not be in history yet (?)
+        # (Optional, skipping for now to keep it simple)
+        
+        # Sort by most recently seen
+        result.sort(key=lambda x: x.get("last_seen", ""), reverse=True)
+        return result
+
+    def set_user_limit(self, user_id, new_limit):
+        """Updates the limit for a specific user"""
+        with self.lock:
+            self._load_limits()
+            if "students" not in self.limits_config:
+                self.limits_config["students"] = {}
+            
+            try:
+                limit_int = int(new_limit)
+                self.limits_config["students"][user_id] = limit_int
+                
+                # Save back to file
+                with open(LIMITS_FILE, 'w', encoding='utf-8') as f:
+                    json.dump(self.limits_config, f, indent=4)
+                return True, "Updated"
+            except Exception as e:
+                return False, str(e)
+
+# Global instance
+quota_manager = QuotaManager()

refiner.py

@@ -0,0 +1,31 @@
+import re
+import logging
+
+logger = logging.getLogger("Refiner")
+
+class Refiner:
+    @staticmethod
+    def refine(data: dict) -> dict:
+        try:
+            if 'sections' in data and isinstance(data['sections'], list):
+                for section in data['sections']:
+                    if 'steps' in section and isinstance(section['steps'], list):
+                        for step in section['steps']:
+                            # חשוב: אנחנו מנקים רק את block_math מדולרים
+                            # את content_mixed אנחנו משאירים עם דולרים כדי שהאפליקציה תרנדר!
+                            if 'block_math' in step:
+                                step['block_math'] = Refiner._clean_latex_block(step['block_math'])
+            
+            return data
+        except Exception as e:
+            logger.error(f"Refinement error: {e}")
+            return data
+
+    @staticmethod
+    def _clean_latex_block(tex: str) -> str:
+        if not tex or tex == 'null': return ""
+        s = str(tex)
+        # בבלוק מתמטי נקי לא צריך דולרים
+        s = s.replace('$$', '').replace('$', '')
+        s = s.replace('-', '−') # מינוס יפה
+        return s.strip()

requirements.txt

@@ -0,0 +1,14 @@
+fastapi
+uvicorn
+python-multipart
+google-generativeai==0.8.3
+pillow
+python-dotenv
+json_repair
+matplotlib
+numpy
+sympy
+edge-tts>=7.0.0
+firebase-admin==6.4.0
+opencv-python-headless
+sse-starlette

smart_solver.py

@@ -0,0 +1,698 @@
+# smart_solver.py - V7.4 (TYPED SIGNED STEPS + DOMAIN-AWARE CONTRACTS)
+import re
+import hashlib
+import logging
+import sympy
+from sympy import symbols, Eq, solve, sympify, diff, latex, Symbol, simplify, trigsimp
+from sympy import srepr, default_sort_key
+from pydantic import BaseModel, Field
+from typing import List, Dict, Any, Tuple, Union, Optional
+from dataclasses import dataclass
+import copy
+from domain.step_types import StepType, SignedStep
+
+logger = logging.getLogger(__name__)
+
+# ==================== V7.3: TYPED ACTION CONTRACT ====================
+
+@dataclass
+class ActionContext:
+    """
+    V7.3: Typed contract between Orchestrator and Solver.
+    Replaces generic dict — unknown fields cause AttributeError, not silent bugs.
+    Add new fields here as the system learns new problem types.
+    """
+    center: Optional[Tuple[float, float]] = None
+    radius: Optional[float] = None
+    point_a: Optional[Tuple[float, float]] = None
+    # Future: triangle_vertices, line_coefficients, etc.
+
+
+# ==================== V7.2: DETERMINISTIC SIGNATURE ENGINE ====================
+
+def sign_step(expression: Union[str, list], problem_id: str, step_id: str) -> SignedStep:
+    """
+    V7.4: Creates a SHA256-signed algebraic step as a typed SignedStep.
+    Uses sympy.srepr for canonical representation to guarantee deterministic hashing.
+    Sorts list results to ensure hash stability regardless of SymPy output order.
+
+    step_type = ALGEBRAIC — ConsistencyGate will validate via sympy.sympify.
+    payload   = raw expression list or string (semantic truth for validator).
+    expression = display string injected into renderer placeholders.
+    """
+    if isinstance(expression, list):
+        # Sort for canonical order (critical for hash determinism)
+        parsed_exprs = sorted(
+            [sympy.sympify(e) for e in expression],
+            key=default_sort_key
+        )
+        canonical = str([srepr(e) for e in parsed_exprs])
+        expr_str = " OR ".join(str(e) for e in parsed_exprs)
+        payload = [str(e) for e in parsed_exprs]
+    else:
+        parsed = sympy.sympify(expression)
+        canonical = srepr(parsed)
+        expr_str = str(parsed)
+        payload = expr_str
+
+    raw = f"{canonical}{problem_id}{step_id}"
+    sig = hashlib.sha256(raw.encode()).hexdigest()
+
+    logger.info(f"[SIGNATURE] Signed step '{step_id}': hash={sig[:12]}...")
+    return SignedStep(
+        id=step_id,
+        expression=expr_str,
+        payload=payload,
+        step_type=StepType.ALGEBRAIC,
+        hash=sig,
+    )
+
+
+def sign_step_geometry(labels: list, problem_id: str, step_id: str) -> SignedStep:
+    """
+    V7.4: Typed signer for geometry results (strings, not SymPy expressions).
+
+    step_type = GEOMETRY — ConsistencyGate validates structurally, NOT via sympify.
+    payload   = original labels list (semantic truth: list[str] of points/distances).
+    expression = display string for renderer injection (pipe-separated, human-readable).
+
+    CTO note: expression is display-only. payload is the authoritative structure
+    the validator uses to verify integrity. Never pass expression to sympy.
+    """
+    canonical = str(sorted(str(l) for l in labels))
+    sig = hashlib.sha256(f"{canonical}{problem_id}{step_id}".encode()).hexdigest()
+    expr_str = " | ".join(str(l) for l in labels)
+    logger.info(f"[SIGNATURE] Signed geometry step '{step_id}': hash={sig[:12]}...")
+    return SignedStep(
+        id=step_id,
+        expression=expr_str,
+        payload=list(labels),
+        step_type=StepType.GEOMETRY,
+        hash=sig,
+    )
+
+
+def resolve_ast_target(target_step_ref: str, ast_registry: dict) -> str:
+    """
+    V7.2: Looks up the actual math expression for an AST node ID.
+    The Planner works with IDs only — this is where IDs are resolved to real math.
+    Raises KeyError if the reference is invalid, preventing silent hallucination.
+    """
+    if target_step_ref not in ast_registry:
+        raise KeyError(
+            f"[RESOLVER] AST node '{target_step_ref}' not found in registry. "
+            f"Known nodes: {list(ast_registry.keys())}"
+        )
+    return ast_registry[target_step_ref]
+
+
+# ==================== V7.2.1: DETERMINISTIC SOLVER DISPATCHER ====================
+
+def execute_action(
+    action: str,
+    expression: str,
+    problem_id: str,
+    step_id: str,
+    ast_variables: list = None,
+    context: Optional[ActionContext] = None
+) -> dict:
+    """
+    V7.2.1 Wall 2: Deterministic Math Engine.
+
+    Routes a Planner Enum command to SymPy, executes it deterministically,
+    and returns a SHA256-signed step result.
+
+    Multi-variable handling (CTO note): if the expression has multiple free
+    symbols, we solve for the first variable listed in `ast_variables` (from
+    AST metadata). If no list is provided, we default to the first free symbol
+    found by SymPy — never guess blindly.
+
+    Args:
+        action:        One of ComputeAction enum values (string)
+        expression:    Raw math expression string from AST registry
+        problem_id:    For hash seeding
+        step_id:       For hash seeding and tracking
+        ast_variables: Ordered list of variable names from build_ast_metadata()
+
+    Returns:
+        dict: {"id": step_id, "hash": "sha256...", "expression": "..."}
+    """
+    import sympy as sp
+
+    # Parse expression — treat '=' as LHS - RHS for sp.solve
+    normalized = expression.replace('=', '-')
+    try:
+        expr = sp.sympify(normalized, evaluate=False)
+    except Exception as e:
+        raise ValueError(f"[SOLVER] Cannot parse expression '{expression}': {e}")
+
+    # Multi-variable: determine which symbol to solve for
+    free_syms = list(expr.free_symbols)
+    solve_for = None
+    if action == "SOLVE_EQUATION":
+        if ast_variables:
+            # Use the first AST-declared variable that is actually in the expression
+            for var_name in ast_variables:
+                candidate = sp.Symbol(var_name)
+                if candidate in free_syms:
+                    solve_for = candidate
+                    break
+        if solve_for is None and free_syms:
+            # Fallback: first free symbol (alphabetically for determinism)
+            solve_for = sorted(free_syms, key=lambda s: s.name)[0]
+            logger.warning(
+                f"[SOLVER] No ast_variables hint provided. "
+                f"Solving for '{solve_for}' (first free symbol in expression)."
+            )
+
+    # ── V7.3: Geometry Guards ──────────────────────────────────────────────────
+    if action == "CALCULATE_DISTANCE" and (
+        not context or not context.center or not context.point_a
+    ):
+        raise ValueError(
+            "MissingContextError: CALCULATE_DISTANCE requires context.center and context.point_a"
+        )
+
+    if action == "CALCULATE_SLOPE_AND_LINE" and (
+        not context or not context.center or not context.point_a
+    ):
+        raise ValueError(
+            "MissingContextError: CALCULATE_SLOPE_AND_LINE requires context.center and context.point_a"
+        )
+
+    # ── V7.3: Geometry Handler Dispatch ───────────────────────────────────────
+    if action == "FIND_AXIS_INTERSECTIONS":
+        # Substitute x=0 → solve for y, then y=0 → solve for x
+        x_sym, y_sym = sp.Symbol('x'), sp.Symbol('y')
+        y_intercepts = sp.solve(expr.subs(x_sym, 0), y_sym)
+        x_intercepts = sp.solve(expr.subs(y_sym, 0), x_sym)
+        # Build human-readable result list
+        result_parts = []
+        for yi in y_intercepts:
+            result_parts.append(f"(0, {yi})")  # x=0
+        for xi in x_intercepts:
+            result_parts.append(f"({xi}, 0)")  # y=0
+        result = result_parts if result_parts else ["אין נקודות חיתוך עם הצירים"]
+        logger.info(f"[SOLVER] ✅ FIND_AXIS_INTERSECTIONS on '{expression}' → {result}")
+        return sign_step_geometry(result, problem_id, step_id)
+
+    elif action == "CALCULATE_SLOPE_AND_LINE":
+        cx, cy = context.center           # e.g. (3, 4)
+        px, py = context.point_a         # e.g. (0, 0) — origin
+        # Vertical line guard
+        if px == cx:
+            line_eq = f"x = {cx}"
+            result = [line_eq]
+        else:
+            slope = sp.Rational(cy - py, cx - px)  # exact fraction (no float)
+            # y - py = slope*(x - px)  →  y = slope*x + b
+            b = py - slope * px
+            x_sym = sp.Symbol('x')
+            line_expr = slope * x_sym + b
+            # Simplify and return LaTeX-friendly string
+            result = [str(sp.simplify(line_expr))]
+        logger.info(f"[SOLVER] ✅ CALCULATE_SLOPE_AND_LINE center={context.center} → {result}")
+        return sign_step_geometry(result, problem_id, step_id)
+
+    elif action == "CALCULATE_DISTANCE":
+        cx, cy = context.center
+        px, py = context.point_a
+        # Use exact Rational arithmetic to avoid float comparison ambiguity
+        cx_r, cy_r = sp.Rational(cx).limit_denominator(1000), sp.Rational(cy).limit_denominator(1000)
+        px_r, py_r = sp.Rational(px).limit_denominator(1000), sp.Rational(py).limit_denominator(1000)
+        dist = sp.sqrt((px_r - cx_r)**2 + (py_r - cy_r)**2)
+        dist_val = sp.simplify(dist)       # SymPy exact value (e.g. 5)
+        radius_sym = sp.Rational(context.radius).limit_denominator(1000)
+
+        # 🚨 [SOP FIX] Guard against NoneType before float cast
+        for val in [dist_val, radius_sym]:
+            if val is None or val == "null" or val == "":
+                raise ValueError("Missing required mathematical argument from LLM. Cannot cast None to float.")
+
+        # Comparison via Python float (avoids SymPy Float vs int ambiguity)
+        dist_float = float(dist_val)
+        radius_float = float(radius_sym)
+        if abs(dist_float - radius_float) < 1e-9:
+            on_circle = "על המעגל"
+        elif dist_float < radius_float:
+            on_circle = "בתוך המעגל"
+        else:
+            on_circle = "מחוץ למעגל"
+        result = [f"d = {dist_val}", f"r = {context.radius}", on_circle]
+        logger.info(f"[SOLVER] ✅ CALCULATE_DISTANCE point={context.point_a} center={context.center} → {result}")
+        return sign_step_geometry(result, problem_id, step_id)
+
+    # ── Legacy Algebraic Action Dispatch ──────────────────────────────────────
+    ACTION_MAP = {
+        "SOLVE_EQUATION":  lambda e: sp.solve(e, solve_for) if solve_for else sp.solve(e),
+        "SIMPLIFY":        lambda e: [sp.simplify(e)],
+        "FACTOR":          lambda e: [sp.factor(e)],
+        "EXPAND":          lambda e: [sp.expand(e)],
+        "FIND_DERIVATIVE": lambda e: [sp.diff(e, solve_for or (free_syms[0] if free_syms else sp.Symbol('x')))],
+        "FIND_INTEGRAL":   lambda e: [sp.integrate(e, solve_for or (free_syms[0] if free_syms else sp.Symbol('x')))],
+        "SUBSTITUTE":      lambda e: [e],
+    }
+
+    fn = ACTION_MAP.get(action)
+    if not fn:
+        raise ValueError(f"[SOLVER] Unknown action: '{action}'. Check ComputeAction enum.")
+
+    try:
+        result = fn(expr)
+        if not isinstance(result, list):
+            result = [result]
+        logger.info(f"[SOLVER] ✅ {action} on '{expression}' → {result}")
+    except Exception as e:
+        raise RuntimeError(f"[SOLVER] SymPy failed on action '{action}': {e}")
+
+    return sign_step(result, problem_id, step_id)
+
+
+
+
+class MathState(BaseModel):
+    """ייצוג מתמטי אחיד של מצב הבעיה"""
+    equations: List[Any] = Field(default_factory=list) # רשימת משוואות SymPy
+    solved_vars: Dict[Any, Any] = Field(default_factory=dict) # משתנים שנפתרו
+    original_text: str = ""
+    
+    class Config:
+        arbitrary_types_allowed = True
+        
+    def is_solved(self) -> bool:
+        # במערכת משוואות MVP: אם יש משתנים פתורים ואין עוד משוואות בלתי פתורות רלוונטיות
+        if not self.equations:
+            return len(self.solved_vars) > 0
+        all_syms = set()
+        for eq in self.equations:
+            all_syms.update(eq.free_symbols)
+        # נפתר אם כל המשתנים מקבלים ערך
+        return len(all_syms) > 0 and all(sym in self.solved_vars for sym in all_syms)
+
+# ==================== V5.8.0 RULE ENGINE MVP ====================
+
+class MathRule:
+    name: str = "BaseRule"
+    
+    def is_applicable(self, state: MathState) -> bool:
+        return False
+        
+    def apply(self, state: MathState) -> Tuple[MathState, Any]:
+        raise NotImplementedError()
+
+class RuleSolveLinearSystem(MathRule):
+    name = "פתרון מערכת משוואות"
+    
+    def __init__(self):
+        self.x, self.y = symbols('x y')
+        
+    def is_applicable(self, state: MathState) -> bool:
+        # נזהה מערכת של 2 משוואות עם 2 נעלמים חופשיים
+        if len(state.equations) >= 2:
+            syms = set()
+            for eq in state.equations:
+                syms.update(eq.free_symbols)
+            if len(syms) == 2:
+                return True
+        return False
+        
+    def apply(self, state: MathState) -> Tuple[MathState, Any]:
+        new_state = copy.copy(state)
+        # ניסיון פתרון סימבולי למערכת המשוואות יחד
+        eq1 = state.equations[0]
+        eq2 = state.equations[1]
+        
+        # V5.8.1: Detailed Steps Mode (Step Granularity)
+        # Check if both equations are of the form "sym = expression" and have the same LHS
+        if eq1.lhs == eq2.lhs and isinstance(eq1.lhs, Symbol):
+            lhs_sym = eq1.lhs
+            # Get the other symbol playing the role of x
+            rhs_syms = list((eq1.rhs.free_symbols | eq2.rhs.free_symbols) - {lhs_sym})
+            if len(rhs_syms) == 1:
+                rhs_sym = rhs_syms[0]
+                steps = []
+                
+                # 1. Equate
+                eq_step = Eq(eq1.rhs, eq2.rhs)
+                steps.append({"logic": "נשווה בין שתי המשוואות", "math": latex(eq_step), "rule_id": "solve_linear_system"})
+                
+                # 2. Collect terms
+                diff_expr = eq_step.lhs - eq_step.rhs
+                c = diff_expr.coeff(rhs_sym)
+                d = diff_expr.subs(rhs_sym, 0)
+                collected_eq = Eq(c * rhs_sym, -d)
+                steps.append({"logic": "נעביר אגפים ונכנס איברים דומים", "math": latex(collected_eq), "rule_id": "solve_linear_system"})
+                
+                # 3. Isolate variable
+                x_val = -d / c
+                isolated_eq = Eq(rhs_sym, x_val)
+                steps.append({"logic": f"נחלק במקדם של {latex(rhs_sym)}", "math": latex(isolated_eq), "rule_id": "solve_linear_system"})
+                
+                # 4. Substitute back
+                y_val = eq1.rhs.subs(rhs_sym, x_val)
+                # string replacement for substitution display to avoid auto-evaluation collapsing it
+                subs_str = latex(eq1.rhs).replace(latex(rhs_sym), f"({latex(x_val)})")
+                steps.append({"logic": f"נציב את {latex(rhs_sym)} באחת המשוואות", "math": f"{latex(lhs_sym)} = {subs_str} = {latex(y_val)}", "rule_id": "solve_linear_system"})
+                
+                new_state.solved_vars[rhs_sym] = x_val
+                new_state.solved_vars[lhs_sym] = y_val
+                new_state.equations = []
+                return new_state, steps
+
+        # V5.8.3 The Ultimate Guard: No step breakdown -> No solve
+        return state, "לא ניתן לפרק לצעדים מדורגים."
+
+class RuleIsolateVariable(MathRule):
+    name = "בידוד משתנה"
+    def is_applicable(self, state: MathState) -> bool:
+        # האם יש משוואה אחת שניתן לבודד ממנה משתנה שעדיין לא בודד?
+        if len(state.equations) == 1:
+            return True
+        return False
+        
+    def apply(self, state: MathState) -> Tuple[MathState, Any]:
+        new_state = copy.copy(state)
+        eq = state.equations[0]
+        syms = list(eq.free_symbols)
+        if not syms: return state, "אין משתנים לבידוד."
+        # ננסה לבודד את המשתנה (למשל x)
+        sol = solve(eq, syms[0])
+        if sol:
+            new_state.solved_vars[syms[0]] = sol[0]
+            new_state.equations = []
+            steps = [{"logic": "נבודד את המשתנה", "math": f"{latex(syms[0])} = {latex(sol[0])}", "rule_id": "isolate_variable"}]
+            return new_state, steps
+        return state, "לא ניתן לבודד משתנה"
+
+class RuleSubstitute(MathRule):
+    name = "הצבת משתנה שבודד"
+    def is_applicable(self, state: MathState) -> bool:
+        return len(state.solved_vars) > 0 and len(state.equations) > 0
+        
+    def apply(self, state: MathState) -> Tuple[MathState, Any]:
+        new_state = copy.copy(state)
+        # נציב את כל המשתנים הידועים בתוך המשוואות שנותרו
+        new_eqs = []
+        for eq in state.equations:
+            new_eq = eq.subs(state.solved_vars)
+            new_eqs.append(new_eq)
+        new_state.equations = new_eqs
+        # אנחנו לא מוחקים את state.solved_vars כי נרצה לזכור אותם להמשך
+        str_vars = ", ".join([f"{latex(k)} = {latex(v)}" for k,v in state.solved_vars.items()])
+        steps = [{"logic": "נציב את הערכים הידועים במשוואות", "math": str_vars, "rule_id": "substitute"}]
+        return new_state, steps
+
+
+class StepValidator:
+    """
+    V6.1 Phase 3: Validation Authority
+    Acts as the 'Supreme Court' for LLM proposed ProofGraphs.
+    """
+    
+    ALLOWED_CONSTANTS = {'pi', 'E', 'sqrt(2)'} # Removed 'I' as per QA Gate requirements.
+    
+    @classmethod
+    def sympy_simplify_tolerance_guard(cls, expr_n, expr_n_plus_1) -> bool:
+        """
+        V6.1 Phase 4: Tolerance Guard
+        Numerical evaluation fallback to handle micro-variances that avoid simplification.
+        """
+        import random
+        try:
+            diff_expr = expr_n - expr_n_plus_1
+            free_syms = diff_expr.free_symbols
+            
+            # If no free symbols, just evaluate numerically
+            if not free_syms:
+                val = diff_expr.evalf()
+                # 🚨 [SOP FIX] Guard against NoneType before float cast
+                if val is None or val == "null" or val == "":
+                    raise ValueError("Missing required mathematical argument from LLM. Cannot cast None to float.")
+                return abs(float(val)) < 1e-9
+            
+            # Sampling: 10 random points
+            for _ in range(10):
+                subs = {s: random.uniform(0.1, 10.0) for s in free_syms}
+                val = diff_expr.evalf(subs=subs)
+                # 🚨 [SOP FIX] Guard against NoneType before float cast
+                if val is None or val == "null" or val == "":
+                    raise ValueError("Missing required mathematical argument from LLM. Cannot cast None to float.")
+                if abs(float(val)) > 1e-9: # Precision set to 10^-9 as per QA Gate
+                    return False
+            return True
+        except Exception:
+            return False
+
+    @classmethod
+    def validate_transition(cls, step_n: str, step_n_plus_1: str) -> bool:
+        """
+        Deterministically verifies the algebraic equivalence between two steps.
+        """
+        try:
+            expr_n = sympify(str(step_n).replace('=', '-'), evaluate=False)
+            expr_n_plus_1 = sympify(str(step_n_plus_1).replace('=', '-'), evaluate=False)
+            
+            # Use simplify to check equivalence
+            diff = simplify(expr_n - expr_n_plus_1)
+            
+            if diff == 0:
+                return True
+                
+            # Fallback for trigonometric identities or complex simplification
+            if trigsimp(expr_n) == trigsimp(expr_n_plus_1):
+                 return True
+                 
+            # V6.1 Phase 4: Tolerance Guard (Secondary Check)
+            if cls.sympy_simplify_tolerance_guard(expr_n, expr_n_plus_1):
+                logger.info(f"🛡️ [VALIDATOR] Tolerance Guard PASSED for {step_n} -> {step_n_plus_1}")
+                return True
+
+            # If equivalence fails, it might be an irreversible action (e.g. squaring).
+            return False
+            
+        except Exception as e:
+            logger.warning(f"[VALIDATOR] Transition validation error '{step_n}' -> '{step_n_plus_1}': {e}")
+            return False
+
+    @classmethod
+    def check_proofgraph_closure(cls, initial_math: str, final_step: str) -> bool:
+        """
+        Ensures all variables in the original problem are resolved or accounted for,
+        and no hallucinations occurred via injected fake constants/variables.
+        """
+        try:
+            initial_exprs = [sympify(str(p).replace('=', '-'), evaluate=False) for p in str(initial_math).split(',')]
+            initial_vars = set()
+            for ex in initial_exprs:
+                initial_vars.update(ex.free_symbols)
+                
+            final_exprs = [sympify(str(p).replace('=', '-'), evaluate=False) for p in str(final_step).split(',')]
+            final_vars = set()
+            for ex in final_exprs:
+                final_vars.update(ex.free_symbols)
+                
+            filtered_final_vars = {str(v) for v in final_vars if not v.is_number and str(v) not in cls.ALLOWED_CONSTANTS}
+            filtered_initial_vars = {str(v) for v in initial_vars if not v.is_number and str(v) not in cls.ALLOWED_CONSTANTS}
+            
+            if len(filtered_final_vars - filtered_initial_vars) > 0:
+                logger.warning(f"[VALIDATOR] Closure check failed. Leaked vars: {filtered_final_vars - filtered_initial_vars}")
+                return False
+                
+            return True
+        except Exception as e:
+            logger.warning(f"[VALIDATOR] Closure validation error: {e}")
+            return False
+            
+    @classmethod
+    def evaluate_proposal(cls, initial_math: str, draft_steps: list) -> tuple[float, str]:
+        """
+        Evaluates the entire Draft ProofGraph.
+        Returns (Validation Score [0.0 - 1.0], Error Reason)
+        """
+        if not draft_steps:
+             return 0.0, "EMPTY_DRAFT"
+             
+        valid_transitions = 0
+        total_transitions = len(draft_steps)
+        
+        # We assume step 0 is the initial math or a reformatted version of it.
+        # We validate transition from step[i] to step[i+1]
+        for i in range(len(draft_steps) - 1):
+            math_n = draft_steps[i].get('math', '')
+            math_n_plus_1 = draft_steps[i+1].get('math', '')
+            
+            if cls.validate_transition(math_n, math_n_plus_1):
+                valid_transitions += 1
+            else:
+                 logger.warning(f"[VALIDATOR] Rejecting step {i+1} -> {i+2}: {math_n} to {math_n_plus_1}")
+                 return 0.0, f"מעבר מתמטי שגוי בין: {math_n} לבין {math_n_plus_1}"
+                 
+        score = valid_transitions / total_transitions if total_transitions > 0 else 0.0
+        
+        # Check Closure
+        final_step_math = draft_steps[-1].get('math', '')
+        if not cls.check_proofgraph_closure(initial_math, final_step_math):
+            return 0.0, "סגירת פתרון לא חוקית (נמצאו משתנים לא מאושרים)"
+            
+        return score, ""
+
+
+    def __init__(self, success=False, function=None, derivative=None, steps=None, operator_used=None):
+        self.success = success
+        self.function = function
+        self.derivative = derivative
+        self.steps = steps or [] # חובה עבור ה-ProofGraph
+        self.operator_used = operator_used
+
+class SmartSolver:
+    def __init__(self):
+        print("✅ 🟢 [BIT-LOG: SmartSolver V263.0] - Algebra Engine Active")
+
+    def solve(self, context):
+        math_input = context.math_input
+        category = context.category
+        original_text = getattr(context, 'original_text', "").lower()
+        grade_num = getattr(context, 'grade_num', 12)
+        
+        print(f"🔍 [BIT-LOG: SOLVER] Analyzing input: '{math_input}'")
+        print(f"🔍 [BIT-LOG: SOLVER] Category: {category}, Intent Text: '{original_text[:50]}...'")
+
+        # --- V5.8.0 Rule Engine MVP (Always First) ---
+        print("🔢 [BIT-LOG: SOLVER] Triggering Rule Engine MVP")
+        rule_engine_res = self._solve_linear_system(math_input)
+        if rule_engine_res and rule_engine_res.success:
+            return rule_engine_res
+
+        # --- ענף 2: חקירת פונקציות (כיתה י' עד י"ב) ---
+        # V4.2.12: Anchor regex to start of string to avoid matching 4x + 5y = 120 as 'y = 120'
+        is_explicit_func = bool(re.match(r'^(f\(x\)|y|g\(x\))\s*=', math_input, re.IGNORECASE))
+        investigation_keywords = ["חקור", "חקירת", "קיצון", "אסימפטוט", "נגזרת", "עליה", "ירידה"]
+        has_intent = any(kw in original_text for kw in investigation_keywords)
+
+        # הנגזרת תופעל רק אם: זו חקירה + יש פונקציה מפורשת + יש כוונה בטקסט
+        should_derive = (category == "INVESTIGATION" and is_explicit_func and has_intent and grade_num > 7)
+
+        if should_derive:
+            print("📈 [BIT-LOG: SOLVER] Triggering Calculus Engine (Derivatives)")
+            return self._solve_calculus(math_input)
+
+        # Fallback גנרי
+        print(f"🛡️ [BIT-LOG: SOLVER] Generic Algebra Mode. category={category}, intent={has_intent}")
+        return SmartResult(success=True, function=math_input, operator_used="ALGEBRA_GENERAL")
+
+    def _solve_linear_system(self, raw_input):
+        """V5.8.0: מנוע קבלת החלטות מבוסס MVP חוקים"""
+        try:
+            # שלב 1: Parsing
+            eq_parts = re.split(r'[,\n]', raw_input)
+            parsed_eqs = []
+            for part in eq_parts:
+                if '=' in part:
+                    s_a, s_b = part.split('=')
+                    parsed_eqs.append(Eq(sympify(self._sanitize(s_a)), sympify(self._sanitize(s_b))))
+            
+            if not parsed_eqs:
+                return SmartResult(success=False)
+
+            current_state = MathState(equations=parsed_eqs, original_text=raw_input)
+            rules = [RuleSolveLinearSystem(), RuleIsolateVariable(), RuleSubstitute()]
+            proof_graph_steps = []
+            iteration = 0
+            MAX_ITER = 5
+
+            logger.info(f"🧮 [RULE-ENGINE] Starting resolution for system: {parsed_eqs}")
+
+            # שלב 2: לולאת החוקים הארכיטקטונית (The Engine)
+            while not current_state.is_solved() and iteration < MAX_ITER:
+                applied_any = False
+                for rule in rules:
+                    if rule.is_applicable(current_state):
+                        new_state, step_data = rule.apply(current_state)
+                        if isinstance(step_data, list):
+                            for s in step_data:
+                                proof_graph_steps.append({
+                                    "id": len(proof_graph_steps) + 1,
+                                    "logic": s["logic"],
+                                    "math": s["math"]
+                                })
+                        else:
+                            proof_graph_steps.append({
+                                "id": len(proof_graph_steps) + 1,
+                                "logic": rule.name,
+                                "math": step_data
+                            })
+                        current_state = new_state
+                        applied_any = True
+                        break # Start rules over with new state
+                
+                if not applied_any:
+                    logger.warning("🧮 [RULE-ENGINE] No applicable rules found to continue solving.")
+                    break
+                
+                iteration += 1
+
+            # יצירת מודל SmartResult עם הוכחה מבוססת חוקים
+            if current_state.is_solved():
+                print(f"✅ [RULE-ENGINE] Resolved system to state: {current_state.solved_vars}")
+                # הוספת צעד סיכום אחרון
+                res_str = ", ".join([f"{latex(k)}={latex(v)}" for k,v in current_state.solved_vars.items()])
+                
+                return SmartResult(success=True, function=raw_input, steps=proof_graph_steps, operator_used="RULE_ENGINE_SYSTEM")
+            else:
+                 return SmartResult(success=False)
+                 
+        except Exception as e:
+            print(f"❌ [BIT-LOG: SOLVER] Algebra Rule Engine Error: {e}")
+            return SmartResult(success=False)
+
+    def _solve_calculus(self, math_input):
+        try:
+            x = symbols('x')
+            # חילוץ הביטוי אחרי ה- '='
+            expr_part = math_input.split('=')[-1]
+            expr_str = self._sanitize(expr_part)
+            logger.info(f"🧮 [TRACE] EXPRESSION SENT TO SYMPY: {expr_str}")
+            expr = sympify(expr_str)
+            f_prime = diff(expr, x)
+            
+            # חישוב נקודות קיצון
+            crit_points = []
+            try:
+                sols = solve(f_prime, x)
+                for s in sols:
+                    if s is not None and s.is_real:
+                        y_val = expr.subs(x, s).evalf()
+                        if y_val is not None:
+                            crit_points.append(f"({float(s):.2f}, {float(y_val):.2f})")
+            except Exception as e: 
+                logger.warning(f"[SOLVER] Calculus point evaluation failed: {e}")
+
+            steps = [{"id": 1, "math": f"f'(x)={latex(f_prime)}", "logic": "חישוב נגזרת"}]
+            return SmartResult(
+                success=True, 
+                function=f"f(x)={latex(expr)}", 
+                derivative=f"f'(x)={latex(f_prime)}", 
+                steps=steps, 
+                operator_used="DERIVATIVE"
+            )
+        except Exception as e:
+            print(f"❌ [BIT-LOG: SOLVER] Calculus Engine Error: {e}")
+            return SmartResult(success=False)
+
+    def _sanitize(self, text):
+        """✅ סנכרון עם מנגנון הניקוי המרכזי (V260.0)"""
+        text = text.replace(r'\left', '').replace(r'\right', '')
+        while r'\frac' in text:
+            text = re.sub(r'\\frac\s*\{(.*?)\}\{(.*?)\}', r'(\1)/(\2)', text)
+        
+        text = re.sub(r'(sin|cos|tan)\s+([a-zA-Z0-9]+)', r'\1(\2)', text)
+        text = text.replace(r'\sin', 'sin').replace(r'\cos', 'cos').replace(r'\tan', 'tan')
+        text = text.replace('^', '**')
+        
+        # ✅ V260.0: Robust implicit multiplication
+        text = re.sub(r'(\d)([a-zA-Z(])', r'\1*\2', text)
+        text = re.sub(r'\)([a-zA-Z0-9(])', r')*\1', text)
+        text = re.sub(r'(?<![a-zA-Z])([a-zA-Z])\(', r'\1*(', text)
+        
+        allowed = "0123456789+-*/().=xsincoabslpqrtABSpi eylog" 
+        return ''.join(c for c in text if c.lower() in allowed).strip()

strategy_manager.py

@@ -0,0 +1,215 @@
+import topic_taxonomy
+import micro_prompts
+import validators
+import asyncio
+import json
+import cost_tracker
+import re
+import logging
+from utils.safe_json import safe_extract_json  # V1.0: Canonical extractor (replaces local duplicate)
+import prompts
+
+logger = logging.getLogger(__name__)
+
+
+class StrategyManager:
+    def __init__(self, llm_model):
+        self.llm = llm_model
+        self.max_retries = 2
+    
+    async def solve_with_strategy(self, problem_text, data_anchor, grade="10", image_data=None, parent_category=None, ambiguity_warning=False, intent=None, intent_contract=None, proof_graph_steps_count=1, student_name="נסיך", student_gender="M"):
+        """
+        V3.1.2: Added support for adaptive failure (Soft Recovery).
+        V5.8.2: Dynamic Token Budget added via proof_graph_steps_count.
+        """
+        self.grade = grade # V4.2.11: Persist grade for prompt building
+        topic_id = topic_taxonomy.detect_topic(problem_text, grade)
+        detected_category = topic_taxonomy.get_topic_category(topic_id)
+        category = detected_category if detected_category != "GENERAL" else (parent_category or "GENERAL")
+        
+        image_pages = []
+        if image_data:
+            try:
+                from ocr_strip_engine import paginate_image
+                image_pages = paginate_image(image_data)
+            except Exception as e: 
+                logger.exception("CRITICAL FLOW ERROR")
+                logger.error(f"Pagination failed: {e}")
+        
+        # V4.3: Single Pass (No Retries)
+        try:
+            strategy_config = self._get_strategy(topic_id)
+            prompt = self._build_prompt(topic_id, data_anchor, strategy_config, problem_text, category, grade, student_name, student_gender)
+            
+            # V4.2 Intent Lockdown (Iron Law #2)
+            if intent_contract and intent_contract.get("status") != "unconstrained":
+                lockdown_note = f"""
+📢 [V4.2] PEDAGOGICAL LOCKDOWN:
+- Intent: {intent}
+- Max Variables: {intent_contract.get('max_variables', 'N/A')}
+- Forbidden: {", ".join(intent_contract.get('forbidden_strategies', []))}
+- REQUIRED: Use ONLY basic algebraic steps. DO NOT use advanced functions or calculus.
+"""
+                prompt = lockdown_note + "\n" + prompt
+            if data_anchor.get("function_equations"):
+                prompt = f"TARGET FUNCTION: {data_anchor['function_equations'][0]}\n\n" + prompt
+            
+            # V3.1.2: Soft Recovery Prompt Injection
+            if ambiguity_warning:
+                soft_recovery_note = """
+System Prompt Override: הוסף לתחילת ההסבר שלך את ההערה הבאה בנימה ידידותית: 'היי! הצילום היה קצת לא ברור, אבל נראה לי שהתכוונת לביטוי הזה. אם התכוונת למשהו אחר, פשוט צלם שוב מקרוב!' - המשך להסביר את השלבים כרגיל.
+"""
+                prompt = soft_recovery_note + "\n" + prompt
+
+            prompt += f"\n\n🎯 MISSION: Solve ONLY part: {problem_text}"
+            llm_response = await self._call_llm(prompt, image_data, category, image_pages, proof_graph_steps_count)
+            
+            # V5.8.2: Guard against raw list responses
+            if isinstance(llm_response, list):
+                llm_response = {"steps": llm_response, "is_valid": True, "confidence_score": 1.0}
+            
+            return {
+                "topic": topic_id,
+                "category": category,
+                "llm_response": llm_response,
+                "validated": llm_response.get("is_valid", True),
+                "confidence": llm_response.get("confidence_score", 1.0)
+            }
+        except asyncio.CancelledError:
+            logger.warning("V4.3 Single Pass Cancelled (Client Disconnected)")
+            return {
+                "topic": topic_id,
+                "category": category,
+                "llm_response": {"solution_markdown": "בוטל על ידי המשתמש", "is_valid": False, "confidence_score": 0.0},
+                "validated": False
+            }
+        except Exception as e:
+            logger.error(f"V4.3 Single Pass Failed: {e}")
+            return {
+                "topic": topic_id,
+                "category": category,
+                "llm_response": {"solution_markdown": "המורה נתקלה בקושי טכני.", "is_valid": False, "confidence_score": 0.0},
+                "validated": False
+            }
+
+    def _get_strategy(self, topic_id):
+        return {"has_micro_prompt": topic_id in micro_prompts.MICRO_PROMPTS, "has_validator": topic_id in validators.VALIDATORS}
+
+    def _build_prompt(self, topic_id, data_anchor, strategy_config, problem_text, category, grade, student_name, student_gender):
+        # V7.3 Hybrid Mode: Always use Specialist Prompt for the "Solution Skin"
+        specialist = prompts.get_specialist_prompt(
+            category=category,
+            problem_text=problem_text,
+            solver_hint="Hybrid Navigation Mode",
+            grade=grade,
+            student_name=student_name,
+            student_gender=student_gender,
+            data_anchor=data_anchor
+        )
+
+        if strategy_config["has_micro_prompt"]:
+            try: 
+                 focus = micro_prompts.get_micro_prompt(topic_id, data_anchor, grade=self.grade)
+                 return f"{focus}\n\n{specialist}"
+            except: 
+                 pass
+        
+        return specialist
+        return micro_prompts.get_general_prompt(data_anchor)
+
+    async def _call_llm(self, prompt, image_data, category, image_pages, proof_graph_steps_count=1):
+        # V8.5: No More Patchwork. Use centralized V4.3.0 standard.
+        v430_instruction = prompts.get_master_prompt_v430()
+        prompt += v430_instruction
+        
+        from google.generativeai.types import GenerationConfig
+        import asyncio
+        
+        # V5.8.3: Pre-release Hardening (Increased Budget for Preamble)
+        # V8.6: Golden Merge - Increased to 8192 to support high-density Micro-Stepping
+        max_tokens = 8192
+        logger.info(f"🪙 [BUDGET] Dynamic Token Budget allocated: {max_tokens} tokens for {proof_graph_steps_count} steps.")
+        
+        gen_config = GenerationConfig(
+            temperature=0.0, 
+            top_p=0.1, 
+            top_k=1,
+            max_output_tokens=max_tokens,
+            response_mime_type="application/json"
+        )
+        
+        try:
+            if image_pages:
+                payload = [f"Images are sequential. Image 1 is Header.\n{prompt}"] + image_pages
+                logger.info(f"🧠 [TRACE] PROMPT SENT TO LLM: {payload[0]}")
+                # V8.5: True Async Cancellation. Using current_task to handle disconnects.
+                response = await asyncio.wait_for(
+                    self.llm.generate_content_async(payload, generation_config=gen_config), 
+                    timeout=60.0
+                )
+            else:
+                logger.info(f"🧠 [TRACE] PROMPT SENT TO LLM: {prompt}")
+                response = await asyncio.wait_for(
+                    self.llm.generate_content_async(prompt, generation_config=gen_config), 
+                    timeout=30.0
+                )
+        except asyncio.CancelledError:
+            # HARD STOP: Client disconnected. Active cancellation is handled by wait_for + generate_content_async
+            logger.warning("📉 [V8.5] LLM Call actively CANCELLED due to client disconnect.")
+            # Repropagate to allow parent orchestrator to catch it
+            raise
+        except Exception as e:
+            logger.error(f"Error in _call_llm generation: {e}")
+            raise
+
+        raw_text = response.text
+        logger.info(f"📦 [TRACE] RAW RESPONSE RECEIVED: {raw_text}")
+        
+        # V8.5.1: Convert UsageMetadata (Custom Class) to dict to avoid serialization error
+        usage = getattr(response, 'usage_metadata', None)
+        usage_dict = {}
+        if usage:
+            usage_dict = {
+                "prompt_token_count": getattr(usage, 'prompt_token_count', 0),
+                "candidates_token_count": getattr(usage, 'candidates_token_count', 0),
+                "total_token_count": getattr(usage, 'total_token_count', 0)
+            }
+            
+        parsed = self._parse_v4_json(raw_text)
+        return {**parsed, "usage_metadata": usage_dict}
+
+    def _parse_v4_json(self, raw_text):
+        # V4.7 → V1.0: Use canonical safe_extract_json (logs RAW, LaTeX shield, json_repair, fail-closed)
+        if "{" not in raw_text and "[" not in raw_text:
+            return {"solution_markdown": "שגיאת מבנה", "is_valid": False, "confidence_score": 0.1}
+        result = safe_extract_json(raw_text, caller="STRATEGY_MANAGER")
+        if isinstance(result, dict) and result.get("logic_error"):
+            return {"solution_markdown": "המורה נכשלה בפירוש הפתרון", "is_valid": False, "confidence_score": 0.1}
+        return result
+
+    def _validate(self, topic_id, llm_response, data_anchor): return {"valid": True, "error": None}
+
+    async def generate_raw(self, system_prompt: str, user_prompt: str) -> str:
+        """
+        V6.1: Direct raw LLM call for ProposalEngine. Unconstrained output.
+        """
+        from google.generativeai.types import GenerationConfig
+        import asyncio
+        
+        full_prompt = f"{system_prompt}\n\nUser Request: {user_prompt}"
+        
+        gen_config = GenerationConfig(
+            temperature=0.2, # Slight creativity needed to draft proofs, but still grounded
+            top_p=0.8,
+        )
+        
+        logger.info(f"🧠 [PROPOSAL-GATEWAY] Sending PROMPT to LLM.")
+        try:
+            response = await asyncio.wait_for(
+                asyncio.to_thread(self.llm.generate_content, full_prompt, generation_config=gen_config),
+                timeout=45.0
+            )
+            return getattr(response, 'text', '')
+        except Exception as e:
+            logger.error(f"❌ [PROPOSAL-GATEWAY] LLM Request failed: {e}")
+            raise e