Update app.py

app.py

@@ -1,701 +1,28 @@
-import os
-import re
-import math
+# app.py
 from typing import List, Dict, Tuple, Optional
 
 import gradio as gr
-from openai import OpenAI
-from docx import Document
 
-# ---------- 环境变量 ----------
-OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
-if not OPENAI_API_KEY:
-    raise RuntimeError(
-        "OPENAI_API_KEY is not set. Please go to Settings → Secrets and add it."
-    )
-
-client = OpenAI(api_key=OPENAI_API_KEY)
-DEFAULT_MODEL = "gpt-4.1-mini"
-EMBEDDING_MODEL = "text-embedding-3-small"
-
-# ---------- 默认 GenAI 课程大纲 ----------
-DEFAULT_COURSE_TOPICS = [
-    "Week 0 – Welcome & What is Generative AI; course outcomes LO1–LO5.",
-    "Week 1 – Foundations of GenAI: LLMs, Transformer & self-attention, perplexity.",
-    "Week 2 – Foundation Models & multimodal models; data scale, bias & risks.",
-    "Week 3 – Choosing Pre-trained Models; open-source vs proprietary; cost vs quality.",
-    "Week 4 – Prompt Engineering: core principles; zero/few-shot; CoT; ReAct.",
-    "Week 5 – Building a Simple Chatbot; memory (short vs long term); LangChain & UI.",
-    "Week 6 – Review Week; cross-module consolidation & self-check prompts.",
-    "Week 7 – Retrieval-Augmented Generation (RAG); embeddings; hybrid retrieval.",
-    "Week 8 – Agents & Agentic RAG; planning, tools, knowledge augmentation.",
-    "Week 9 – Evaluating GenAI Apps; hallucination, bias/fairness, metrics.",
-    "Week 10 – Responsible AI; risks, governance, EU AI Act-style ideas.",
-]
-
-# ---------- 学习模式 ----------
-LEARNING_MODES = [
-    "Concept Explainer",
-    "Socratic Tutor",
-    "Exam Prep / Quiz",
-    "Assignment Helper",
-    "Quick Summary",
-]
-
-LEARNING_MODE_INSTRUCTIONS = {
-    "Concept Explainer": (
-        "Explain concepts step by step. Use clear definitions, key formulas or structures, "
-        "and one or two simple examples. Focus on clarity over depth. Regularly check if "
-        "the student is following."
-    ),
-    "Socratic Tutor": (
-        "Use a Socratic style. Ask the student ONE short question at a time, guide them to "
-        "reason step by step, and only give full explanations after they try. Prioritize "
-        "questions and hints over long lectures."
-    ),
-    "Exam Prep / Quiz": (
-        "Behave like an exam prep coach. Often propose short quiz-style questions "
-        "(multiple choice or short answer), then explain the solutions clearly. Emphasize "
-        "common traps and how to avoid them."
-    ),
-    "Assignment Helper": (
-        "Help with assignments WITHOUT giving full final solutions. Clarify requirements, "
-        "break tasks into smaller steps, and provide hints, partial examples, or pseudo-code "
-        "instead of complete code or final answers. Encourage the student to attempt each "
-        "step before revealing more."
-    ),
-    "Quick Summary": (
-        "Provide concise, bullet-point style summaries and cheat-sheet style notes. "
-        "Focus on key ideas and avoid long paragraphs."
-    ),
-}
-
-# ---------- 上传文件类型 ----------
-DOC_TYPES = [
-    "Syllabus",
-    "Lecture Slides / PPT",
-    "Literature Review / Paper",
-    "Other Course Document",
-]
-
-# ---------- Clare 的基础 System Prompt ----------
-CLARE_SYSTEM_PROMPT = """
-You are Clare, an AI teaching assistant for Hanbridge University.
-
-Core identity:
-- You are patient, encouraging, and structured like a very good TA.
-- Your UI and responses should be in ENGLISH by default.
-- However, you can understand BOTH English and Chinese, and you may reply in Chinese
-  if the student clearly prefers Chinese or asks you to.
-
-General responsibilities:
-1. Help students understand course concepts step by step.
-2. Ask short check-up questions to confirm understanding instead of giving huge long lectures.
-3. When the student seems confused, break content into smaller chunks and use simple language first.
-4. When the student is advanced, you can switch to more technical explanations.
-
-Safety and honesty:
-- If you don’t know, say you are not sure and suggest how to verify.
-- Do not fabricate references, exam answers, or grades.
-"""
-
-# ---------- syllabus 解析 ----------
-def parse_syllabus_docx(file_path: str, max_lines: int = 15) -> List[str]:
-    """
-    非常简单的 syllabus 解析：取前若干个非空段落当作主题行。
-    只是为了给 Clare 一些课程上下文，不追求超精确结构。
-    """
-    topics: List[str] = []
-    try:
-        doc = Document(file_path)
-        for para in doc.paragraphs:
-            text = para.text.strip()
-            if not text:
-                continue
-            topics.append(text)
-            if len(topics) >= max_lines:
-                break
-    except Exception as e:
-        topics = [f"[Error parsing syllabus: {e}]"]
-
-    return topics
-
-
-# ---------- 简单“弱项”检测 ----------
-WEAKNESS_KEYWORDS = [
-    "don't understand",
-    "do not understand",
-    "not understand",
-    "not sure",
-    "confused",
-    "hard to",
-    "difficult",
-    "struggle",
-    "不会",
-    "不懂",
-    "看不懂",
-    "搞不清",
-    "很难",
-]
-
-# ---------- 简单“掌握”检测 ----------
-MASTERY_KEYWORDS = [
-    "got it",
-    "makes sense",
-    "now i see",
-    "i see",
-    "understand now",
-    "clear now",
-    "easy",
-    "no problem",
-    "没问题",
-    "懂了",
-    "明白了",
-    "清楚了",
-]
-
-def update_weaknesses_from_message(message: str, weaknesses: List[str]) -> List[str]:
-    lower_msg = message.lower()
-    if any(k in lower_msg for k in WEAKNESS_KEYWORDS):
-        weaknesses = weaknesses or []
-        weaknesses.append(message)
-    return weaknesses
-
-
-def update_cognitive_state_from_message(
-    message: str,
-    state: Optional[Dict[str, int]],
-) -> Dict[str, int]:
-    """
-    简单认知状态统计：
-    - 遇到困惑类关键词 → confusion +1
-    - 遇到掌握类关键词 → mastery +1
-    """
-    if state is None:
-        state = {"confusion": 0, "mastery": 0}
-
-    lower_msg = message.lower()
-    if any(k in lower_msg for k in WEAKNESS_KEYWORDS):
-        state["confusion"] = state.get("confusion", 0) + 1
-    if any(k in lower_msg for k in MASTERY_KEYWORDS):
-        state["mastery"] = state.get("mastery", 0) + 1
-    return state
-
-
-def describe_cognitive_state(state: Optional[Dict[str, int]]) -> str:
-    if not state:
-        return "unknown"
-    confusion = state.get("confusion", 0)
-    mastery = state.get("mastery", 0)
-    if confusion >= 2 and confusion >= mastery + 1:
-        return "student shows signs of HIGH cognitive load (often confused)."
-    elif mastery >= 2 and mastery >= confusion + 1:
-        return "student seems COMFORTABLE; material may be slightly easy."
-    else:
-        return "mixed or uncertain cognitive state."
-
-
-# ---------- 语言检测（用于 Auto 模式） ----------
-def detect_language(message: str, preference: str) -> str:
-    """
-    preference:
-      - 'English' → 强制英文
-      - '中文' → 强制中文
-      - 'Auto' → 检测文本是否包含中文字符
-    """
-    if preference in ("English", "中文"):
-        return preference
-    # Auto 模式下简单检测是否含有中文字符
-    if re.search(r"[\u4e00-\u9fff]", message):
-        return "中文"
-    return "English"
-
-
-# ---------- Session 状态展示 ----------
-def render_session_status(
-    learning_mode: str,
-    weaknesses: Optional[List[str]],
-    cognitive_state: Optional[Dict[str, int]],
-) -> str:
-    lines: List[str] = []
-    lines.append("### Session status\n")
-    lines.append(f"- Learning mode: **{learning_mode}**")
-    lines.append(f"- Cognitive state: {describe_cognitive_state(cognitive_state)}")
-
-    if weaknesses:
-        lines.append("- Recent difficulties (last 3):")
-        for w in weaknesses[-3:]:
-            lines.append(f"  - {w}")
-    else:
-        lines.append("- Recent difficulties: *(none yet)*")
-
-    return "\n".join(lines)
-
-
-# ---------- Same Question Check helpers ----------
-def _normalize_text(text: str) -> str:
-    """
-    将文本转为小写、去除标点和多余空格，用于简单相似度计算。
-    """
-    text = text.lower().strip()
-    # 去掉标点符号，只保留字母数字和空格
-    text = re.sub(r"[^\w\s]", " ", text)
-    text = re.sub(r"\s+", " ", text)
-    return text
-
-
-def _jaccard_similarity(a: str, b: str) -> float:
-    tokens_a = set(a.split())
-    tokens_b = set(b.split())
-    if not tokens_a or not tokens_b:
-        return 0.0
-    return len(tokens_a & tokens_b) / len(tokens_a | tokens_b)
-
-
-def cosine_similarity(a: List[float], b: List[float]) -> float:
-    if not a or not b or len(a) != len(b):
-        return 0.0
-    dot = sum(x * y for x, y in zip(a, b))
-    norm_a = math.sqrt(sum(x * x for x in a))
-    norm_b = math.sqrt(sum(y * y for y in b))
-    if norm_a == 0 or norm_b == 0:
-        return 0.0
-    return dot / (norm_a * norm_b)
-
-
-def get_embedding(text: str) -> Optional[List[float]]:
-    """
-    调用 OpenAI Embedding API，将文本编码为向量。
-    """
-    try:
-        resp = client.embeddings.create(
-            model=EMBEDDING_MODEL,
-            input=[text],
-        )
-        return resp.data[0].embedding
-    except Exception as e:
-        # 打到 Hugging Face 的 log，方便你在 Space Logs 里看
-        print(f"[Embedding error] {repr(e)}")
-        return None
-
-
-def find_similar_past_question(
-    message: str,
-    history: List[Tuple[str, str]],
-    jaccard_threshold: float = 0.65,
-    embedding_threshold: float = 0.85,
-    max_turns_to_check: int = 6,
-) -> Optional[Tuple[str, str, float]]:
-    """
-    在最近若干轮历史对话中查找与当前问题相似的既往问题。
-
-    两级检测：
-    1. 先用 Jaccard 做快速近似匹配（文本几乎一样的情况）
-    2. 再用 OpenAI embedding 做语义相似度检测（改写、同义句）
-
-    返回:
-        (past_question, past_answer, similarity_score) 或 None
-    """
-    # ---------- 第一步：Jaccard 快速检测 ----------
-    norm_msg = _normalize_text(message)
-    if not norm_msg:
-        return None
-
-    best_sim_j = 0.0
-    best_pair_j: Optional[Tuple[str, str]] = None
-    checked = 0
-
-    for user_q, assistant_a in reversed(history):
-        checked += 1
-        if checked > max_turns_to_check:
-            break
-
-        norm_hist_q = _normalize_text(user_q)
-        if not norm_hist_q:
-            continue
-
-        if norm_msg == norm_hist_q:
-            # 完全相同，直接视为重复
-            return user_q, assistant_a, 1.0
-
-        sim_j = _jaccard_similarity(norm_msg, norm_hist_q)
-        if sim_j > best_sim_j:
-            best_sim_j = sim_j
-            best_pair_j = (user_q, assistant_a)
-
-    if best_pair_j and best_sim_j >= jaccard_threshold:
-        # 词面高度相似，直接视为重复
-        return best_pair_j[0], best_pair_j[1], best_sim_j
-
-    # ---------- 第二步：Embedding 语义相似度 ----------
-    # 如果历史太少，就没必要算 embedding
-    if not history:
-        return None
-
-    msg_emb = get_embedding(message)
-    if msg_emb is None:
-        # embedding 调用失败，放弃语义检测
-        return None
-
-    best_sim_e = 0.0
-    best_pair_e: Optional[Tuple[str, str]] = None
-    checked = 0
-
-    for user_q, assistant_a in reversed(history):
-        checked += 1
-        if checked > max_turns_to_check:
-            break
-
-        hist_emb = get_embedding(user_q)
-        if hist_emb is None:
-            continue
-
-        sim_e = cosine_similarity(msg_emb, hist_emb)
-        if sim_e > best_sim_e:
-            best_sim_e = sim_e
-            best_pair_e = (user_q, assistant_a)
-
-    if best_pair_e and best_sim_e >= embedding_threshold:
-        return best_pair_e[0], best_pair_e[1], best_sim_e
-
-    return None
-
-
-# ---------- 构建 messages ----------
-def build_messages(
-    user_message: str,
-    history: List[Tuple[str, str]],
-    language_preference: str,
-    learning_mode: str,
-    doc_type: str,
-    course_outline: Optional[List[str]],
-    weaknesses: Optional[List[str]],
-    cognitive_state: Optional[Dict[str, int]],
-) -> List[Dict[str, str]]:
-    messages: List[Dict[str, str]] = [
-        {"role": "system", "content": CLARE_SYSTEM_PROMPT}
-    ]
-
-    # 学习模式注入
-    if learning_mode in LEARNING_MODE_INSTRUCTIONS:
-        mode_instruction = LEARNING_MODE_INSTRUCTIONS[learning_mode]
-        messages.append(
-            {
-                "role": "system",
-                "content": f"Current learning mode: {learning_mode}. {mode_instruction}",
-            }
-        )
-
-    # 课程大纲注入
-    topics = course_outline if course_outline else DEFAULT_COURSE_TOPICS
-    topics_text = " | ".join(topics)
-    messages.append(
-        {
-            "role": "system",
-            "content": (
-                "Here is the course syllabus context. Use this to stay aligned "
-                "with the course topics when answering: "
-                + topics_text
-            ),
-        }
-    )
-
-    # 上传文件类型提示（仅作语境）
-    if doc_type and doc_type != "Syllabus":
-        messages.append(
-            {
-                "role": "system",
-                "content": (
-                    f"The student also uploaded a {doc_type} document as supporting material. "
-                    "You do not see the full content directly, but you may assume it is relevant "
-                    "to the same course and topics."
-                ),
-            }
-        )
-
-    # 学生弱项提示（会话内记忆）
-    if weaknesses:
-        weak_text = " | ".join(weaknesses[-5:])  # 最近几条即可
-        messages.append(
-            {
-                "role": "system",
-                "content": (
-                    "The student seems to struggle with the following questions or topics. "
-                    "Be extra gentle and clear when these appear: " + weak_text
-                ),
-            }
-        )
-
-    # 认知状态提示（动态复杂度调整）
-    if cognitive_state:
-        confusion = cognitive_state.get("confusion", 0)
-        mastery = cognitive_state.get("mastery", 0)
-        if confusion >= 2 and confusion >= mastery + 1:
-            messages.append(
-                {
-                    "role": "system",
-                    "content": (
-                        "The student is currently under HIGH cognitive load. "
-                        "Use simpler language, shorter steps, and more concrete examples. "
-                        "Avoid long derivations in a single answer, and check understanding "
-                        "frequently."
-                    ),
-                }
-            )
-        elif mastery >= 2 and mastery >= confusion + 1:
-            messages.append(
-                {
-                    "role": "system",
-                    "content": (
-                        "The student seems comfortable with the material. "
-                        "You may increase difficulty slightly, introduce deeper follow-up "
-                        "questions, and connect concepts across topics."
-                    ),
-                }
-            )
-        else:
-            messages.append(
-                {
-                    "role": "system",
-                    "content": (
-                        "The student's cognitive state is mixed or uncertain. "
-                        "Keep explanations clear and moderately paced, and probe for "
-                        "understanding with short questions."
-                    ),
-                }
-            )
-
-    # 语言偏好控制
-    if language_preference == "English":
-        messages.append(
-            {"role": "system", "content": "Please answer in English."}
-        )
-    elif language_preference == "中文":
-        messages.append(
-            {"role": "system", "content": "请用中文回答学生的问题。"}
-        )
-
-    # 历史对话
-    for user, assistant in history:
-        messages.append({"role": "user", "content": user})
-        if assistant is not None:
-            messages.append({"role": "assistant", "content": assistant})
-
-    # 当前输入
-    messages.append({"role": "user", "content": user_message})
-    return messages
-
-
-def chat_with_clare(
-    message: str,
-    history: List[Tuple[str, str]],
-    model_name: str,
-    language_preference: str,
-    learning_mode: str,
-    doc_type: str,
-    course_outline: Optional[List[str]],
-    weaknesses: Optional[List[str]],
-    cognitive_state: Optional[Dict[str, int]],
-):
-    try:
-        messages = build_messages(
-            user_message=message,
-            history=history,
-            language_preference=language_preference,
-            learning_mode=learning_mode,
-            doc_type=doc_type,
-            course_outline=course_outline,
-            weaknesses=weaknesses,
-            cognitive_state=cognitive_state,
-        )
-        response = client.chat.completions.create(
-            model=model_name or DEFAULT_MODEL,
-            messages=messages,
-            temperature=0.5,
-        )
-        answer = response.choices[0].message.content
-    except Exception as e:
-        answer = f"⚠️ Error talking to the model: {e}"
-
-    history = history + [(message, answer)]
-    return answer, history
-
-
-# ---------- 导出对话为 Markdown ----------
-def export_conversation(
-    history: List[Tuple[str, str]],
-    course_outline: List[str],
-    learning_mode_val: str,
-    weaknesses: List[str],
-    cognitive_state: Optional[Dict[str, int]],
-) -> str:
-    lines: List[str] = []
-    lines.append("# Clare – Conversation Export\n")
-    lines.append(f"- Learning mode: **{learning_mode_val}**\n")
-    lines.append("- Course topics (short): " + "; ".join(course_outline[:5]) + "\n")
-    lines.append(f"- Cognitive state snapshot: {describe_cognitive_state(cognitive_state)}\n")
-
-    if weaknesses:
-        lines.append("- Observed student difficulties:\n")
-        for w in weaknesses[-5:]:
-            lines.append(f"  - {w}\n")
-    lines.append("\n---\n\n")
-
-    for user, assistant in history:
-        lines.append(f"**Student:** {user}\n\n")
-        lines.append(f"**Clare:** {assistant}\n\n")
-        lines.append("---\n\n")
-
-    return "".join(lines)
-
-
-# ---------- 生成 3 个 quiz 题目 ----------
-def generate_quiz_from_history(
-    history: List[Tuple[str, str]],
-    course_outline: List[str],
-    weaknesses: List[str],
-    cognitive_state: Optional[Dict[str, int]],
-    model_name: str,
-    language_preference: str,
-) -> str:
-    conversation_text = ""
-    for user, assistant in history[-8:]:  # 用最近几轮
-        conversation_text += f"Student: {user}\nClare: {assistant}\n"
-
-    topics_text = "; ".join(course_outline[:8])
-    weakness_text = "; ".join(weaknesses[-5:]) if weaknesses else "N/A"
-    cog_text = describe_cognitive_state(cognitive_state)
-
-    messages = [
-        {"role": "system", "content": CLARE_SYSTEM_PROMPT},
-        {
-            "role": "system",
-            "content": (
-                "Now your task is to create a **short concept quiz** for the student. "
-                "Based on the conversation and course topics, generate **3 questions** "
-                "(a mix of multiple-choice and short-answer is fine). After listing the "
-                "questions, provide an answer key at the end under a heading 'Answer Key'. "
-                "Number the questions Q1, Q2, Q3. Adjust the difficulty according to the "
-                "student's cognitive state."
-            ),
-        },
-        {
-            "role": "system",
-            "content": f"Course topics: {topics_text}",
-        },
-        {
-            "role": "system",
-            "content": f"Student known difficulties: {weakness_text}",
-        },
-        {
-            "role": "system",
-            "content": f"Student cognitive state: {cog_text}",
-        },
-        {
-            "role": "user",
-            "content": (
-                "Here is the recent conversation between you and the student:\n\n"
-                + conversation_text
-                + "\n\nPlease create the quiz now."
-            ),
-        },
-    ]
-
-    if language_preference == "中文":
-        messages.append(
-            {
-                "role": "system",
-                "content": "请用中文给出问题和答案。",
-            }
-        )
-
-    try:
-        response = client.chat.completions.create(
-            model=model_name or DEFAULT_MODEL,
-            messages=messages,
-            temperature=0.5,
-        )
-        quiz_text = response.choices[0].message.content
-    except Exception as e:
-        quiz_text = f"⚠️ Error generating quiz: {e}"
-
-    return quiz_text
-
-
-# ---------- 概念总结（知识点摘要） ----------
-def summarize_conversation(
-    history: List[Tuple[str, str]],
-    course_outline: List[str],
-    weaknesses: List[str],
-    cognitive_state: Optional[Dict[str, int]],
-    model_name: str,
-    language_preference: str,
-) -> str:
-    conversation_text = ""
-    for user, assistant in history[-10:]:  # 最近 10 轮足够
-        conversation_text += f"Student: {user}\nClare: {assistant}\n"
-
-    topics_text = "; ".join(course_outline[:8])
-    weakness_text = "; ".join(weaknesses[-5:]) if weaknesses else "N/A"
-    cog_text = describe_cognitive_state(cognitive_state)
-
-    messages = [
-        {"role": "system", "content": CLARE_SYSTEM_PROMPT},
-        {
-            "role": "system",
-            "content": (
-                "Your task now is to produce a **concept-only summary** of this tutoring "
-                "session. Only include knowledge points, definitions, key formulas, "
-                "examples, and main takeaways. Do **not** include any personal remarks, "
-                "jokes, or off-topic chat. Write in clear bullet points. This summary "
-                "should be suitable for the student to paste into their study notes. "
-                "Take into account what the student struggled with and their cognitive state."
-            ),
-        },
-        {
-            "role": "system",
-            "content": f"Course topics context: {topics_text}",
-        },
-        {
-            "role": "system",
-            "content": f"Student known difficulties: {weakness_text}",
-        },
-        {
-            "role": "system",
-            "content": f"Student cognitive state: {cog_text}",
-        },
-        {
-            "role": "user",
-            "content": (
-                "Here is the recent conversation between you and the student:\n\n"
-                + conversation_text
-                + "\n\nPlease summarize only the concepts and key ideas learned."
-            ),
-        },
-    ]
-
-    if language_preference == "中文":
-        messages.append(
-            {
-                "role": "system",
-                "content": "请用中文给出要点总结，只保留知识点和结论，使用条目符号。"
-            }
-        )
-
-    try:
-        response = client.chat.completions.create(
-            model=model_name or DEFAULT_MODEL,
-            messages=messages,
-            temperature=0.4,
-        )
-        summary_text = response.choices[0].message.content
-    except Exception as e:
-        summary_text = f"⚠️ Error generating summary: {e}"
-
-    return summary_text
+from config import (
+    DEFAULT_MODEL,
+    DEFAULT_COURSE_TOPICS,
+    LEARNING_MODES,
+    DOC_TYPES,
+)
+from clare_core import (
+    parse_syllabus_docx,
+    update_weaknesses_from_message,
+    update_cognitive_state_from_message,
+    render_session_status,
+    find_similar_past_question,
+    detect_language,
+    chat_with_clare,
+    export_conversation,
+    generate_quiz_from_history,
+    summarize_conversation,
+)
 
 
-# ---------- Gradio UI ----------
 with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
     gr.Markdown(
         """
@@ -709,6 +36,7 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
         """
     )
 
