Update app.py

app.py

@@ -9,35 +9,26 @@ import struct
 import logging
 import uuid
 import sys
+import time
 
 # ── CRITICAL: eventlet monkey_patch BEFORE all other imports ──────────────────
-# Azure Speech SDK uses native C++ threads internally. If eventlet patches
-# Python threading AFTER the SDK is already loaded, the SDK's recognize_once_async()
-# silently returns ResultReason.Canceled + CancellationReason.Error with no
-# useful error_details — even with valid credentials and good audio.
-#
-# Fix: call monkey_patch() here at the very top, then run all Azure SDK calls
-# inside a real OS thread via concurrent.futures.ThreadPoolExecutor, which
-# is not subject to eventlet's cooperative scheduling.
 import eventlet
 eventlet.monkey_patch()
 
 import concurrent.futures
-_azure_executor = concurrent.futures.ThreadPoolExecutor(max_workers=4)
+
+_azure_executor  = concurrent.futures.ThreadPoolExecutor(max_workers=4)
+_gemini_executor = concurrent.futures.ThreadPoolExecutor(max_workers=4)
 
 import cv2
 import numpy as np
 from flask import Flask
 from flask_socketio import SocketIO, emit
-
 from PIL import Image
-
-# --- 2025 AI STANDARDS ---
 from google import genai
 from google.genai import types
 import azure.cognitiveservices.speech as speechsdk
 
-# --- KLP Modules ---
 from korean_rules import rule_engine
 from content_pack import get_active_pack, replace_active_pack
 from learner_model import get_or_create_session, get_session, delete_session, purge_stale_sessions
@@ -45,23 +36,17 @@ from question_generator import QuestionGenerator, QTYPE_TO_RULE
 
 sys.path.append(os.path.dirname(__file__))
 
-
-# --- LOGGING SETUP ---
-logging.basicConfig(
-    level=logging.INFO,
-    format='%(asctime)s - %(levelname)s - %(message)s'
-)
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
 logger = logging.getLogger(__name__)
 
-app = Flask(__name__)
+app      = Flask(__name__)
 socketio = SocketIO(app, cors_allowed_origins="*", async_mode='eventlet')
 
-# --- SECRETS ---
-GEMINI_API_KEY = os.environ.get("GEMINI_API_KEY")
-AZURE_SPEECH_KEY = os.environ.get("AZURE_SPEECH_KEY")
+GEMINI_API_KEY      = os.environ.get("GEMINI_API_KEY")
+AZURE_SPEECH_KEY    = os.environ.get("AZURE_SPEECH_KEY")
 AZURE_SPEECH_REGION = os.environ.get("AZURE_SPEECH_REGION")
+GEMINI_MODEL        = "gemini-2.5-flash-lite"
 
-# --- Initialize Gemini Client ---
 client = None
 try:
     client = genai.Client(api_key=GEMINI_API_KEY)
@@ -69,24 +54,48 @@ try:
 except Exception as e:
     logger.error(f"❌ Failed to init Gemini: {e}")
 
-# --- Initialize Question Generator ---
-question_gen = QuestionGenerator(gemini_client=client)
+_speech_config = None
+
+def _build_speech_config():
+    if not AZURE_SPEECH_KEY or not AZURE_SPEECH_REGION:
+        return None
+    cfg = speechsdk.SpeechConfig(subscription=AZURE_SPEECH_KEY, region=AZURE_SPEECH_REGION)
+    cfg.speech_recognition_language = "ko-KR"
+    return cfg
 
-# --- Session ID → socket SID mapping ---
-_socket_to_learner: dict[str, str] = {}
+try:
+    _speech_config = _build_speech_config()
+    if _speech_config:
+        logger.info(f"✅ Azure SpeechConfig pre-built (region={AZURE_SPEECH_REGION})")
+    else:
+        logger.warning("⚠️  Azure SpeechConfig not built — credentials missing")
+except Exception as e:
+    logger.error(f"❌ Azure SpeechConfig init failed: {e}")
 
+question_gen        = QuestionGenerator(gemini_client=client)
+_socket_to_learner  = {}
+_question_cache     = {}
+
+
+def _prefetch_question(learner_id, grammar_rule, difficulty, history, session_id):
+    def _gen():
+        try:
+            return question_gen.generate(difficulty=difficulty, grammar_rule=grammar_rule,
+                                         history=history, session_id=session_id)
+        except Exception as e:
+            logger.warning(f"⚡ Prefetch failed: {e}")
+            return None
+    _question_cache[learner_id] = _gemini_executor.submit(_gen)
+    logger.info(f"⚡ Prefetch queued: rule={grammar_rule} diff={difficulty}")
 
-# ===========================================================================
-# HELPERS
-# ===========================================================================
 
 def decode_image(base64_string):
     try:
         if "," in base64_string:
             base64_string = base64_string.split(",")[1]
         img_bytes = base64.b64decode(base64_string)
-        np_arr = np.frombuffer(img_bytes, np.uint8)
-        frame = cv2.imdecode(np_arr, cv2.IMREAD_COLOR)
+        np_arr    = np.frombuffer(img_bytes, np.uint8)
+        frame     = cv2.imdecode(np_arr, cv2.IMREAD_COLOR)
         return Image.fromarray(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB))
     except Exception as e:
         logger.error(f"Image Decode Error: {e}")
@@ -94,136 +103,85 @@ def decode_image(base64_string):
 
 
 def sanitize_audio(input_path):
-    """Force audio into Azure-compliant format: 16kHz, Mono, 16-bit PCM WAV."""
-    output_path = input_path + "_clean.wav"
-
-    # --- Log input file info before conversion ---
     try:
         input_size = os.path.getsize(input_path)
-        logger.info(f"🔧 [FFmpeg] Input file: {input_path} | Size: {input_size} bytes")
-        if input_size == 0:
-            logger.error("❌ [FFmpeg] Input file is EMPTY (0 bytes) — audio was not captured correctly")
-            return None
-    except Exception as e:
-        logger.error(f"❌ [FFmpeg] Could not stat input file: {e}")
-
-    command = [
-        "ffmpeg", "-y", "-v", "verbose",
-        "-i", input_path,
-        "-ac", "1",
-        "-ar", "16000",
-        "-acodec", "pcm_s16le",
-        output_path
-    ]
-
-    logger.info(f"🔧 [FFmpeg] Running: {' '.join(command)}")
+    except Exception:
+        logger.error("❌ [FFmpeg] Cannot stat input file")
+        return None
+    if input_size == 0:
+        logger.error("❌ [FFmpeg] Input file is empty")
+        return None
 
+    output_path = input_path + "_clean.wav"
+    command = ["ffmpeg", "-y", "-v", "error", "-i", input_path,
+                "-ac", "1", "-ar", "16000", "-acodec", "pcm_s16le", output_path]
     try:
         result = subprocess.run(command, check=True, capture_output=True, text=True)
-        logger.info(f"✅ [FFmpeg] Conversion successful → {output_path}")
-        if result.stderr:
-            logger.info(f"🔧 [FFmpeg] stderr:\n{result.stderr[:2000]}")
-
         output_size = os.path.getsize(output_path)
-        logger.info(f"🔧 [FFmpeg] Output WAV size: {output_size} bytes")
         if output_size == 0:
-            logger.error("❌ [FFmpeg] Output WAV is EMPTY — conversion produced no data")
+            logger.error("❌ [FFmpeg] Output WAV is empty")
             return None
