Update app.py

app.py

@@ -30,7 +30,9 @@ from google.genai import types
 import azure.cognitiveservices.speech as speechsdk
 
 from korean_rules import rule_engine
-from content_pack import get_active_pack, replace_active_pack
+from content_pack import (get_active_pack, replace_active_pack,
+                           get_explanation, get_example_sentences,
+                           get_speaking_sentences, get_nouns)
 from learner_model import get_or_create_session, get_session, delete_session, purge_stale_sessions
 from question_generator import QuestionGenerator, QTYPE_TO_RULE
 
@@ -671,6 +673,145 @@ def handle_writing_verification(data):
         emit('writing_result', {"correct": False, "detected_text": "Error", "feedback": "Server error"})
 
 
+# ===========================================================================
+# 9. LESSON FLOW — Explanation, Example Sentences, Speaking Practice
+# ===========================================================================
+# These three endpoints serve the 6-frame lesson structure:
+#   Frame 1+2 → get_lesson_explanation  (title, body, pattern)
+#   Frame 3   → get_example_sentences   (positive/negative pairs)
+#   Frame 4   → request_question        (existing — MCQ / fill-in / assemble)
+#   Frame 4.1 → submit_answer           (existing — feedback)
+#   Frame 5   → get_speaking_sentence   (sentence to repeat aloud)
+#   Frame 6   → assess_pronunciation    (existing — accuracy + word scores)
+# ===========================================================================
+
+@socketio.on('get_lesson_explanation')
+def handle_get_lesson_explanation(data):
+    """
+    Frame 1+2: Return explanation and grammar pattern for a rule.
+    Emit:     { "grammar_rule": "copula" }
+    Response: { "grammar_rule", "title", "body", "pattern", "notes", "difficulty", "lesson" }
+    """
+    grammar_rule = (data or {}).get("grammar_rule", "")
+    if not grammar_rule:
+        emit('lesson_explanation', {"error": "grammar_rule is required"})
+        return
+    explanation = get_explanation(grammar_rule)
+    if not explanation.get("title"):
+        emit('lesson_explanation', {"error": f"No lesson content for rule: {grammar_rule}"})
+        return
+    logger.info(f"📖 Explanation: rule={grammar_rule}")
+    emit('lesson_explanation', explanation)
+
+
+@socketio.on('get_example_sentences')
+def handle_get_example_sentences(data):
+    """
+    Frame 3: Return positive/negative sentence pairs for a grammar rule.
+    Emit:     { "grammar_rule": "copula", "use_ai": false }
+    Response: { "grammar_rule", "sentences": [{positive, negative, focus_word, rule_shown}], "source" }
+
+    use_ai=true generates fresh pairs via Gemini (slower, falls back to hardcoded on error).
+    use_ai=false (default) returns hardcoded pairs instantly.
+    """
+    grammar_rule = (data or {}).get("grammar_rule", "")
+    use_ai       = (data or {}).get("use_ai", False)
+    if not grammar_rule:
+        emit('example_sentences', {"error": "grammar_rule is required"})
+        return
+
+    logger.info(f"📝 Example sentences: rule={grammar_rule} use_ai={use_ai}")
+    sentences = get_example_sentences(grammar_rule)
+
+    if not use_ai or not client:
+        emit('example_sentences', {"grammar_rule": grammar_rule, "sentences": sentences, "source": "hardcoded"})
+        return
+
+    try:
+        pack      = get_active_pack()
+        nouns     = get_nouns(pack)[:10]
+        noun_list = ", ".join(f"{n['korean']}({n['english']})" for n in nouns)
+        rule_info = get_explanation(grammar_rule)
+        prompt = (
+            f"You are a Korean language teacher generating example sentences.\n"
+            f"Grammar rule: {grammar_rule}\n"
+            f"Explanation: {rule_info.get('body', '')}\n"
+            f"Pattern: {rule_info.get('pattern', '')}\n"
+            f"Vocabulary: {noun_list}\n\n"
+            f"Generate exactly 2 positive/negative sentence pairs demonstrating the rule.\n"
+            f"Return ONLY valid JSON: {{\"sentences\": ["
+            f"{{\"positive\": {{\"korean\": \"...\", \"english\": \"...\"}}, "
+            f"\"negative\": {{\"korean\": \"...\", \"english\": \"...\"}}, "
+            f"\"focus_word\": \"...\", \"rule_shown\": \"...\"}}]}}"
+        )
+        response = client.models.generate_content(model=GEMINI_MODEL, contents=prompt)
+        text = response.text.strip()
+        if "```" in text:
+            text = text.split("```")[1]
+            if text.startswith("json"):
+                text = text[4:]
+        ai_sentences = json.loads(text.strip()).get("sentences", [])
+        if ai_sentences:
+            emit('example_sentences', {"grammar_rule": grammar_rule, "sentences": ai_sentences, "source": "gemini"})
+            return
+    except Exception as e:
+        logger.warning(f"Gemini example gen failed: {e} — fallback to hardcoded")
+
+    emit('example_sentences', {"grammar_rule": grammar_rule, "sentences": sentences, "source": "hardcoded_fallback"})
+
+
+@socketio.on('get_speaking_sentence')
+def handle_get_speaking_sentence(data):
+    """
+    Frame 5: Return a sentence for the user to repeat aloud.
+    The reference_text field is ready to pass directly to assess_pronunciation.
+
+    Emit:     { "grammar_rule": "copula", "difficulty": 1, "exclude_ids": ["0"] }
+    Response: { "grammar_rule", "sentence": {korean, english, difficulty},
+                "sentence_index", "total_sentences",
+                "instruction", "reference_text" }
+    """
+    grammar_rule = (data or {}).get("grammar_rule", "")
+    difficulty   = (data or {}).get("difficulty", None)
+    exclude_ids  = set(str(i) for i in (data or {}).get("exclude_ids", []))
+    if not grammar_rule:
+        emit('speaking_sentence', {"error": "grammar_rule is required"})
+        return
+
+    logger.info(f"🗣️  Speaking sentence: rule={grammar_rule} diff={difficulty}")
+    sentences = get_speaking_sentences(grammar_rule, difficulty=difficulty)
+
+    if not sentences:
+        examples = get_example_sentences(grammar_rule)
+        if examples:
+            first = examples[0]["positive"]
+            emit('speaking_sentence', {
+                "grammar_rule": grammar_rule,
+                "sentence": {"korean": first["korean"], "english": first["english"], "difficulty": 1},
+                "sentence_index": "ex_0", "total_sentences": len(examples),
+                "instruction": "듣고 따라 말해 보세요! Listen and repeat.",
+                "reference_text": first["korean"],
+            })
+            return
+        emit('speaking_sentence', {"error": f"No speaking sentences for rule: {grammar_rule}"})
+        return
+
+    import random
+    available = [(i, s) for i, s in enumerate(sentences) if str(i) not in exclude_ids]
+    if not available:
+        available = list(enumerate(sentences))
+    idx, sentence = random.choice(available)
+
+    emit('speaking_sentence', {
+        "grammar_rule": grammar_rule,
+        "sentence": sentence,
+        "sentence_index": str(idx),
+        "total_sentences": len(sentences),
+        "instruction": "듣고 따라 말해 보세요! Listen and repeat.",
+        "reference_text": sentence["korean"],
+    })
+
+
 @socketio.on('get_grammar_rules')
 def handle_get_grammar_rules(data):
     pack = get_active_pack()