+    # 顶部：模型、语言偏好、学习模式
     with gr.Row():
         model_name = gr.Textbox(
             label="Model name",
@@ -726,6 +54,7 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
             label="Learning mode",
         )
 
+    # 课程文件上传
     with gr.Row():
         syllabus_file = gr.File(
             label="Upload course file (.docx)",
@@ -742,20 +71,18 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
     weakness_state = gr.State([])
     cognitive_state_state = gr.State({"confusion": 0, "mastery": 0})
 
-    # syllabus 上传后更新课程大纲（仅当类型是 Syllabus 时解析）
+    # 上传 syllabus 时更新课程大纲
     def update_outline(file, doc_type_val):
         if file is None:
             return DEFAULT_COURSE_TOPICS
-        # Gradio File 默认传的是一个带 .name 的临时文件对象
         if doc_type_val == "Syllabus":
             try:
-                file_path = file.name  # 临时文件真实路径
+                file_path = file.name
                 if file_path.lower().endswith(".docx"):
                     topics = parse_syllabus_docx(file_path)
                     return topics
             except Exception:
                 return DEFAULT_COURSE_TOPICS
-        # 其他类型文件目前不解析，只保留默认大纲
         return DEFAULT_COURSE_TOPICS
 
     syllabus_file.change(
@@ -764,6 +91,7 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
         outputs=[course_outline_state],
     )
 
+    # 左侧聊天，右侧 Session 状态栏
     with gr.Row():
         chatbot = gr.Chatbot(
             label="Clare Chat",
@@ -798,7 +126,7 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
         lines=8,
     )
 
-    # 主对话逻辑：Same Question Check + 更新弱项 + 认知状态 + 调用 Clare
+    # 主对话逻辑
     def respond(
         message,
         chat_history,
@@ -810,14 +138,14 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
         learning_mode_val,
         doc_type_val,
     ):
-        # 先根据 Auto / English / 中文 决定本轮用什么语言
+        # 1) 决定本轮语言（Auto / English / 中文）
         resolved_lang = detect_language(message, language_pref_val)
 
-        # 先更新弱项和认知状态
+        # 2) 更新弱项 & 认知状态
         weaknesses = update_weaknesses_from_message(message, weaknesses or [])
         cognitive_state = update_cognitive_state_from_message(message, cognitive_state)
 
-        # ---------- Same Question Check ----------
+        # 3) Same Question Check
         dup = find_similar_past_question(message, chat_history)
         if dup is not None:
             past_q, past_a, sim = dup
@@ -841,10 +169,9 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
 
             new_history = chat_history + [(message, answer)]
             status_text = render_session_status(learning_mode_val, weaknesses, cognitive_state)
-            # 清空输入框，更新 history / 弱项 / 认知状态 / 状态栏
             return "", new_history, weaknesses, cognitive_state, status_text
 
-        # ---------- 正常调用 Clare ----------
+        # 4) 正常调用 Clare
         answer, new_history = chat_with_clare(
             message=message,
             history=chat_history,
@@ -876,7 +203,7 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
         [user_input, chatbot, weakness_state, cognitive_state_state, session_status],
     )
 
-    # 清空对话 & 状态 & 导出/quiz/summary
+    # 清空对话 & 状态
     def clear_all():
         empty_state = {"confusion": 0, "mastery": 0}
         status_text = render_session_status("Concept Explainer", [], empty_state)
@@ -889,7 +216,7 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
         queue=False,
     )
 
-    # 导出对话按钮
+    # 导出对话
     def on_export(chat_history, course_outline, learning_mode_val, weaknesses, cognitive_state):
         return export_conversation(
             chat_history,
@@ -905,7 +232,7 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
         [export_box],
     )
 
-    # 生成 quiz 按钮
+    # 生成 quiz
     def on_quiz(
         chat_history,
         course_outline,
@@ -936,7 +263,7 @@ with gr.Blocks(title="Clare – Hanbridge AI Teaching Assistant") as demo:
         [quiz_box],
     )
 
-    # 概念总结按钮
+    # 概念总结
     def on_summary(
         chat_history,
         course_outline,