-
+        logger.info(f"✅ [FFmpeg] {input_size}B → {output_size}B WAV")
+        if result.stderr:
+            logger.warning(f"[FFmpeg] stderr: {result.stderr[:500]}")
         return output_path
-
     except subprocess.CalledProcessError as e:
-        logger.error(f"❌ [FFmpeg] Process failed (returncode={e.returncode})")
-        logger.error(f"❌ [FFmpeg] stdout: {e.stdout}")
-        logger.error(f"❌ [FFmpeg] stderr: {e.stderr}")
+        logger.error(f"❌ [FFmpeg] Failed (rc={e.returncode}): {e.stderr[:500]}")
         return None
     except FileNotFoundError:
-        logger.error("❌ [FFmpeg] ffmpeg binary not found — is it installed in the Docker image?")
+        logger.error("❌ [FFmpeg] ffmpeg not found")
         return None
     except Exception as e:
-        logger.error(f"❌ [FFmpeg] Unexpected error: {e}")
+        logger.error(f"❌ [FFmpeg] Unexpected: {e}")
         return None
 
 
-def analyze_audio_volume(file_path):
-    """Inspect WAV: log framerate, channels, duration, peak amplitude."""
+def quick_audio_check(file_path):
     try:
         with wave.open(file_path, 'rb') as wf:
             framerate  = wf.getframerate()
             nframes    = wf.getnframes()
-            channels   = wf.getnchannels()
-            sampwidth  = wf.getsampwidth()
             duration_s = nframes / framerate if framerate else 0
-
-            logger.info(
-                f"🔊 [WAV] framerate={framerate}Hz | channels={channels} | "
-                f"sampwidth={sampwidth}B | nframes={nframes} | duration={duration_s:.2f}s"
-            )
-
+            logger.info(f"🔊 [WAV] {framerate}Hz | {duration_s:.2f}s | {nframes} frames")
             if duration_s < 0.2:
-                logger.warning(f"⚠️  [WAV] Very short audio ({duration_s:.2f}s) — may not be enough for recognition")
-
-            raw_data = wf.readframes(nframes)
-            if len(raw_data) == 0:
-                logger.error("❌ [WAV] No PCM data in file")
-                return False
-
-            fmt = "%dh" % (len(raw_data) // 2)
-            pcm_data = struct.unpack(fmt, raw_data)
-
-            if not pcm_data:
-                logger.error("❌ [WAV] PCM unpack produced no samples")
+                logger.warning(f"⚠️  [WAV] Very short ({duration_s:.2f}s)")
+            sample_frames = min(4096, nframes)
+            raw_sample    = wf.readframes(sample_frames)
+            if not raw_sample:
                 return False
-
-            max_val = max(abs(x) for x in pcm_data)
-            avg_val = sum(abs(x) for x in pcm_data) / len(pcm_data)
-            logger.info(f"🔊 [WAV] Peak amplitude: {max_val}/32767 | Avg: {avg_val:.1f}")
-
-            if max_val < 100:
-                logger.warning("⚠️  [WAV] Audio appears SILENT (peak < 100) — microphone may not be working")
+            samples = struct.unpack("%dh" % (len(raw_sample) // 2), raw_sample)
+            peak    = max(abs(x) for x in samples)
+            logger.info(f"🔊 [WAV] Sample peak: {peak}/32767")
+            if peak < 100:
+                logger.warning("⚠️  [WAV] Audio appears silent")
                 return False
-            if max_val < 500:
-                logger.warning(f"⚠️  [WAV] Audio is very quiet (peak={max_val}) — may affect recognition accuracy")
-
             return True
-
-    except wave.Error as e:
-        logger.error(f"❌ [WAV] wave.Error: {e} — file may not be a valid WAV")
-        return False
     except Exception as e:
-        logger.warning(f"⚠️  [WAV] Could not analyze audio: {e}")
-        return True  # Don't block on analysis failure
+        logger.warning(f"⚠️  [WAV] Check skipped: {e}")
+        return True
 
 
-def get_learner(socket_sid: str):
-    """Get learner model for the current socket connection."""
+def get_learner(socket_sid):
     learner_id = _socket_to_learner.get(socket_sid)
     if learner_id:
         return get_session(learner_id)
     return None
 
 
-# ===========================================================================
-# CONNECTION HANDLERS
-# ===========================================================================
-
 @socketio.on('connect')
 def handle_connect():
     from flask import request
-    sid = request.sid
+    sid        = request.sid
     learner_id = str(uuid.uuid4())
     _socket_to_learner[sid] = learner_id
     model = get_or_create_session(learner_id)
     logger.info(f"✅ Client connected: socket={sid} learner={learner_id}")
-
     emit('session_ready', {
-        "session_id": learner_id,
-        "message": "Connected to KLP AI Service",
-        "mastery": model.mastery,
-        "difficulty": model.difficulty,
+        "session_id": learner_id, "message": "Connected to KLP AI Service",
+        "mastery": model.mastery, "difficulty": model.difficulty,
         "content_pack": {
-            "lesson": get_active_pack().get("lesson"),
-            "version": get_active_pack().get("version"),
+            "lesson":      get_active_pack().get("lesson"),
+            "version":     get_active_pack().get("version"),
             "vocab_count": len(get_active_pack().get("vocab", [])),
         }
     })
@@ -232,120 +190,73 @@ def handle_connect():
 @socketio.on('disconnect')
 def handle_disconnect():
     from flask import request
-    sid = request.sid
+    sid        = request.sid
     learner_id = _socket_to_learner.pop(sid, None)
     if learner_id:
+        _question_cache.pop(learner_id, None)
         logger.info(f"Client disconnected: socket={sid} learner={learner_id}")
     else:
         logger.info(f"Client disconnected: socket={sid}")
 
 
-# ===========================================================================
-# 1. CONTENT PACK LOADER
-# ===========================================================================
-
 @socketio.on('load_content_pack')
 def handle_load_content_pack(data):
     logger.info("📦 Content pack upload received")
-
     try:
         file_type   = data.get("file_type", "json").lower()
         file_b64    = data.get("file_bytes", "")
         lesson      = data.get("lesson", "custom")
         description = data.get("description", "Custom content pack")
-
         if "," in file_b64:
             file_b64 = file_b64.split(",")[1]
         file_bytes = base64.b64decode(file_b64)
 
         if file_type == "json":
-            raw = json.loads(file_bytes.decode("utf-8"))
-            new_pack = replace_active_pack({
-                **raw,
-                "lesson": lesson,
-                "description": description,
-            })
+            raw      = json.loads(file_bytes.decode("utf-8"))
+            new_pack = replace_active_pack({**raw, "lesson": lesson, "description": description})
             emit('content_pack_loaded', {
-                "success": True,
-                "lesson": new_pack["lesson"],
+                "success": True, "lesson": new_pack["lesson"],
                 "vocab_count": len(new_pack["vocab"]),
-                "grammar_rules": list(new_pack["grammar_rules"].keys()),
-                "source": "json_upload",
+                "grammar_rules": list(new_pack["grammar_rules"].keys()), "source": "json_upload",
             })
-
         elif file_type in ("docx", "pdf"):
             if not client:
                 emit('content_pack_loaded', {"success": False, "error": "Gemini not available"})
                 return
-
-            mime = "application/pdf" if file_type == "pdf" else \
-                   "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
-
-            parse_prompt = """You are parsing a Korean language teaching document.
-Extract all vocabulary items and grammar rules.
-
-Return ONLY valid JSON in this exact structure:
-{
-  "vocab": [
-    {"korean": "학생", "english": "student", "type": "noun"}
-  ],
-  "grammar_rules": {
-    "rule_id": {
-      "id": "rule_id",
-      "name": "Rule Name",
-      "description": "What the rule does",
-      "examples": [{"sentence": "...", "translation": "..."}],
-      "difficulty": 1
-    }
-  },
-  "lesson": "lesson name/number",
-  "description": "brief description"
-}
-
-Types for vocab: noun, verb, adjective, pronoun, adverb, expression
-Grammar rule IDs should be snake_case."""
-
+            mime = ("application/pdf" if file_type == "pdf"
+                    else "application/vnd.openxmlformats-officedocument.wordprocessingml.document")
+            parse_prompt = ('You are parsing a Korean language teaching document. '
+                            'Return ONLY valid JSON: {"vocab": [{"korean":"...","english":"...","type":"noun"}], '
+                            '"grammar_rules": {"rule_id": {"id":"...","name":"...","description":"...",'
+                            '"examples":[{"sentence":"...","translation":"..."}],"difficulty":1}}, '
+                            '"lesson": "...", "description": "..."}')
             response = client.models.generate_content(
-                model="gemini-2.5-flash",
-                contents=[
-                    parse_prompt,
-                    types.Part.from_bytes(data=file_bytes, mime_type=mime)
-                ],
+                model=GEMINI_MODEL,
+                contents=[parse_prompt, types.Part.from_bytes(data=file_bytes, mime_type=mime)],
             )
-
             text = response.text.strip()
             if "```" in text:
                 text = text.split("```")[1]
                 if text.startswith("json"):
                     text = text[4:]
-
-            parsed = json.loads(text.strip())
-            new_pack = replace_active_pack(parsed)
-
+            new_pack = replace_active_pack(json.loads(text.strip()))
             emit('content_pack_loaded', {
-                "success": True,
-                "lesson": new_pack["lesson"],
+                "success": True, "lesson": new_pack["lesson"],
                 "vocab_count": len(new_pack["vocab"]),
-                "grammar_rules": list(new_pack["grammar_rules"].keys()),
-                "source": "gemini_parsed",
+                "grammar_rules": list(new_pack["grammar_rules"].keys()), "source": "gemini_parsed",
             })
-
         else:
-            emit('content_pack_loaded', {"success": False, "error": f"Unsupported file type: {file_type}"})
-
+            emit('content_pack_loaded', {"success": False, "error": f"Unsupported: {file_type}"})
     except Exception as e:
         logger.error(f"Content pack load error: {e}")
         emit('content_pack_loaded', {"success": False, "error": str(e)})
 
 
-# ===========================================================================
-# 2. QUESTION GENERATION
-# ===========================================================================
-
 @socketio.on('request_question')
 def handle_request_question(data):
     from flask import request as req
-    sid = req.sid
+    t0      = time.monotonic()
+    sid     = req.sid
     learner = get_learner(sid)
 
     if not learner:
@@ -354,19 +265,30 @@ def handle_request_question(data):
 
     try:
         forced_rule         = data.get("grammar_rule") if data else None
-        override_difficulty = data.get("difficulty") if data else None
+        override_difficulty = data.get("difficulty")   if data else None
         difficulty          = override_difficulty or learner.difficulty
         grammar_rule        = forced_rule or learner.get_recommended_rule()
+        learner_id          = _socket_to_learner.get(sid)
 
-        logger.info(f"🎯 Generating question: rule={grammar_rule} difficulty={difficulty} session={learner.session_id}")
+        cached_future = _question_cache.pop(learner_id, None) if learner_id else None
+        if cached_future is not None:
+            try:
+                payload = cached_future.result(timeout=6)
+                if payload:
+                    logger.info(f"⚡ Cache HIT — {(time.monotonic()-t0)*1000:.0f}ms")
+                    emit('question_payload', payload)
+                    return
+            except concurrent.futures.TimeoutError:
+                logger.warning("⚡ Cache future timed out — live generation")
+            except Exception as e:
+                logger.warning(f"⚡ Cache future errored: {e} — live generation")
 
+        logger.info(f"🎯 Generating: rule={grammar_rule} diff={difficulty}")
         payload = question_gen.generate(
-            difficulty=difficulty,
-            grammar_rule=grammar_rule,
-            history=learner.history,
-            session_id=learner.session_id,
+            difficulty=difficulty, grammar_rule=grammar_rule,
+            history=learner.history, session_id=learner.session_id,
         )
-
+        logger.info(f"🎯 Generated in {(time.monotonic()-t0)*1000:.0f}ms")
         emit('question_payload', payload)
 
     except Exception as e:
@@ -374,10 +296,6 @@ def handle_request_question(data):
         emit('question_payload', {"error": "Could not generate question. Please try again."})
 
 
-# ===========================================================================
-# 3. ANSWER VALIDATION
-# ===========================================================================
-
 @socketio.on('submit_answer')
 def handle_submit_answer(data):
     from flask import request as req
@@ -391,18 +309,13 @@ def handle_submit_answer(data):
 
     try:
         correct = False
-
         if interaction_mode == "assemble":
-            submitted = data.get("token_order", [])
-            expected  = data.get("correct_order", [])
-            correct   = rule_engine.validate_token_order(submitted, expected)
-
+            correct = rule_engine.validate_token_order(data.get("token_order", []), data.get("correct_order", []))
         elif interaction_mode in ("choose_select", "fill_in"):
             chosen        = str(data.get("answer", "")).strip()
             answer_key    = str(data.get("answer_key", "")).strip()
             word_tested   = data.get("word_tested")
             particle_type = data.get("particle_type")
-
             if word_tested and particle_type:
                 correct = rule_engine.validate_particle_choice(word_tested, chosen, particle_type)
             else:
@@ -420,13 +333,8 @@ def handle_submit_answer(data):
         if not correct:
             word  = data.get("word_tested")
             ptype = data.get("particle_type")
-            if word and ptype:
-                hint = rule_engine.get_hint(word, ptype)
-            else:
-                hint = data.get("hint_text", "Review the grammar rule and try again")
-
-        retry_allowed         = not correct and attempt < 3
-        speech_stage_unlocked = correct
+            hint  = (rule_engine.get_hint(word, ptype) if (word and ptype)
+                     else data.get("hint_text", "Review the grammar rule and try again"))
 
         response = {
             "question_id":           data.get("question_id"),
@@ -434,83 +342,70 @@ def handle_submit_answer(data):
             "score_delta":           10 if correct else 0,
             "feedback":              _build_feedback(correct, q_type, grammar_rule),
             "hint":                  hint,
-            "retry_allowed":         retry_allowed,
+            "retry_allowed":         not correct and attempt < 3,
             "attempt_number":        attempt,
-            "speech_stage_unlocked": speech_stage_unlocked,
+            "speech_stage_unlocked": correct,
         }
-
         if learner:
             response["mastery_update"] = dict(learner.mastery)
             response["streak"]         = learner.streak
 
         emit('answer_result', response)
 
+        if correct and learner:
+            learner_id = _socket_to_learner.get(sid)
+            if learner_id:
+                _prefetch_question(
+                    learner_id=learner_id,
+                    grammar_rule=learner.get_recommended_rule(),
+                    difficulty=learner.difficulty,
+                    history=list(learner.history),
+                    session_id=learner.session_id,
+                )
+
     except Exception as e:
         logger.error(f"Answer validation error: {e}")
-        emit('answer_result', {
-            "correct": False,
-            "score_delta": 0,
-            "feedback": "Server error during validation",
-            "retry_allowed": True,
-        })
+        emit('answer_result', {"correct": False, "score_delta": 0,
+                                "feedback": "Server error during validation", "retry_allowed": True})
 
 
-def _gemini_recheck(data: dict) -> bool:
+def _gemini_recheck(data):
     try:
-        prompt = f"""You are a Korean language grammar validator.
-
-Direct speech: {data.get('direct_speech', '')}
-Student's indirect speech: {data.get('answer', '')}
-Expected indirect speech: {data.get('answer_key', '')}
-
-Is the student's answer grammatically correct as an indirect quotation?
-Consider: minor spacing differences are OK, but wrong particles or wrong verb endings are not.
-
-Reply with ONLY valid JSON: {{"correct": true}} or {{"correct": false, "reason": "explanation"}}"""
-
-        response = client.models.generate_content(
-            model="gemini-2.5-flash",
-            contents=prompt,
-        )
-        result = json.loads(response.text.strip())
-        return result.get("correct", False)
+        prompt = (f"You are a Korean grammar validator.\n"
+                  f"Direct speech: {data.get('direct_speech','')}\n"
+                  f"Student answer: {data.get('answer','')}\n"
+                  f"Expected: {data.get('answer_key','')}\n"
+                  f"Is the student correct as indirect quotation? Minor spacing OK, wrong particles/endings not.\n"
+                  f'Reply ONLY: {{"correct": true}} or {{"correct": false, "reason": "..."}}')
+        response = client.models.generate_content(model=GEMINI_MODEL, contents=prompt)
+        return json.loads(response.text.strip()).get("correct", False)
     except Exception as e:
         logger.warning(f"Gemini recheck failed: {e}")
         return False
 
 
-def _build_feedback(correct: bool, q_type: str, grammar_rule: str) -> str:
+def _build_feedback(correct, q_type, grammar_rule):
     if correct:
-        messages = [
-            "정확해요! Great job! 🎉",
-            "맞아요! That's correct! ⭐",
-            "완벽해요! Perfect! 🌟",
-            "잘했어요! Well done! 👏",
-        ]
         import random
-        return random.choice(messages)
-    else:
-        rule_hints = {
-            "topic_marker":               "Remember: 은 for consonant endings, 는 for vowel endings",
-            "copula":                     "Remember: 이에요 for consonant endings, 예요 for vowel endings",
-            "negative_copula":            "Remember: 이 아니에요 for consonant, 가 아니에요 for vowel/ㄹ",
-            "indirect_quote_dago":        "Review: V+는다고/ㄴ다고, Adj+다고, Past+었다고",
-            "indirect_quote_commands":    "Review: (으)라고 commands, 지 말라고 negatives",
-            "indirect_quote_questions":   "Review: V/Adj+냐고 (drop ㄹ from stem)",
-            "indirect_quote_suggestions": "Review: V+자고 for suggestions",
-            "regret_expression":          "Review: (으)ㄹ 걸 그랬다 = should have; 지 말 걸 = shouldn't have",
-        }
-        base = "다시 해 보세요! Let's try again. "
-        return base + rule_hints.get(grammar_rule, "Review the grammar rule.")
-
+        return random.choice(["정확해요! Great job! 🎉","맞아요! That's correct! ⭐",
+                               "완벽해요! Perfect! 🌟","잘했어요! Well done! 👏"])
+    rule_hints = {
+        "topic_marker":               "Remember: 은 for consonant endings, 는 for vowel endings",
+        "copula":                     "Remember: 이에요 for consonant endings, 예요 for vowel endings",
+        "negative_copula":            "Remember: 이 아니에요 for consonant, 가 아니에요 for vowel/ㄹ",
+        "indirect_quote_dago":        "Review: V+는다고/ㄴ다고, Adj+다고, Past+었다고",
+        "indirect_quote_commands":    "Review: (으)라고 commands, 지 말라고 negatives",
+        "indirect_quote_questions":   "Review: V/Adj+냐고 (drop ㄹ from stem)",
+        "indirect_quote_suggestions": "Review: V+자고 for suggestions",
+        "regret_expression":          "Review: (으)ㄹ 걸 그랬다 = should have; 지 말 걸 = shouldn't have",
+    }
+    return "다시 해 보세요! Let's try again. " + rule_hints.get(grammar_rule, "Review the grammar rule.")
 
-# ===========================================================================
-# 4. PRONUNCIATION ASSESSMENT
-# ===========================================================================
 
 @socketio.on('assess_pronunciation')
 def handle_pronunciation(data):
     from flask import request as req
+    t0      = time.monotonic()
     sid     = req.sid
     learner = get_learner(sid)
 
@@ -518,340 +413,159 @@ def handle_pronunciation(data):
     lang         = data.get('lang', 'ko-KR')
     grammar_rule = data.get('grammar_rule', '')
 
-    # ── STEP 1: Validate incoming payload ───────────────────────────────────
-    logger.info("=" * 60)
-    logger.info("🎤 [PRON] ── Pronunciation Assessment Start ──")
-    logger.info(f"🎤 [PRON] ref_text='{ref_text}' | lang='{lang}' | grammar_rule='{grammar_rule}'")
+    logger.info("=" * 56)
+    logger.info(f"🎤 [PRON] Start | text='{ref_text}' lang='{lang}'")
 
-    if not ref_text:
-        logger.error("❌ [PRON] STEP 1 FAILED: No reference text in payload")
+    def _fail(msg):
         emit('pronunciation_result', {
             "success": False, "score": 0, "fluency": 0, "completeness": 0,
-            "recognized_text": "", "word_details": [],
-            "feedback": "No reference text provided.",
+            "recognized_text": "", "word_details": [], "feedback": msg,
         })
-        return
+
+    if not ref_text:
+        return _fail("No reference text provided.")
 
     audio_b64 = data.get('audio', '')
     if not audio_b64:
-        logger.error("❌ [PRON] STEP 1 FAILED: No audio data in payload")
-        emit('pronunciation_result', {
-            "success": False, "score": 0, "fluency": 0, "completeness": 0,
-            "recognized_text": "", "word_details": [],
-            "feedback": "No audio data received.",
-        })
-        return
+        return _fail("No audio data received.")
 
-    logger.info(f"🎤 [PRON] STEP 1 OK: audio_b64 length={len(audio_b64)} chars")
-
-    # ── STEP 2: Validate Azure credentials ──────────────────────────────────
-    logger.info("🎤 [PRON] STEP 2: Checking Azure credentials...")
-    logger.info(f"🎤 [PRON] AZURE_SPEECH_KEY present={bool(AZURE_SPEECH_KEY)} | length={len(AZURE_SPEECH_KEY) if AZURE_SPEECH_KEY else 0}")
-    logger.info(f"🎤 [PRON] AZURE_SPEECH_REGION='{AZURE_SPEECH_REGION}'")
-
-    if not AZURE_SPEECH_KEY:
-        logger.error("❌ [PRON] STEP 2 FAILED: AZURE_SPEECH_KEY env var not set")
-        emit('pronunciation_result', {
-            "success": False, "score": 0, "fluency": 0, "completeness": 0,
-            "recognized_text": "", "word_details": [],
-            "feedback": "Azure Speech key not configured on server.",
-        })
-        return
-
-    if not AZURE_SPEECH_REGION:
-        logger.error("❌ [PRON] STEP 2 FAILED: AZURE_SPEECH_REGION env var not set")
-        emit('pronunciation_result', {
-            "success": False, "score": 0, "fluency": 0, "completeness": 0,
-            "recognized_text": "", "word_details": [],
-            "feedback": "Azure Speech region not configured on server.",
-        })
-        return
-
-    logger.info("🎤 [PRON] STEP 2 OK: Azure credentials present")
-
-    raw_path   = None
-    clean_path = None
+    if not AZURE_SPEECH_KEY or not AZURE_SPEECH_REGION:
+        logger.error("❌ [PRON] Azure credentials missing")
+        return _fail("Azure Speech not configured on server.")
 
+    raw_path = clean_path = None
     try:
-        # ── STEP 3: Decode base64 ────────────────────────────────────────────
-        logger.info("🎤 [PRON] STEP 3: Decoding base64 audio...")
-        try:
-            if "," in audio_b64:
-                header, audio_b64 = audio_b64.split(",", 1)
-                logger.info(f"🎤 [PRON] Stripped data URI header: '{header[:60]}'")
-            audio_bytes = base64.b64decode(audio_b64)
-            logger.info(f"🎤 [PRON] STEP 3 OK: Decoded {len(audio_bytes)} bytes")
-        except Exception as e:
-            logger.error(f"❌ [PRON] STEP 3 FAILED: base64 decode error: {e}")
-            raise
-
+        if "," in audio_b64:
+            _, audio_b64 = audio_b64.split(",", 1)
+        audio_bytes = base64.b64decode(audio_b64)
+        logger.info(f"🎤 [PRON] Payload: {len(audio_bytes)} bytes")
         if len(audio_bytes) < 100:
-            logger.error(f"❌ [PRON] STEP 3: Audio too small ({len(audio_bytes)} bytes) — likely not real audio")
-            raise Exception(f"Audio payload too small: {len(audio_bytes)} bytes")
-
-        # ── STEP 4: Write temp file ──────────────────────────────────────────
-        logger.info("🎤 [PRON] STEP 4: Writing to temp file...")
-        with tempfile.NamedTemporaryFile(suffix=".webm", delete=False) as temp_raw:
-            temp_raw.write(audio_bytes)
-            raw_path = temp_raw.name
-        logger.info(f"🎤 [PRON] STEP 4 OK: Wrote {os.path.getsize(raw_path)} bytes → {raw_path}")
-
-        # ── STEP 5: FFmpeg conversion ────────────────────────────────────────
-        logger.info("🎤 [PRON] STEP 5: FFmpeg → 16kHz mono PCM WAV...")
+            raise Exception(f"Audio too small: {len(audio_bytes)} bytes")
+
+        with tempfile.NamedTemporaryFile(suffix=".webm", delete=False) as f:
+            f.write(audio_bytes)
+            raw_path = f.name
+
+        t_ffmpeg = time.monotonic()
         clean_path = sanitize_audio(raw_path)
+        logger.info(f"🎤 [PRON] FFmpeg: {(time.monotonic()-t_ffmpeg)*1000:.0f}ms")
         if not clean_path:
-            logger.error("❌ [PRON] STEP 5 FAILED: sanitize_audio() returned None")
-            raise Exception("Audio conversion failed (FFmpeg error — see logs above)")
-        logger.info(f"🎤 [PRON] STEP 5 OK: clean WAV at {clean_path}")
-
-        # ── STEP 6: WAV integrity check ──────────────────────────────────────
-        logger.info("🎤 [PRON] STEP 6: WAV integrity + volume check...")
-        audio_ok = analyze_audio_volume(clean_path)
-        if not audio_ok:
-            logger.warning("⚠️  [PRON] STEP 6: Audio silent — Azure will likely return NoMatch")
-        else:
-            logger.info("🎤 [PRON] STEP 6 OK: Audible signal confirmed")
-
-        # ── STEP 7: Build Azure SpeechConfig ────────────────────────────────
-        logger.info(f"🎤 [PRON] STEP 7: Building SpeechConfig (region={AZURE_SPEECH_REGION}, lang={lang})...")
-        try:
-            speech_config = speechsdk.SpeechConfig(
-                subscription=AZURE_SPEECH_KEY,
-                region=AZURE_SPEECH_REGION
-            )
-            speech_config.speech_recognition_language = lang
-            logger.info("🎤 [PRON] STEP 7 OK: SpeechConfig built")
-        except Exception as e:
-            logger.error(f"❌ [PRON] STEP 7 FAILED: SpeechConfig error: {e}")
-            raise
+            raise Exception("Audio conversion failed")
+
+        quick_audio_check(clean_path)
+
+        speech_cfg = _speech_config or _build_speech_config()
+        if not speech_cfg:
+            raise Exception("Azure SpeechConfig unavailable — check HF Space secrets")
+        if lang != "ko-KR":
+            speech_cfg.speech_recognition_language = lang
+
+        audio_config = speechsdk.audio.AudioConfig(filename=clean_path)
+        pron_config  = speechsdk.PronunciationAssessmentConfig(
+            reference_text=ref_text,
+            grading_system=speechsdk.PronunciationAssessmentGradingSystem.HundredMark,
+            granularity=speechsdk.PronunciationAssessmentGranularity.Word,
+            enable_miscue=True
+        )
+        recognizer = speechsdk.SpeechRecognizer(speech_config=speech_cfg, audio_config=audio_config)
+        pron_config.apply_to(recognizer)
 
-        # ��─ STEP 8: Build AudioConfig ────────────────────────────────────────
-        logger.info(f"🎤 [PRON] STEP 8: Building AudioConfig from {clean_path}...")
-        try:
-            audio_config = speechsdk.audio.AudioConfig(filename=clean_path)
-            logger.info("🎤 [PRON] STEP 8 OK: AudioConfig built")
-        except Exception as e:
-            logger.error(f"❌ [PRON] STEP 8 FAILED: AudioConfig error: {e}")
-            raise
+        t_azure = time.monotonic()
+        logger.info("🎤 [PRON] Submitting to Azure OS thread...")
 
-        # ── STEP 9: Build PronunciationAssessmentConfig ──────────────────────
-        logger.info(f"🎤 [PRON] STEP 9: PronunciationAssessmentConfig for '{ref_text}'...")
-        try:
-            pronunciation_config = speechsdk.PronunciationAssessmentConfig(
-                reference_text=ref_text,
-                grading_system=speechsdk.PronunciationAssessmentGradingSystem.HundredMark,
-                granularity=speechsdk.PronunciationAssessmentGranularity.Word,
-                enable_miscue=True
-            )
-            logger.info("🎤 [PRON] STEP 9 OK: PronunciationAssessmentConfig built")
-        except Exception as e:
-            logger.error(f"❌ [PRON] STEP 9 FAILED: PronunciationAssessmentConfig error: {e}")
-            raise
+        def _run_azure():
+            return recognizer.recognize_once_async().get()
 
-        # ── STEP 10: Build SpeechRecognizer ─────────────────────────────────
-        logger.info("🎤 [PRON] STEP 10: Building SpeechRecognizer...")
         try:
-            recognizer = speechsdk.SpeechRecognizer(
-                speech_config=speech_config,
-                audio_config=audio_config
-            )
-            pronunciation_config.apply_to(recognizer)
-            logger.info("🎤 [PRON] STEP 10 OK: SpeechRecognizer ready")
-        except Exception as e:
-            logger.error(f"❌ [PRON] STEP 10 FAILED: SpeechRecognizer error: {e}")
-            raise
-
-        # ── STEP 11: Call Azure in a REAL OS thread ──────────────────────────
-        # recognize_once_async() uses native C++ threads internally.
-        # Calling it directly in an eventlet greenthread causes silent Canceled
-        # errors because eventlet has patched socket/ssl/threading under the SDK.
-        # _azure_executor is a real ThreadPoolExecutor — unpatched OS threads.
-        logger.info("🎤 [PRON] STEP 11: Submitting to real OS thread (bypassing eventlet)...")
-        try:
-            def _run_azure():
-                return recognizer.recognize_once_async().get()
-
-            future = _azure_executor.submit(_run_azure)
-            result = future.result(timeout=30)
-            logger.info("🎤 [PRON] STEP 11 OK: Azure responded from real OS thread")
-            logger.info(f"🎤 [PRON] result.reason = {result.reason}")
-            logger.info(f"🎤 [PRON] result.text   = '{result.text}'")
+            result = _azure_executor.submit(_run_azure).result(timeout=30)
         except concurrent.futures.TimeoutError:
-            logger.error("❌ [PRON] STEP 11 FAILED: Azure timed out after 30s")
-            raise Exception("Azure Speech timed out — check HF Space outbound network access")
-        except Exception as e:
-            logger.error(f"❌ [PRON] STEP 11 FAILED: Azure OS thread raised: {e}")
-            raise
+            raise Exception("Azure Speech timed out after 30s")
 
-        # ── STEP 12: Parse Azure result ──────────────────────────────────────
-        logger.info("🎤 [PRON] STEP 12: Parsing result...")
-        response = {}
+        logger.info(f"🎤 [PRON] Azure: {(time.monotonic()-t_azure)*1000:.0f}ms | reason={result.reason}")
 
+        response = {}
         if result.reason == speechsdk.ResultReason.RecognizedSpeech:
-            logger.info("🎤 [PRON] STEP 12: RecognizedSpeech ✅")
-            try:
-                pron_result  = speechsdk.PronunciationAssessmentResult(result)
-                accuracy     = pron_result.accuracy_score
-                fluency      = pron_result.fluency_score
-                completeness = pron_result.completeness_score
-                logger.info(f"🎤 [PRON] Scores → accuracy={accuracy:.1f} fluency={fluency:.1f} completeness={completeness:.1f}")
-            except Exception as e:
-                logger.error(f"❌ [PRON] STEP 12 FAILED: PronunciationAssessmentResult parse error: {e}")
-                raise
-
-            detailed_words = []
-            for word in pron_result.words:
-                w = {"word": word.word, "score": word.accuracy_score, "error": word.error_type}
-                detailed_words.append(w)
-                logger.info(f"🎤 [PRON] Word: '{word.word}' score={word.accuracy_score:.1f} error='{word.error_type}'")
-
-            feedback = _build_pronunciation_feedback(accuracy, fluency, completeness, detailed_words, ref_text)
-
+            pr           = speechsdk.PronunciationAssessmentResult(result)
+            accuracy     = pr.accuracy_score
+            fluency      = pr.fluency_score
+            completeness = pr.completeness_score
+            words        = [{"word": w.word, "score": w.accuracy_score, "error": w.error_type}
+                            for w in pr.words]
+            for w in words:
+                logger.info(f"🎤 [PRON] Word: '{w['word']}' score={w['score']:.1f} error='{w['error']}'")
             response = {
-                "success":         True,
-                "score":           accuracy,
-                "fluency":         fluency,
-                "completeness":    completeness,
-                "recognized_text": result.text,
-                "word_details":    detailed_words,
-                "feedback":        feedback,
-                "question_id":     data.get("question_id"),
+                "success": True, "score": accuracy, "fluency": fluency,
+                "completeness": completeness, "recognized_text": result.text,
+                "word_details": words,
+                "feedback": _build_pronunciation_feedback(accuracy, fluency, completeness, words),
+                "question_id": data.get("question_id"),
             }
-
             if learner and grammar_rule and accuracy >= 70:
                 learner.record_outcome(grammar_rule, True, "speak")
                 response["mastery_update"] = dict(learner.mastery)
-
-            logger.info(f"✅ [PRON] Complete — accuracy={accuracy:.1f}")
+            logger.info(f"✅ [PRON] acc={accuracy:.1f} flu={fluency:.1f} comp={completeness:.1f}")
 
         elif result.reason == speechsdk.ResultReason.NoMatch:
-            no_match_detail = getattr(result, 'no_match_details', 'N/A')
-            logger.warning(f"⚠️  [PRON] STEP 12: NoMatch — Azure heard nothing useful")
-            logger.warning(f"⚠️  [PRON] NoMatch details: {no_match_detail}")
-            response = {
-                "success": False, "score": 0, "fluency": 0, "completeness": 0,
-                "recognized_text": "", "word_details": [],
-                "feedback": "I couldn't hear you clearly. Check your microphone and try again.",
-            }
+            logger.warning("⚠️  [PRON] NoMatch")
+            response = {"success": False, "score": 0, "fluency": 0, "completeness": 0,
+                        "recognized_text": "", "word_details": [],
+                        "feedback": "I couldn't hear you clearly. Check your microphone and try again."}
 
         elif result.reason == speechsdk.ResultReason.Canceled:
-            logger.error("❌ [PRON] STEP 12: Result reason = Canceled")
             try:
-                cancellation = speechsdk.CancellationDetails(result)
-
-                # Use getattr for all fields — older SDK versions may be missing some
-                c_reason  = getattr(cancellation, 'reason',        'UNKNOWN')
-                c_code    = getattr(cancellation, 'error_code',    'UNKNOWN')
-                c_details = getattr(cancellation, 'error_details', 'UNKNOWN')
-
-                logger.error(f"❌ [PRON] Cancellation reason:        {c_reason}")
-                logger.error(f"❌ [PRON] Cancellation error_code:    {c_code}")
-                logger.error(f"❌ [PRON] Cancellation error_details: {c_details}")
-
-                # Dump every attribute on the object so nothing is hidden
-                logger.error(f"❌ [PRON] CancellationDetails dir(): {[a for a in dir(cancellation) if not a.startswith('_')]}")
-
-                # Also dump the raw result properties dict if available
-                raw_props = getattr(result, 'properties', None)
-                if raw_props:
-                    logger.error(f"❌ [PRON] result.properties: {dict(raw_props)}")
-
-                details_str = str(c_details or '') + str(c_code or '')
-                if "401" in details_str:
-                    logger.error("❌ [PRON] → HTTP 401: Azure key is INVALID or EXPIRED — check HF Space secrets")
-                elif "403" in details_str:
-                    logger.error("❌ [PRON] → HTTP 403: Key does not have access — wrong region or feature not enabled")
-                elif "ServiceUnavailable" in details_str or "503" in details_str:
-                    logger.error("❌ [PRON] → 503: Azure Speech service is temporarily unavailable")
-                elif "connection" in details_str.lower() or "network" in details_str.lower():
-                    logger.error("❌ [PRON] → Network error: HF Space cannot reach Azure endpoint — check outbound access")
-                elif "AuthenticationFailure" in details_str:
-                    logger.error("❌ [PRON] → AuthenticationFailure: Key/region mismatch — your key was provisioned in a different region than AZURE_SPEECH_REGION")
-                elif details_str in ('', 'UNKNOWN'):
-                    logger.error("❌ [PRON] → Empty error details: likely a key/region mismatch. Verify AZURE_SPEECH_REGION matches the region shown in Azure portal for this key")
-
-                response = {
-                    "success": False, "score": 0, "fluency": 0, "completeness": 0,
-                    "recognized_text": "", "word_details": [],
-                    "feedback": f"Azure canceled: reason={c_reason} code={c_code} details={c_details}",
-                }
-            except Exception as parse_e:
-                logger.error(f"❌ [PRON] Could not parse CancellationDetails at all: {parse_e}")
-                # Last resort — try to get anything from the raw result
-                logger.error(f"❌ [PRON] Raw result dir(): {[a for a in dir(result) if not a.startswith('_')]}")
-                response = {
-                    "success": False, "score": 0, "fluency": 0, "completeness": 0,
-                    "recognized_text": "", "word_details": [],
-                    "feedback": "Recognition was canceled by Azure — check server logs for details.",
-                }
-
+                c  = speechsdk.CancellationDetails(result)
+                ds = str(getattr(c,'error_details','')) + str(getattr(c,'error_code',''))
+                logger.error(f"❌ [PRON] Canceled: {ds}")
+                if "401" in ds:              logger.error("❌ [PRON] → Key INVALID or EXPIRED")
+                elif "403" in ds:            logger.error("❌ [PRON] → Key lacks access")
+                elif "AuthenticationFailure" in ds: logger.error("❌ [PRON] → Key/region mismatch")
+            except Exception:
+                pass
+            response = {"success": False, "score": 0, "fluency": 0, "completeness": 0,
+                        "recognized_text": "", "word_details": [],
+                        "feedback": "Recognition canceled — check server logs."}
         else:
-            logger.error(f"❌ [PRON] STEP 12: Unexpected result.reason = {result.reason}")
-            response = {
-                "success": False, "score": 0, "fluency": 0, "completeness": 0,
-                "recognized_text": "", "word_details": [],
-                "feedback": f"Unexpected recognition result: {result.reason}",
-            }
+            response = {"success": False, "score": 0, "fluency": 0, "completeness": 0,
+                        "recognized_text": "", "word_details": [],
+                        "feedback": f"Unexpected result: {result.reason}"}
 
-        logger.info("🎤 [PRON] ── Assessment End ──")
-        logger.info("=" * 60)
+        logger.info(f"🎤 [PRON] Total: {(time.monotonic()-t0)*1000:.0f}ms")
+        logger.info("=" * 56)
         emit('pronunciation_result', response)
 
     except Exception as e:
         import traceback
-        logger.error(f"❌ [PRON] UNHANDLED EXCEPTION: {type(e).__name__}: {e}")
-        logger.error(f"❌ [PRON] Traceback:\n{traceback.format_exc()}")
-        emit('pronunciation_result', {
-            "success": False, "score": 0, "fluency": 0, "completeness": 0,
-            "recognized_text": "", "word_details": [],
-            "feedback": "Server error during assessment.",
-        })
+        logger.error(f"❌ [PRON] Unhandled: {type(e).__name__}: {e}\n{traceback.format_exc()}")
+        emit('pronunciation_result', {"success": False, "score": 0, "fluency": 0, "completeness": 0,
+                                      "recognized_text": "", "word_details": [],
+                                      "feedback": "Server error during assessment."})
     finally:
-        if raw_path and os.path.exists(raw_path):
-            os.remove(raw_path)
-            logger.info(f"🧹 [PRON] Cleaned up: {raw_path}")
-        if clean_path and os.path.exists(clean_path):
-            os.remove(clean_path)
-            logger.info(f"🧹 [PRON] Cleaned up: {clean_path}")
-
-
-def _build_pronunciation_feedback(accuracy: float, fluency: float,
-                                   completeness: float, words: list,
-                                   ref_text: str) -> str:
-    issues = [w for w in words if w.get("error") not in (None, "None", "") or w.get("score", 100) < 60]
-
-    if accuracy >= 85:
-        base = "훌륭해요! Excellent pronunciation! 🌟"
-    elif accuracy >= 70:
-        base = "잘했어요! Good pronunciation! Keep practicing."
-    elif accuracy >= 50:
-        base = "괜찮아요! Not bad, but let's work on a few sounds."
-    else:
-        base = "다시 해 보세요! Let's practice this together."
-
+        for p in [raw_path, clean_path]:
+            if p and os.path.exists(p):
+                try: os.remove(p)
+                except Exception: pass
+
+
+def _build_pronunciation_feedback(accuracy, fluency, completeness, words):
+    if   accuracy >= 85: base = "훌륭해요! Excellent pronunciation! 🌟"
+    elif accuracy >= 70: base = "잘했어요! Good pronunciation! Keep practicing."
+    elif accuracy >= 50: base = "괜찮아요! Not bad, let's work on a few sounds."
+    else:                base = "다시 해 보세���! Let's practice this together."
+    issues = [w for w in words if w.get("error") not in (None,"None","") or w.get("score",100) < 60]
     if issues:
-        problem_words = [w["word"] for w in issues[:3]]
-        base += f" Pay attention to: {', '.join(problem_words)}"
-
+        base += f" Pay attention to: {', '.join(w['word'] for w in issues[:3])}"
     if fluency < 60:
-        base += " Try to speak more smoothly without pausing between words."
-
+        base += " Try to speak more smoothly without pausing."
     return base
 
 
-# ===========================================================================
-# 5. MASTERY & SESSION MANAGEMENT
-# ===========================================================================
-
 @socketio.on('get_mastery')
 def handle_get_mastery(data):
     from flask import request as req
     learner = get_learner(req.sid)
-
     if not learner:
         emit('mastery_state', {"error": "No active session"})
         return
-
     emit('mastery_state', learner.get_state())
 
 
@@ -859,25 +573,17 @@ def handle_get_mastery(data):
 def handle_restore_session(data):
     from flask import request as req
     sid = req.sid
-
     try:
         learner_id = _socket_to_learner.get(sid)
         if not learner_id:
             emit('session_restored', {"success": False, "error": "No active socket session"})
             return
-
         learner = get_or_create_session(learner_id)
         learner.set_state(data)
-        logger.info(f"♻️ Session restored for {learner_id}: difficulty={learner.difficulty}")
-
-        emit('session_restored', {
-            "success":        True,
-            "session_id":     learner_id,
-            "mastery":        learner.mastery,
-            "difficulty":     learner.difficulty,
-            "question_count": learner.question_count,
-        })
-
+        logger.info(f"♻️ Session restored: {learner_id}")
+        emit('session_restored', {"success": True, "session_id": learner_id,
+                                   "mastery": learner.mastery, "difficulty": learner.difficulty,
+                                   "question_count": learner.question_count})
     except Exception as e:
         logger.error(f"Session restore error: {e}")
         emit('session_restored', {"success": False, "error": str(e)})
@@ -888,15 +594,11 @@ def handle_reset_session(data):
     from flask import request as req
     sid     = req.sid
     learner = get_learner(sid)
-
     if learner:
         learner.reset()
+        _question_cache.pop(_socket_to_learner.get(sid), None)
         logger.info(f"🔄 Session reset: {learner.session_id}")
-        emit('session_reset', {
-            "success":    True,
-            "mastery":    learner.mastery,
-            "difficulty": learner.difficulty,
-        })
+        emit('session_reset', {"success": True, "mastery": learner.mastery, "difficulty": learner.difficulty})
     else:
         emit('session_reset', {"success": False, "error": "No active session"})
 
@@ -905,159 +607,87 @@ def handle_reset_session(data):
 def handle_update_mastery(data):
     from flask import request as req
     learner = get_learner(req.sid)
-
     if not learner:
         emit('mastery_updated', {"error": "No active session"})
         return
-
     grammar_rule = data.get("grammar_rule", "")
     correct      = data.get("correct", False)
     mode         = data.get("interaction_mode", "")
-
     if grammar_rule:
         learner.record_outcome(grammar_rule, correct, mode)
+    emit('mastery_updated', {"mastery": learner.mastery, "difficulty": learner.difficulty, "streak": learner.streak})
 
-    emit('mastery_updated', {
-        "mastery":    learner.mastery,
-        "difficulty": learner.difficulty,
-        "streak":     learner.streak,
-    })
-
-
-# ===========================================================================
-# 6. VISUAL RECOGNITION
-# ===========================================================================
 
 @socketio.on('verify_object')
 def handle_object_verification(data):
     target = data.get('target', 'magic wand')
-    logger.info(f"👁️ Vision Request: Checking for '{target}'")
-
+    logger.info(f"👁️ Vision: '{target}'")
     try:
         pil_image = decode_image(data.get('image'))
         if not pil_image:
             emit('vision_result', {"verified": False, "feedback": "Could not decode image"})
             return
-
         img_byte_arr = io.BytesIO()
         pil_image.save(img_byte_arr, format='JPEG', quality=80)
-        img_bytes = img_byte_arr.getvalue()
-
-        schema = {
-            "type": "OBJECT",
-            "properties": {
-                "verified":   {"type": "BOOLEAN"},
-                "confidence": {"type": "NUMBER"},
-                "feedback":   {"type": "STRING"}
-            },
-            "required": ["verified", "feedback"]
-        }
-
-        prompt = f"""You are the 'Eye of the Spellbook'.
-Look at this image. Is the user holding a '{target}'?
-IMPORTANT: Be lenient. If target is 'wand', accept a pen, pencil, chopstick, or stick.
-Return JSON matching the schema."""
-
+        schema = {"type":"OBJECT","properties":{"verified":{"type":"BOOLEAN"},
+                   "confidence":{"type":"NUMBER"},"feedback":{"type":"STRING"}},
+                  "required":["verified","feedback"]}
         response = client.models.generate_content(
-            model="gemini-2.5-flash",
-            contents=[prompt, types.Part.from_bytes(data=img_bytes, mime_type="image/jpeg")],
-            config=types.GenerateContentConfig(
-                response_mime_type="application/json",
-                response_schema=schema,
-                temperature=0.1
-            )
+            model=GEMINI_MODEL,
+            contents=[f"Eye of the Spellbook: is user holding '{target}'? Lenient — pen/pencil/stick OK for wand. Return JSON.",
+                      types.Part.from_bytes(data=img_byte_arr.getvalue(), mime_type="image/jpeg")],
+            config=types.GenerateContentConfig(response_mime_type="application/json",
+                                               response_schema=schema, temperature=0.1)
         )
-
-        result = json.loads(response.text)
-        logger.info(f"👁️ Vision Result: {result}")
-        emit('vision_result', result)
-
+        emit('vision_result', json.loads(response.text))
     except Exception as e:
         logger.error(f"Vision Error: {e}")
         emit('vision_result', {"verified": False, "feedback": "The magic eye is clouded (Server Error)."})
 
 
-# ===========================================================================
-# 7. HANDWRITING / OCR
-# ===========================================================================
-
 @socketio.on('verify_writing')
 def handle_writing_verification(data):
     expected = data.get('expected_word', '')
-    logger.info(f"📖 Handwriting Check: Expecting '{expected}'")
-
+    logger.info(f"📖 Handwriting: '{expected}'")
     try:
         pil_image = decode_image(data.get('image'))
         if not pil_image:
             emit('writing_result', {"correct": False, "detected_text": "Could not decode image"})
             return
-
         img_byte_arr = io.BytesIO()
         pil_image.save(img_byte_arr, format='JPEG', quality=80)
-        img_bytes = img_byte_arr.getvalue()
-
-        schema = {
-            "type": "OBJECT",
-            "properties": {
-                "correct":       {"type": "BOOLEAN"},
-                "detected_text": {"type": "STRING"},
-                "feedback":      {"type": "STRING"}
-            },
-            "required": ["correct", "detected_text"]
-        }
-
-        prompt = f"""Read the handwriting in this image.
-Does it spell '{expected}'?
-Be lenient with stroke variation but strict about the actual characters.
-Return JSON with: correct (bool), detected_text (what you read), feedback (brief comment)."""
-
+        schema = {"type":"OBJECT","properties":{"correct":{"type":"BOOLEAN"},
+                   "detected_text":{"type":"STRING"},"feedback":{"type":"STRING"}},
+                  "required":["correct","detected_text"]}
         response = client.models.generate_content(
-            model="gemini-2.5-flash",
-            contents=[prompt, types.Part.from_bytes(data=img_bytes, mime_type="image/jpeg")],
-            config=types.GenerateContentConfig(
-                response_mime_type="application/json",
-                response_schema=schema,
-            )
+            model=GEMINI_MODEL,
+            contents=[f"Read handwriting. Does it spell '{expected}'? Lenient on strokes, strict on characters. Return JSON.",
+                      types.Part.from_bytes(data=img_byte_arr.getvalue(), mime_type="image/jpeg")],
+            config=types.GenerateContentConfig(response_mime_type="application/json", response_schema=schema)
         )
-
-        result = json.loads(response.text)
-        logger.info(f"📖 Writing Result: {result}")
-        emit('writing_result', result)
-
+        emit('writing_result', json.loads(response.text))
     except Exception as e:
         logger.error(f"OCR Error: {e}")
         emit('writing_result', {"correct": False, "detected_text": "Error", "feedback": "Server error"})
 
 
-# ===========================================================================
-# 8. GRAMMAR RULE INFO
-# ===========================================================================
-
 @socketio.on('get_grammar_rules')
 def handle_get_grammar_rules(data):
     pack = get_active_pack()
-    emit('grammar_rules', {
-        "rules":  pack.get("grammar_rules", {}),
-        "lesson": pack.get("lesson"),
-    })
+    emit('grammar_rules', {"rules": pack.get("grammar_rules", {}), "lesson": pack.get("lesson")})
 
 
 @socketio.on('get_content_pack_info')
 def handle_get_content_pack_info(data):
     pack = get_active_pack()
     emit('content_pack_info', {
-        "lesson":        pack.get("lesson"),
-        "version":       pack.get("version"),
-        "vocab_count":   len(pack.get("vocab", [])),
+        "lesson": pack.get("lesson"), "version": pack.get("version"),
+        "vocab_count": len(pack.get("vocab", [])),
         "grammar_rules": list(pack.get("grammar_rules", {}).keys()),
-        "metadata":      pack.get("metadata", {}),
+        "metadata": pack.get("metadata", {}),
     })
 
 
-# ===========================================================================
-# ENTRY POINT
-# ===========================================================================
-
 if __name__ == '__main__':
     purge_stale_sessions()
     logger.info("🚀 KLP AI Service starting on port 7860")