Initial PDF tutor app

.gitignore

@@ -205,3 +205,5 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+tmp_outputs/
+.DS_Store

app.py

@@ -0,0 +1,1625 @@
+import base64
+import json
+import math
+import os
+import re
+import uuid
+import wave
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import gradio as gr
+import requests
+
+try:
+    import spaces  # type: ignore
+except Exception:
+    class _SpacesFallback:
+        @staticmethod
+        def GPU(fn):
+            return fn
+
+    spaces = _SpacesFallback()  # type: ignore
+
+try:
+    from pypdf import PdfReader
+except Exception:  # pragma: no cover
+    PdfReader = None  # type: ignore
+
+try:
+    import pypdfium2 as pdfium
+except Exception:  # pragma: no cover
+    pdfium = None  # type: ignore
+
+
+APP_DIR = Path(__file__).parent.resolve()
+TMP_DIR = APP_DIR / "tmp_outputs"
+TMP_DIR.mkdir(exist_ok=True)
+
+def _load_dotenv_file(dotenv_path: Path) -> None:
+    if not dotenv_path.exists():
+        return
+    for raw_line in dotenv_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+_load_dotenv_file(APP_DIR / ".env")
+
+API_URL = os.getenv("API_URL") or os.getenv("API_UR", "")
+API_KEY = os.getenv("API_KEY", "")
+USE_MOCK_MODELS = os.getenv("USE_MOCK_MODELS", "0" if (API_URL and API_KEY) else "1") == "1"
+CHAT_MODEL_ID = os.getenv("QWEN_VL_MODEL_ID", "qwen-vl-max")
+TTS_MODEL_ID = os.getenv("QWEN_TTS_MODEL_ID", "qwen-tts")
+TTS_SPEAKER = os.getenv("QWEN_TTS_SPEAKER", "longxiaochun_v2")
+TTS_FORMAT = os.getenv("QWEN_TTS_FORMAT", "wav")
+API_TIMEOUT_SEC = int(os.getenv("API_TIMEOUT_SEC", "180"))
+QWEN_VL_MAX_PAGES = int(os.getenv("QWEN_VL_MAX_PAGES", "4"))
+QWEN_VL_RENDER_SCALE = float(os.getenv("QWEN_VL_RENDER_SCALE", "1.5"))
+QWEN_VL_MAX_NEW_TOKENS = int(os.getenv("QWEN_VL_MAX_NEW_TOKENS", "800"))
+QWEN_VL_MCQ_MAX_NEW_TOKENS = int(os.getenv("QWEN_VL_MCQ_MAX_NEW_TOKENS", "1800"))
+
+
+DEFAULT_LECTURE_PROMPT_TEMPLATE = """
+你是一名课程助教。请阅读用户上传的论文内容，并输出一段中文讲解，要求：
+1. 先说明论文要解决的问题和背景；
+2. 再解释核心方法（按步骤/模块）；
+3. 再总结实验结果或亮点；
+4. 最后给出局限性与适用场景；
+5. 语言清晰，适合课堂讲解（约 400-700 字）。
+
+论文内容（可能是节选）：
+{document}
+""".strip()
+
+
+DEFAULT_MCQ_PROMPT_TEMPLATE = """
+请基于下面论文内容，生成 5 道中文单选题（MCQ），用于课堂测验。
+严格输出 JSON（不要 markdown 代码块），格式如下：
+{{
+  "questions": [
+    {{
+      "question": "...",
+      "options": ["A选项", "B选项", "C选项", "D选项"],
+      "answer": "A",
+      "explanation": "..."
+    }}
+  ]
+}}
+
+要求：
+1. 共 5 题；
+2. 每题 4 个选项；
+3. answer 必须是 A/B/C/D；
+4. 解析要说明为什么正确，以及常见误区；
+5. 题目应覆盖问题背景、方法、实验/结果、局限性。
+
+论文内容（可能是节选）：
+{document}
+""".strip()
+
+
+DEFAULT_MCQ_RETRY_PROMPT_TEMPLATE = """
+基于以下论文内容生成 5 道中文单选题。只输出合法 JSON，不要任何解释，不要 markdown。
+
+限制：
+1. 必须是紧凑 JSON（单行也可以）；
+2. 共 5 题；
+3. 每题 question、options(4项)、answer(A/B/C/D)、explanation；
+4. 解析简短（1-2句），避免过长；
+5. 如果不确定，仍按论文内容出题，不要输出额外文字。
+
+输出格式：
+{{"questions":[{{"question":"...","options":["...","...","...","..."],"answer":"A","explanation":"..."}}]}}
+
+论文内容：
+{document}
+""".strip()
+
+
+CHARACTERS_DIR = APP_DIR / "characters"
+
+
+def _read_text_if_exists(path: Path, fallback: str) -> str:
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except Exception:
+        return fallback
+
+
+def render_prompt_template(template: str, document: str) -> str:
+    # Avoid `str.format(...)` because character prompt files may contain JSON braces.
+    return str(template).replace("{document}", document)
+
+
+def load_character_configs() -> Dict[str, Dict[str, Any]]:
+    configs: Dict[str, Dict[str, Any]] = {}
+    if CHARACTERS_DIR.exists():
+        for d in sorted(CHARACTERS_DIR.iterdir()):
+            if not d.is_dir():
+                continue
+            meta_path = d / "meta.json"
+            meta: Dict[str, Any] = {}
+            if meta_path.exists():
+                try:
+                    parsed = json.loads(meta_path.read_text(encoding="utf-8"))
+                    if isinstance(parsed, dict):
+                        meta = parsed
+                except Exception:
+                    meta = {}
+            cid = str(meta.get("id") or d.name)
+            if cid in configs:
+                cid = d.name
+            avatar_rel = str(meta.get("avatar", "avatar.jpg"))
+            config: Dict[str, Any] = {
+                "id": cid,
+                "display_name": str(meta.get("display_name", d.name)),
+                "tagline": str(meta.get("tagline", "Research paper explainer · MCQ coach")),
+                "byline": str(meta.get("byline", "By @local-demo")),
+                "chat_label": str(meta.get("chat_label", meta.get("display_name", d.name))),
+                "chat_mode": str(meta.get("chat_mode", "paper mode")),
+                "avatar_path": str((d / avatar_rel).resolve()),
+                "lecture_prompt_template": _read_text_if_exists(
+                    d / str(meta.get("lecture_prompt_file", "lecture_prompt.txt")),
+                    DEFAULT_LECTURE_PROMPT_TEMPLATE,
+                ),
+                "mcq_prompt_template": _read_text_if_exists(
+                    d / str(meta.get("mcq_prompt_file", "mcq_prompt.txt")),
+                    DEFAULT_MCQ_PROMPT_TEMPLATE,
+                ),
+                "mcq_retry_prompt_template": _read_text_if_exists(
+                    d / str(meta.get("mcq_retry_prompt_file", "mcq_retry_prompt.txt")),
+                    DEFAULT_MCQ_RETRY_PROMPT_TEMPLATE,
+                ),
+            }
+            configs[cid] = config
+
+    if not configs:
+        # Fallback to a built-in default character if no folder config exists.
+        configs["default"] = {
+            "id": "default",
+            "display_name": "PDF Paper Tutor",
+            "tagline": "Research paper explainer · MCQ coach",
+            "byline": "By @local-demo",
+            "chat_label": "PDF Paper Tutor",
+            "chat_mode": "paper mode",
+            "avatar_path": str((APP_DIR / "avatar.jpg").resolve()) if (APP_DIR / "avatar.jpg").exists() else "",
+            "lecture_prompt_template": DEFAULT_LECTURE_PROMPT_TEMPLATE,
+            "mcq_prompt_template": DEFAULT_MCQ_PROMPT_TEMPLATE,
+            "mcq_retry_prompt_template": DEFAULT_MCQ_RETRY_PROMPT_TEMPLATE,
+        }
+    return configs
+
+
+CHARACTER_CONFIGS = load_character_configs()
+DEFAULT_CHARACTER_ID = next(iter(CHARACTER_CONFIGS.keys()))
+
+
+def get_character_config(character_id: Optional[str]) -> Dict[str, Any]:
+    if character_id and character_id in CHARACTER_CONFIGS:
+        return CHARACTER_CONFIGS[character_id]
+    return CHARACTER_CONFIGS[DEFAULT_CHARACTER_ID]
+
+
+@dataclass
+class MCQItem:
+    question: str
+    options: List[str]
+    answer: str  # A/B/C/D
+    explanation: str
+
+    def to_display_choices(self) -> List[str]:
+        labels = ["A", "B", "C", "D"]
+        return [f"{labels[i]}. {opt}" for i, opt in enumerate(self.options)]
+
+    def correct_choice_display(self) -> str:
+        idx = ["A", "B", "C", "D"].index(self.answer)
+        return self.to_display_choices()[idx]
+
+
+def new_session_state() -> Dict[str, Any]:
+    return {
+        "lecture_text": "",
+        "lecture_audio_path": None,
+        "explanation_audio_path": None,
+        "last_explanation_tts_text": "",
+        "pdf_path": None,
+        "pdf_excerpt": "",
+        "character_id": DEFAULT_CHARACTER_ID,
+        "exam_character_id": None,
+        "current_page": "explain",
+        "mcqs": [],
+        "current_index": 0,
+        "score": 0,
+        "awaiting_next_after_wrong": False,
+        "completed": False,
+        "status": "Idle",
+    }
+
+
+def strip_code_fence(text: str) -> str:
+    s = text.strip()
+    if s.startswith("```"):
+        s = re.sub(r"^```[a-zA-Z0-9_-]*\n?", "", s)
+        s = re.sub(r"\n?```$", "", s)
+    return s.strip()
+
+
+def extract_pdf_text(pdf_path: str, max_chars: int = 16000) -> str:
+    if PdfReader is None:
+        return (
+            "PDF text extraction library (pypdf) is unavailable. "
+            "Please install pypdf or switch to a Vision-based PDF reader implementation."
+        )
+
+    reader = PdfReader(pdf_path)
+    chunks: List[str] = []
+    total = 0
+    for page_idx, page in enumerate(reader.pages, start=1):
+        try:
+            text = page.extract_text() or ""
+        except Exception:
+            text = ""
+        if text.strip():
+            chunk = f"[Page {page_idx}]\n{text.strip()}\n"
+            chunks.append(chunk)
+            total += len(chunk)
+            if total >= max_chars:
+                break
+
+    if not chunks:
+        return (
+            "No extractable text was found in the PDF. "
+            "For scanned PDFs, implement page-image rendering and pass images to Qwen-VL."
+        )
+    return "\n".join(chunks)[:max_chars]
+
+
+def write_tone_wav(text: str, out_path: str, seconds: float = 2.0, sample_rate: int = 16000) -> str:
+    # Mock TTS fallback: writes a short tone so the UI flow is testable without a TTS model.
+    freq = 440 + (len(text) % 220)
+    amplitude = 9000
+    frames = int(sample_rate * max(1.0, min(seconds, 8.0)))
+    with wave.open(out_path, "wb") as wf:
+        wf.setnchannels(1)
+        wf.setsampwidth(2)
+        wf.setframerate(sample_rate)
+        for i in range(frames):
+            sample = int(amplitude * math.sin(2 * math.pi * freq * (i / sample_rate)))
+            wf.writeframesraw(sample.to_bytes(2, byteorder="little", signed=True))
+    return out_path
+
+
+def render_pdf_pages_for_vl(pdf_path: str, max_pages: int, scale: float) -> List[str]:
+    if pdfium is None:
+        raise RuntimeError("pypdfium2 is required to render PDF pages for Qwen3-VL.")
+    doc = pdfium.PdfDocument(pdf_path)
+    page_count = len(doc)
+    if page_count == 0:
+        raise RuntimeError("Uploaded PDF has no pages.")
+
+    render_dir = TMP_DIR / f"pdf_pages_{uuid.uuid4().hex}"
+    render_dir.mkdir(exist_ok=True)
+
+    paths: List[str] = []
+    try:
+        for i in range(min(page_count, max_pages)):
+            page = doc[i]
+            pil = page.render(scale=scale).to_pil()
+            pil = pil.convert("RGB")
+            out_path = render_dir / f"page_{i+1:02d}.png"
+            pil.save(out_path, format="PNG")
+            paths.append(str(out_path))
+            close_fn = getattr(page, "close", None)
+            if callable(close_fn):
+                close_fn()
+    finally:
+        close_fn = getattr(doc, "close", None)
+        if callable(close_fn):
+            close_fn()
+
+    if not paths:
+        raise RuntimeError("Failed to render PDF pages for Qwen3-VL.")
+    return paths
+
+
+def image_file_to_data_url(image_path: str) -> str:
+    image_bytes = Path(image_path).read_bytes()
+    b64 = base64.b64encode(image_bytes).decode("ascii")
+    return f"data:image/png;base64,{b64}"
+
+
+def _api_headers() -> Dict[str, str]:
+    if not API_KEY:
+        raise RuntimeError("Missing API_KEY. Put it in .env or environment variables.")
+    return {
+        "Authorization": f"Bearer {API_KEY}",
+        "Content-Type": "application/json",
+    }
+
+
+def _require_api_url() -> str:
+    if not API_URL:
+        raise RuntimeError("Missing API_URL/API_UR. Put it in .env or environment variables.")
+    return API_URL.rstrip("/")
+
+
+def _dashscope_tts_url() -> str:
+    base = _require_api_url()
+    if "/compatible-mode/" in base:
+        root = base.split("/compatible-mode/", 1)[0]
+    elif base.endswith("/v1"):
+        root = base[:-3]
+    else:
+        root = base
+    return f"{root}/api/v1/services/aigc/multimodal-generation/generation"
+
+
+def _save_binary_audio(audio_bytes: bytes, out_path: str) -> str:
+    Path(out_path).write_bytes(audio_bytes)
+    return out_path
+
+
+def split_text_for_tts(text: str, max_len: int = 480) -> List[str]:
+    cleaned = re.sub(r"\s+", " ", (text or "")).strip()
+    if not cleaned:
+        return []
+    if len(cleaned) <= max_len:
+        return [cleaned]
+
+    # Prefer sentence-ish chunks, then hard-split as fallback.
+    pieces = re.split(r"(?<=[。！？!?；;:：\.])\s*", cleaned)
+    chunks: List[str] = []
+    buf = ""
+    for piece in pieces:
+        piece = piece.strip()
+        if not piece:
+            continue
+        if len(piece) > max_len:
+            if buf:
+                chunks.append(buf)
+                buf = ""
+            for i in range(0, len(piece), max_len):
+                chunks.append(piece[i:i + max_len])
+            continue
+        candidate = f"{buf} {piece}".strip() if buf else piece
+        if len(candidate) <= max_len:
+            buf = candidate
+        else:
+            chunks.append(buf)
+            buf = piece
+    if buf:
+        chunks.append(buf)
+    return chunks
+
+
+def concat_wav_files(wav_paths: List[str], out_path: str) -> str:
+    if not wav_paths:
+        raise RuntimeError("No WAV chunks to concatenate.")
+    if len(wav_paths) == 1:
+        return _save_binary_audio(Path(wav_paths[0]).read_bytes(), out_path)
+
+    params = None
+    frames: List[bytes] = []
+    for p in wav_paths:
+        with wave.open(str(p), "rb") as wf:
+            cur_params = (wf.getnchannels(), wf.getsampwidth(), wf.getframerate())
+            if params is None:
+                params = cur_params
+            elif cur_params != params:
+                raise RuntimeError("TTS WAV chunks have mismatched formats and cannot be concatenated.")
+            frames.append(wf.readframes(wf.getnframes()))
+
+    assert params is not None
+    with wave.open(out_path, "wb") as out:
+        out.setnchannels(params[0])
+        out.setsampwidth(params[1])
+        out.setframerate(params[2])
+        for f in frames:
+            out.writeframes(f)
+    return out_path
+
+
+class QwenPipelineEngine:
+    """
+    Gradio-facing backend for:
+    PDF -> lecture text -> MCQs -> TTS audio
+
+    This ships with a mock mode by default so the workflow is runnable immediately.
+    When USE_MOCK_MODELS=0, it calls remote APIs:
+    - VL: OpenAI-compatible /chat/completions (works with DashScope compatible-mode and vLLM-style APIs)
+    - TTS: DashScope multimodal generation API (returns audio URL)
+    """
+
+    def __init__(self) -> None:
+        self.mock_mode = USE_MOCK_MODELS
+        self.vl_loaded = False
+        self.tts_loaded = False
+        self._pdf_page_cache: Dict[str, List[str]] = {}
+
+    def ensure_vl_loaded(self) -> None:
+        if self.vl_loaded:
+            return
+        if self.mock_mode:
+            self.vl_loaded = True
+            return
+        _require_api_url()
+        if not API_KEY:
+            raise RuntimeError("Missing API_KEY for VL API calls.")
+        self.vl_loaded = True
+
+    def ensure_tts_loaded(self) -> None:
+        if self.tts_loaded:
+            return
+        if self.mock_mode:
+            self.tts_loaded = True
+            return
+        _require_api_url()
+        if not API_KEY:
+            raise RuntimeError("Missing API_KEY for TTS API calls.")
+        self.tts_loaded = True
+
+    def _mock_generate_lecture(self, pdf_excerpt: str) -> str:
+        excerpt = re.sub(r"\s+", " ", pdf_excerpt).strip()
+        excerpt = excerpt[:1000]
+        return (
+            "这是一段基于论文内容的课堂讲解（Mock 模式）。\n\n"
+            "1. 论文问题与背景：该工作试图解决一个具体任务中的效率/性能/泛化问题，核心动机通常是现有方法在成本、准确性或可解释性方面存在不足。\n"
+            "2. 核心方法：作者提出新的模型结构、训练策略或推理流程，并通过若干模块协同完成任务。\n"
+            "3. 实验与结果：论文通常会在标准数据集上与基线比较，并报告性能提升、效率改善或更稳定的表现。\n"
+            "4. 局限与适用场景：方法可能依赖特定数据分布、计算资源或任务设定，迁移到新领域需要额外验证。\n\n"
+            f"论文节选（用于生成讲解）: {excerpt}"
+        )
+
+    def _mock_generate_mcqs(self, lecture_text: str) -> List[MCQItem]:
+        base_questions = [
+            MCQItem(
+                question="这篇论文最主要想解决的问题通常属于下列哪一类？",
+                options=["现有方法存在性能或效率瓶颈", "如何设计数据库索引", "如何搭建前端页面", "如何压缩视频文件"],
+                answer="A",
+                explanation="课程论文阅读类任务通常围绕已有方法不足展开，作者提出新方法来提升性能、效率或鲁棒性。",
+            ),
+            MCQItem(
+                question="在讲解论文方法时，最合理的组织方式是什么？",
+                options=["按模块或步骤解释输入到输出流程", "只列出参考文献", "只展示实验表格不解释方法", "只讲结论不讲背景"],
+                answer="A",
+                explanation="课堂讲解需要结构化地说明方法流程，这样听众才能理解论文如何从问题走到解法。",
+            ),
+            MCQItem(
+                question="生成选择题时，为什么需要同时给出答案和解析？",
+                options=["便于交互反馈与纠错教学", "只是为了让 JSON 更长", "因为 Gradio 要求必须有解析", "为了减少题目数量"],
+                answer="A",
+                explanation="答案和解析是教学闭环的一部分，错误时给出解析能帮助用户理解常见误区。",
+            ),
+            MCQItem(
+                question="如果论文很长，一次性输入模型的风险是什么？",
+                options=["上下文超长导致成本高、信息丢失或失败", "模型会自动变得更准确", "TTS 音频会变短", "PDF 文件会损坏"],
+                answer="A",
+                explanation="长文档通常需要分块总结再汇总，避免超出上下文窗口并降低生成质量波动。",
+            ),
+            MCQItem(
+                question="在这个 Demo 流程中，Qwen TTS 的作用是什么？",
+                options=["把讲解与错题解析转成语音输出", "把 PDF 转成图片", "训练 Qwen3-VL-8B", "生成新的选择题答案"],
+                answer="A",
+                explanation="TTS 用于将文本讲解/解析语音化，提高交互演示效果和可访问性。",
+            ),
+        ]
+        return base_questions
+
+    def _get_pdf_page_images(self, pdf_path: str) -> List[str]:
+        cache_key = str(Path(pdf_path).resolve())
+        cached = self._pdf_page_cache.get(cache_key)
+        if cached and all(Path(p).exists() for p in cached):
+            return cached
+        page_paths = render_pdf_pages_for_vl(
+            pdf_path,
+            max_pages=QWEN_VL_MAX_PAGES,
+            scale=QWEN_VL_RENDER_SCALE,
+        )
+        self._pdf_page_cache[cache_key] = page_paths
+        return page_paths
+
+    def _chat_completions(self, messages: List[Dict[str, Any]], max_tokens: int) -> str:
+        url = f"{_require_api_url()}/chat/completions"
+        payload: Dict[str, Any] = {
+            "model": CHAT_MODEL_ID,
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "stream": False,
+        }
+        resp = requests.post(url, headers=_api_headers(), json=payload, timeout=API_TIMEOUT_SEC)
+        if resp.status_code >= 400:
+            raise RuntimeError(f"VL API error {resp.status_code}: {resp.text[:1000]}")
+        data = resp.json()
+        choices = data.get("choices") or []
+        if not choices:
+            raise RuntimeError(f"VL API returned no choices: {data}")
+        content = choices[0].get("message", {}).get("content", "")
+        if isinstance(content, str):
+            return content.strip()
+        if isinstance(content, list):
+            parts: List[str] = []
+            for item in content:
+                if isinstance(item, dict) and item.get("type") in {"text", "output_text"}:
+                    parts.append(str(item.get("text") or item.get("content") or ""))
+            return "\n".join([p for p in parts if p]).strip()
+        return str(content).strip()
+
+    def _real_generate_text_from_pdf(self, pdf_path: str, prompt: str, max_tokens: Optional[int] = None) -> str:
+        page_image_paths = self._get_pdf_page_images(pdf_path)
+        content: List[Dict[str, Any]] = []
+        for p in page_image_paths:
+            content.append({"type": "image_url", "image_url": {"url": image_file_to_data_url(p)}})
+        content.append({"type": "text", "text": prompt})
+        messages = [{"role": "user", "content": content}]
+        return self._chat_completions(messages, max_tokens=max_tokens or QWEN_VL_MAX_NEW_TOKENS)
+
+    def _real_tts_single(self, text: str, out_path: str) -> str:
+        if not text.strip():
+            return write_tone_wav("empty", out_path)
+        openai_url = f"{_require_api_url()}/audio/speech"
+        openai_payload = {
+            "model": TTS_MODEL_ID,
+            "input": text,
+            "voice": TTS_SPEAKER,
+            "format": TTS_FORMAT,
+        }
+        openai_resp = requests.post(
+            openai_url,
+            headers=_api_headers(),
+            json=openai_payload,
+            timeout=API_TIMEOUT_SEC,
+        )
+        content_type = openai_resp.headers.get("content-type", "")
+        if openai_resp.status_code < 400 and "application/json" not in content_type.lower():
+            return _save_binary_audio(openai_resp.content, out_path)
+
+        # DashScope fallback: multimodal generation returns an audio URL in JSON.
+        payload = {
+            "model": TTS_MODEL_ID,
+            "input": {"text": text},
+            "parameters": {"voice": TTS_SPEAKER, "format": TTS_FORMAT},
+        }
+        resp = requests.post(
+            _dashscope_tts_url(),
+            headers=_api_headers(),
+            json=payload,
+            timeout=API_TIMEOUT_SEC,
+        )
+        if resp.status_code >= 400:
+            err1 = openai_resp.text[:500] if openai_resp.text else ""
+            err2 = resp.text[:500] if resp.text else ""
+            raise RuntimeError(
+                f"TTS API failed. openai-compatible: {openai_resp.status_code} {err1}; "
+                f"dashscope: {resp.status_code} {err2}"
+            )
+        data = resp.json()
+        audio_url = (
+            (((data.get("output") or {}).get("audio") or {}).get("url"))
+            or (((data.get("output") or {}).get("audio_url")))
+        )
+        if not audio_url:
+            raise RuntimeError(f"TTS API returned no audio URL: {data}")
+        audio_resp = requests.get(audio_url, timeout=API_TIMEOUT_SEC)
+        if audio_resp.status_code >= 400:
+            raise RuntimeError(f"Failed to download TTS audio {audio_resp.status_code}: {audio_resp.text[:500]}")
+        return _save_binary_audio(audio_resp.content, out_path)
+
+    def _real_tts(self, text: str, out_path: str) -> str:
+        chunks = split_text_for_tts(text, max_len=480)
+        if not chunks:
+            return write_tone_wav("empty", out_path)
+        if len(chunks) == 1:
+            return self._real_tts_single(chunks[0], out_path)
+
+        chunk_paths: List[str] = []
+        for idx, chunk in enumerate(chunks, start=1):
+            chunk_path = str(TMP_DIR / f"tts_chunk_{idx}_{uuid.uuid4().hex}.wav")
+            chunk_paths.append(self._real_tts_single(chunk, chunk_path))
+        return concat_wav_files(chunk_paths, out_path)
+
+    @spaces.GPU
+    def build_lesson_and_quiz(self, pdf_path: str, character_cfg: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        self.ensure_vl_loaded()
+        pdf_excerpt = extract_pdf_text(pdf_path)
+        cfg = character_cfg or get_character_config(None)
+        lecture_template = cfg.get("lecture_prompt_template", DEFAULT_LECTURE_PROMPT_TEMPLATE)
+        mcq_template = cfg.get("mcq_prompt_template", DEFAULT_MCQ_PROMPT_TEMPLATE)
+        mcq_retry_template = cfg.get("mcq_retry_prompt_template", DEFAULT_MCQ_RETRY_PROMPT_TEMPLATE)
+
+        if self.mock_mode:
+            lecture_text = self._mock_generate_lecture(pdf_excerpt)
+            mcqs = self._mock_generate_mcqs(lecture_text)
+        else:
+            lecture_prompt = render_prompt_template(str(lecture_template), pdf_excerpt)
+            lecture_text = self._real_generate_text_from_pdf(pdf_path, lecture_prompt, max_tokens=QWEN_VL_MAX_NEW_TOKENS)
+            quiz_prompt = render_prompt_template(str(mcq_template), pdf_excerpt)
+            raw_mcq_json = self._real_generate_text_from_pdf(pdf_path, quiz_prompt, max_tokens=QWEN_VL_MCQ_MAX_NEW_TOKENS)
+            try:
+                mcqs = parse_mcq_json(raw_mcq_json)
+            except json.JSONDecodeError:
+                retry_prompt = render_prompt_template(str(mcq_retry_template), pdf_excerpt)
+                retry_raw = self._real_generate_text_from_pdf(
+                    pdf_path,
+                    retry_prompt,
+                    max_tokens=QWEN_VL_MCQ_MAX_NEW_TOKENS,
+                )
+                mcqs = parse_mcq_json(retry_raw)
+
+        return {
+            "lecture_text": lecture_text,
+            "mcqs": [asdict(q) for q in mcqs],
+            "pdf_excerpt": pdf_excerpt,
+        }
+
+    @spaces.GPU
+    def build_lecture(self, pdf_path: str, character_cfg: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        self.ensure_vl_loaded()
+        pdf_excerpt = extract_pdf_text(pdf_path)
+        cfg = character_cfg or get_character_config(None)
+        lecture_template = cfg.get("lecture_prompt_template", DEFAULT_LECTURE_PROMPT_TEMPLATE)
+
+        if self.mock_mode:
+            lecture_text = self._mock_generate_lecture(pdf_excerpt)
+        else:
+            lecture_prompt = render_prompt_template(str(lecture_template), pdf_excerpt)
+            lecture_text = self._real_generate_text_from_pdf(pdf_path, lecture_prompt, max_tokens=QWEN_VL_MAX_NEW_TOKENS)
+
+        return {
+            "lecture_text": lecture_text,
+            "pdf_excerpt": pdf_excerpt,
+        }
+
+    @spaces.GPU
+    def build_mcqs(self, pdf_path: str, pdf_excerpt: str, character_cfg: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
+        self.ensure_vl_loaded()
+        cfg = character_cfg or get_character_config(None)
+        mcq_template = cfg.get("mcq_prompt_template", DEFAULT_MCQ_PROMPT_TEMPLATE)
+        mcq_retry_template = cfg.get("mcq_retry_prompt_template", DEFAULT_MCQ_RETRY_PROMPT_TEMPLATE)
+
+        if self.mock_mode:
+            mcqs = self._mock_generate_mcqs(pdf_excerpt)
+            return [asdict(q) for q in mcqs]
+
+        quiz_prompt = render_prompt_template(str(mcq_template), pdf_excerpt)
+        raw_mcq_json = self._real_generate_text_from_pdf(pdf_path, quiz_prompt, max_tokens=QWEN_VL_MCQ_MAX_NEW_TOKENS)
+        try:
+            mcqs = parse_mcq_json(raw_mcq_json)
+        except json.JSONDecodeError:
+            retry_prompt = render_prompt_template(str(mcq_retry_template), pdf_excerpt)
+            retry_raw = self._real_generate_text_from_pdf(
+                pdf_path,
+                retry_prompt,
+                max_tokens=QWEN_VL_MCQ_MAX_NEW_TOKENS,
+            )
+            mcqs = parse_mcq_json(retry_raw)
+        return [asdict(q) for q in mcqs]
+
+    @spaces.GPU
+    def synthesize_tts(self, text: str, name_prefix: str = "audio") -> str:
+        self.ensure_tts_loaded()
+        out_path = str(TMP_DIR / f"{name_prefix}_{uuid.uuid4().hex}.wav")
+        if self.mock_mode:
+            return write_tone_wav(text, out_path)
+        return self._real_tts(text, out_path)
+
+
+def parse_mcq_json(raw: str) -> List[MCQItem]:
+    cleaned = strip_code_fence(raw)
+    try:
+        payload = json.loads(cleaned)
+    except json.JSONDecodeError:
+        start = cleaned.find("{")
+        end = cleaned.rfind("}")
+        if start != -1 and end != -1 and end > start:
+            payload = json.loads(cleaned[start:end + 1])
+        else:
+            raise
+    questions = payload.get("questions", [])
+    parsed: List[MCQItem] = []
+    for item in questions[:5]:
+        q = str(item.get("question", "")).strip()
+        options = [str(x).strip() for x in item.get("options", [])][:4]
+        answer = str(item.get("answer", "")).strip().upper()
+        explanation = str(item.get("explanation", "")).strip()
+        if len(options) != 4:
+            continue
+        if answer not in {"A", "B", "C", "D"}:
+            continue
+        if not q or not explanation:
+            continue
+        parsed.append(MCQItem(question=q, options=options, answer=answer, explanation=explanation))
+    if len(parsed) != 5:
+        raise ValueError(f"Expected 5 MCQs, got {len(parsed)}")
+    return parsed
+
+
+engine = QwenPipelineEngine()
+
+
+def get_current_mcq(state: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    idx = state.get("current_index", 0)
+    mcqs = state.get("mcqs", [])
+    if not mcqs or idx < 0 or idx >= len(mcqs):
+        return None
+    return mcqs[idx]
+
+
+def format_question_block(state: Dict[str, Any]) -> str:
+    mcq = get_current_mcq(state)
+    if mcq is None:
+        if state.get("completed"):
+            total = len(state.get("mcqs", []))
+            return f"### Quiz Completed\nScore: {state.get('score', 0)} / {total}"
+        return "### No question loaded"
+    qn = state["current_index"] + 1
+    total = len(state["mcqs"])
+    return f"### Question {qn}/{total}\n\n{mcq['question']}"
+
+
+def current_choices(state: Dict[str, Any]) -> List[str]:
+    mcq = get_current_mcq(state)
+    if mcq is None:
+        return []
+    labels = ["A", "B", "C", "D"]
+    return [f"{labels[i]}. {opt}" for i, opt in enumerate(mcq["options"])]
+
+
+def score_text(state: Dict[str, Any]) -> str:
+    total = len(state.get("mcqs", []))
+    return f"Score: {state.get('score', 0)} / {total}"
+
+
+def reset_ui_from_state(
+    state: Dict[str, Any],
+    feedback: str = "",
+    *,
+    results_visible: bool = True,
+    loading_visible: bool = False,
+    loading_text: str = "正在生成中，请稍候...",
+):
+    quiz_ready = bool(state.get("mcqs"))
+    current_page = state.get("current_page", "explain")
+    show_explain_page = results_visible and current_page != "exam"
+    show_exam_page = results_visible and current_page == "exam"
+    next_visible = bool(state.get("awaiting_next_after_wrong"))
+    submit_interactive = quiz_ready and not state.get("completed", False)
+    radio_interactive = submit_interactive and not state.get("awaiting_next_after_wrong", False)
+    lecture_tts_ready = bool(state.get("lecture_text"))
+    explanation_tts_ready = bool(state.get("last_explanation_tts_text"))
+    if state.get("completed"):
+        next_visible = False
+        radio_interactive = False
+    return (
+        state,
+        gr.update(value=loading_text, visible=loading_visible),
+        gr.update(visible=show_explain_page),
+        gr.update(visible=show_exam_page),
+        gr.update(),
+        state.get("status", "Idle"),
+        state.get("lecture_text", ""),
+        state.get("lecture_audio_path", None),
+        gr.update(interactive=lecture_tts_ready),
+        gr.update(visible=lecture_tts_ready, interactive=lecture_tts_ready),
+        gr.update(value=format_question_block(state), visible=quiz_ready),
+        gr.update(choices=current_choices(state), value=None, interactive=radio_interactive),
+        score_text(state),
+        feedback,
+        state.get("explanation_audio_path", None),
+        gr.update(visible=explanation_tts_ready, interactive=explanation_tts_ready),
+        gr.update(visible=next_visible),
+        gr.update(interactive=submit_interactive),
+        gr.update(interactive=quiz_ready),
+    )
+
+
+def process_pdf(pdf_file: Optional[str], character_id: str, state: Dict[str, Any]):
+    state = new_session_state()
+    state["character_id"] = character_id or DEFAULT_CHARACTER_ID
+    if not pdf_file:
+        state["status"] = "Please upload a PDF first."
+        yield reset_ui_from_state(state, feedback="Upload a PDF to start.", results_visible=False, loading_visible=False)
+        return
+
+    state["status"] = "正在生成中..."
+    yield reset_ui_from_state(
+        state,
+        feedback="正在读取论文并生成讲解与题目，请稍候...",
+        results_visible=False,
+        loading_visible=True,
+        loading_text="正在生成中，请稍候...",
+    )
+    try:
+        result = engine.build_lecture(pdf_file, get_character_config(state["character_id"]))
+        lecture_text = result["lecture_text"]
+        pdf_excerpt = result["pdf_excerpt"]
+
+        state["lecture_text"] = lecture_text
+        state["lecture_audio_path"] = None
+        state["explanation_audio_path"] = None
+        state["last_explanation_tts_text"] = ""
+        state["pdf_path"] = pdf_file
+        state["pdf_excerpt"] = pdf_excerpt
+        state["current_page"] = "explain"
+        state["mcqs"] = []
+        state["current_index"] = 0
+        state["score"] = 0
+        state["awaiting_next_after_wrong"] = False
+        state["completed"] = False
+        state["status"] = "Lecture generated."
+        yield reset_ui_from_state(
+            state,
+            feedback="Lecture is ready. Click 'Play Lecture Audio' if needed, then press 'Exam' to generate MCQs.",
+            results_visible=True,
+            loading_visible=False,
+        )
+    except Exception as exc:
+        state["status"] = "Failed during generation."
+        state["lecture_text"] = f"Error: {type(exc).__name__}: {exc}"
+        state["current_page"] = "explain"
+        yield reset_ui_from_state(
+            state,
+            feedback=f"Error: {type(exc).__name__}: {exc}",
+            results_visible=True,
+            loading_visible=False,
+        )
+
+
+def submit_answer(choice: Optional[str], state: Dict[str, Any]):
+    if not state.get("mcqs"):
+        state["status"] = "No quiz loaded."
+        return reset_ui_from_state(state, feedback="Load a PDF first.")
+    if state.get("completed"):
+        return reset_ui_from_state(state, feedback="Quiz already completed.")
+    if state.get("awaiting_next_after_wrong"):
+        return reset_ui_from_state(state, feedback="Click Next Question to continue.")
+    if not choice:
+        return reset_ui_from_state(state, feedback="Please select an option.")
+
+    mcq = get_current_mcq(state)
+    if mcq is None:
+        state["status"] = "No current question."
+        return reset_ui_from_state(state, feedback="No current question.")
+
+    selected_label = choice.split(".", 1)[0].strip().upper()
+    correct_label = str(mcq["answer"]).upper()
+
+    if selected_label == correct_label:
+        state["score"] += 1
+        state["last_explanation_tts_text"] = ""
+        state["explanation_audio_path"] = None
+        state["status"] = "Correct answer."
+        if state["current_index"] >= len(state["mcqs"]) - 1:
+            state["completed"] = True
+            state["status"] = "Quiz completed."
+            return reset_ui_from_state(
+                state,
+                feedback=f"Correct. Quiz finished. Final score: {state['score']} / {len(state['mcqs'])}.",
+            )
+
+        state["current_index"] += 1
+        return reset_ui_from_state(state, feedback="Correct. Moving to the next question.")
+
+    correct_idx = ["A", "B", "C", "D"].index(correct_label)
+    correct_choice_display = f"{correct_label}. {mcq['options'][correct_idx]}"
+    explanation = mcq["explanation"]
+    state["last_explanation_tts_text"] = explanation
+    state["explanation_audio_path"] = None
+    state["awaiting_next_after_wrong"] = True
+    state["status"] = "Incorrect answer. Review explanation, then continue."
+    feedback = (
+        f"Incorrect.\n\nCorrect answer: {correct_choice_display}\n\nExplanation: {explanation}\n\n"
+        "Click 'Play Explanation Audio' to generate speech for the explanation."
+    )
+    return reset_ui_from_state(state, feedback=feedback)
+
+
+def next_question(state: Dict[str, Any]):
+    if not state.get("mcqs"):
+        return reset_ui_from_state(state, feedback="Load a PDF first.")
+    if state.get("completed"):
+        return reset_ui_from_state(state, feedback="Quiz already completed.")
+    if not state.get("awaiting_next_after_wrong"):
+        return reset_ui_from_state(state, feedback="Use Submit Answer for the current question.")
+
+    if state["current_index"] >= len(state["mcqs"]) - 1:
+        state["completed"] = True
+        state["awaiting_next_after_wrong"] = False
+        state["last_explanation_tts_text"] = ""
+        state["explanation_audio_path"] = None
+        state["status"] = "Quiz completed."
+        return reset_ui_from_state(
+            state,
+            feedback=f"Quiz finished. Final score: {state['score']} / {len(state['mcqs'])}.",
+        )
+
+    state["current_index"] += 1
+    state["awaiting_next_after_wrong"] = False
+    state["last_explanation_tts_text"] = ""
+    state["explanation_audio_path"] = None
+    state["status"] = "Next question loaded."
+    return reset_ui_from_state(state, feedback="Moved to the next question.")
+
+
+def restart_quiz(state: Dict[str, Any]):
+    if not state.get("mcqs"):
+        return reset_ui_from_state(new_session_state(), feedback="Load a PDF first.")
+    state["current_index"] = 0
+    state["score"] = 0
+    state["awaiting_next_after_wrong"] = False
+    state["completed"] = False
+    state["last_explanation_tts_text"] = ""
+    state["explanation_audio_path"] = None
+    state["status"] = "Quiz restarted."
+    return reset_ui_from_state(state, feedback="Quiz restarted.")
+
+
+def go_to_exam_page(state: Dict[str, Any]):
+    if not state.get("lecture_text"):
+        state["status"] = "No lecture loaded."
+        yield reset_ui_from_state(state, feedback="Generate lecture first.", results_visible=False, loading_visible=False)
+        return
+
+    state["current_page"] = "exam"
+    state["exam_character_id"] = None
+    state["mcqs"] = []
+    state["current_index"] = 0
+    state["score"] = 0
+    state["awaiting_next_after_wrong"] = False
+    state["completed"] = False
+    state["last_explanation_tts_text"] = ""
+    state["explanation_audio_path"] = None
+    state["status"] = "请选择角色以生成 MCQ"
+    yield reset_ui_from_state(
+        state,
+        feedback="",
+        results_visible=True,
+        loading_visible=False,
+    )
+
+
+def generate_exam_mcq(selected_character_id: Optional[str], state: Dict[str, Any]):
+    if not state.get("lecture_text"):
+        state["status"] = "No lecture loaded."
+        yield reset_ui_from_state(state, feedback="Generate lecture first.", results_visible=False, loading_visible=False)
+        return
+    if not selected_character_id:
+        state["status"] = "请选择角色以生成 MCQ"
+        yield reset_ui_from_state(state, feedback="", results_visible=True, loading_visible=False)
+        return
+
+    state["current_page"] = "exam"
+    state["exam_character_id"] = selected_character_id
+    state["status"] = "正在生成 MCQ..."
+    state["last_explanation_tts_text"] = ""
+    state["explanation_audio_path"] = None
+    state["mcqs"] = []
+    yield reset_ui_from_state(
+        state,
+        feedback="",
+        results_visible=False,
+        loading_visible=True,
+        loading_text="正在生成 MCQ，请稍候...",
+    )
+
+    try:
+        pdf_path = state.get("pdf_path")
+        pdf_excerpt = state.get("pdf_excerpt", "")
+        if not pdf_path:
+            raise RuntimeError("PDF path missing in session state.")
+        mcqs = engine.build_mcqs(pdf_path, pdf_excerpt, get_character_config(selected_character_id))
+        state["mcqs"] = mcqs
+        state["current_index"] = 0
+        state["score"] = 0
+        state["awaiting_next_after_wrong"] = False
+        state["completed"] = False
+        state["current_page"] = "exam"
+        state["status"] = "MCQ generated."
+        yield reset_ui_from_state(
+            state,
+            feedback="",
+            results_visible=True,
+            loading_visible=False,
+        )
+    except Exception as exc:
+        state["current_page"] = "exam"
+        state["status"] = "Failed during MCQ generation."
+        yield reset_ui_from_state(
+            state,
+            feedback=f"Error: {type(exc).__name__}: {exc}",
+            results_visible=True,
+            loading_visible=False,
+        )
+
+
+def on_generate_click(pdf_file: Optional[str], explain_character_id: str, exam_character_id: Optional[str], state: Dict[str, Any]):
+    current_page = state.get("current_page", "explain")
+    if current_page == "exam":
+        yield from generate_exam_mcq(exam_character_id, state)
+        return
+    yield from process_pdf(pdf_file, explain_character_id, state)
+
+
+def go_to_explain_page(state: Dict[str, Any]):
+    state["current_page"] = "explain"
+    return reset_ui_from_state(state, feedback=state.get("status", "Explain page"))
+
+
+def on_character_change(character_id: str, state: Dict[str, Any]):
+    cfg = get_character_config(character_id)
+    state["character_id"] = cfg["id"]
+    state["current_page"] = "explain"
+    state["lecture_audio_path"] = None
+    state["explanation_audio_path"] = None
+    state["last_explanation_tts_text"] = ""
+    # Keep generated content if user wants to compare, but hide result pages until next generate.
+    return (
+        state,
+        build_character_header_html(cfg["id"]),
+        build_chat_avatar_html(cfg["id"]),
+        build_chat_meta_html(cfg["id"]),
+        gr.update(visible=False),
+        gr.update(visible=False),
+        gr.update(visible=False),
+        "Character switched. Upload PDF and click Generate.",
+    )
+
+
+def on_exam_character_select(character_id: Optional[str], state: Dict[str, Any]):
+    state["exam_character_id"] = character_id
+    state["status"] = "Exam character selected. Click Generate to create MCQs."
+    return state, state["status"]
+
+
+def play_lecture_audio(state: Dict[str, Any]):
+    if not state.get("lecture_text"):
+        state["status"] = "No lecture text available."
+        return state, state["status"], state.get("lecture_audio_path"), "Generate lecture first."
+    try:
+        state["status"] = "Generating lecture audio..."
+        state["lecture_audio_path"] = engine.synthesize_tts(state["lecture_text"], name_prefix="lecture")
+        state["status"] = "Lecture audio ready."
+        return state, state["status"], state["lecture_audio_path"], "Lecture audio generated."
+    except Exception as exc:
+        state["status"] = "Lecture audio generation failed."
+        return state, state["status"], state.get("lecture_audio_path"), f"TTS error: {type(exc).__name__}: {exc}"
+
+
+def play_explanation_audio(state: Dict[str, Any]):
+    text = state.get("last_explanation_tts_text", "")
+    if not text:
+        state["status"] = "No explanation available for TTS."
+        return state, state["status"], state.get("explanation_audio_path"), "Answer a question incorrectly first."
+    try:
+        state["status"] = "Generating explanation audio..."
+        state["explanation_audio_path"] = engine.synthesize_tts(text, name_prefix="explanation")
+        state["status"] = "Explanation audio ready."
+        return state, state["status"], state["explanation_audio_path"], "Explanation audio generated."
+    except Exception as exc:
+        state["status"] = "Explanation audio generation failed."
+        return state, state["status"], state.get("explanation_audio_path"), f"TTS error: {type(exc).__name__}: {exc}"
+
+
+def build_css() -> str:
+    bg_css = ""
+
+    return f"""
+@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Inter:wght@400;500;600;700&display=swap');
+
+html, body {{
+  min-height: 100%;
+  height: auto;
+}}
+body {{
+  background-color: #ffffff !important;
+  font-family: "Inter", sans-serif !important;
+}}
+.app, #root, .gradio-container, .gradio-container > .main {{
+  background: transparent !important;
+}}
+.gradio-container {{
+  position: relative;
+  z-index: 1;
+}}
+.gradio-container .block,
+.gradio-container .panel,
+.gradio-container .gr-box,
+.gradio-container .gr-form,
+.gradio-container .gr-group {{
+  background: rgba(14, 16, 24, 0.62) !important;
+  backdrop-filter: blur(2px);
+  border-color: rgba(255, 255, 255, 0.08) !important;
+}}
+.gradio-container textarea,
+.gradio-container input,
+.gradio-container .wrap,
+.gradio-container .svelte-1ipelgc {{
+  background-color: transparent !important;
+}}
+.gradio-container textarea,
+.gradio-container input {{
+  box-shadow: none !important;
+  color: #eef1f6 !important;
+}}
+.gradio-container label,
+.gradio-container .prose,
+.gradio-container .prose p,
+.gradio-container .prose code,
+.gradio-container .prose strong {{
+  color: #eef1f6 !important;
+}}
+#page-shell {{
+  min-height: 100vh;
+  padding: 2rem 1.2rem 9rem 1.2rem;
+  max-width: 980px;
+  margin: 0 auto;
+}}
+#page-shell .hero {{
+  text-align: center;
+  margin: 1.2rem 0 1.8rem 0;
+}}
+#page-shell .hero-title {{
+  margin: 0;
+  color: #f4f6fb;
+  letter-spacing: 0.01em;
+  font-family: "Instrument Serif", Georgia, serif;
+  font-weight: 400;
+  font-size: clamp(2.05rem, 3vw, 2.75rem);
+  text-shadow: 0 1px 8px rgba(0,0,0,0.35);
+}}
+#page-shell .hero-sub {{
+  margin: 0.65rem 0 0 0;
+  color: rgba(241, 244, 251, 0.88);
+  font-size: 0.98rem;
+}}
+#page-shell .hero-note {{
+  margin-top: 0.5rem;
+  color: rgba(241, 244, 251, 0.72);
+  font-size: 0.92rem;
+}}
+#character-card {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+}}
+.char-wrap {{
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.45rem;
+  margin-bottom: 0.8rem;
+}}
+.char-avatar {{
+  width: 84px;
+  height: 84px;
+  border-radius: 999px;
+  object-fit: cover;
+  border: 1px solid rgba(255,255,255,0.18);
+  box-shadow: 0 8px 26px rgba(0,0,0,0.28);
+}}
+.char-name {{
+  color: #f6f7fb;
+  font-weight: 600;
+  font-size: 1.05rem;
+}}
+.char-tag {{
+  color: rgba(240,243,250,0.78);
+  font-size: 0.95rem;
+}}
+.char-byline {{
+  color: rgba(240,243,250,0.58);
+  font-size: 0.85rem;
+}}
+#character-select-wrap {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  margin: -0.1rem auto 0.8rem auto !important;
+  max-width: 220px !important;
+  min-width: 0 !important;
+  padding: 0 !important;
+}}
+#page-shell .flat-select,
+#page-shell .flat-select > div,
+#page-shell .flat-select .block,
+#page-shell .flat-select .gradio-dropdown {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  padding: 0 !important;
+}}
+#character-select-wrap,
+#character-select-wrap > div,
+#character-select-wrap > div > div,
+#character-select-wrap .wrap,
+#character-select-wrap input,
+#character-select-wrap button {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+}}
+#character-select-wrap .wrap {{
+  justify-content: center;
+  padding: 0 !important;
+  min-height: 20px !important;
+}}
+#character-select-wrap input,
+#character-select-wrap [role="combobox"],
+#character-select-wrap [role="combobox"] {{
+  font-family: "Inter", sans-serif !important;
+  font-size: 0.88rem !important;
+  font-weight: 400 !important;
+  color: rgba(240,243,250,0.78) !important;
+  text-align: center !important;
+}}
+#character-select-wrap [role="combobox"] {{
+  min-height: 20px !important;
+  padding: 0 !important;
+}}
+#character-select-wrap [role="listbox"],
+[data-testid="dropdown-menu"] {{
+  background: rgba(20, 22, 30, 0.96) !important;
+  border: 1px solid rgba(255,255,255,0.12) !important;
+  box-shadow: 0 12px 30px rgba(0,0,0,0.35) !important;
+  z-index: 9999 !important;
+}}
+[data-testid="dropdown-menu"] * {{
+  color: #eef1f6 !important;
+}}
+#character-select-wrap svg,
+#character-select-wrap [data-icon] {{
+  opacity: 0.65 !important;
+  color: rgba(240,243,250,0.78) !important;
+}}
+#character-select-wrap {{
+  display: flex !important;
+  justify-content: center !important;
+}}
+#character-select-wrap .wrap {{
+  display: flex !important;
+  gap: 0.35rem !important;
+  flex-wrap: wrap !important;
+  justify-content: center !important;
+}}
+#character-select-wrap label {{
+  background: transparent !important;
+  border: 1px solid rgba(255,255,255,0.14) !important;
+  border-radius: 999px !important;
+  padding: 0.18rem 0.65rem !important;
+  min-height: 0 !important;
+}}
+#character-select-wrap label span {{
+  color: rgba(240,243,250,0.78) !important;
+  font-size: 0.88rem !important;
+}}
+#character-select-wrap input[type="radio"] {{
+  display: none !important;
+}}
+#character-select-wrap label:has(input[type="radio"]:checked) {{
+  background: rgba(255,255,255,0.10) !important;
+  border-color: rgba(255,255,255,0.22) !important;
+}}
+#character-select-wrap label:has(input[type="radio"]:checked) span {{
+  color: #ffffff !important;
+}}
+#gen-loading {{
+  text-align: center;
+  padding: 14px 18px;
+  margin: 0 0 12px 0;
+  color: #f2f3f8;
+  background: rgba(255,255,255,0.08);
+  border: 1px solid rgba(255,255,255,0.12);
+  border-radius: 12px;
+  backdrop-filter: blur(3px);
+}}
+#results-panel {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  padding: 0 !important;
+  gap: 0.75rem;
+}}
+#chat-row {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  align-items: flex-start !important;
+}}
+#chat-avatar-col {{
+  max-width: 54px !important;
+  min-width: 54px !important;
+}}
+.mini-avatar {{
+  width: 34px;
+  height: 34px;
+  border-radius: 999px;
+  object-fit: cover;
+  border: 1px solid rgba(255,255,255,0.16);
+}}
+#chat-main {{
+  flex: 1;
+}}
+#chat-meta {{
+  margin: 0 0 0.45rem 0;
+  color: rgba(245,247,252,0.95);
+  font-size: 0.95rem;
+  font-weight: 600;
+}}
+#chat-meta .pill {{
+  margin-left: 0.5rem;
+  padding: 0.08rem 0.45rem;
+  border-radius: 999px;
+  background: rgba(255,255,255,0.1);
+  color: rgba(255,255,255,0.78);
+  font-size: 0.78rem;
+}}
+#lecture-wrap {{
+  background: rgba(33, 36, 46, 0.82) !important;
+  border: 1px solid rgba(255,255,255,0.06) !important;
+  border-radius: 20px !important;
+  padding: 0.35rem 0.45rem !important;
+}}
+#lecture-wrap textarea {{
+  font-style: italic;
+  line-height: 1.45 !important;
+  color: rgba(244,246,251,0.95) !important;
+}}
+#lecture-actions {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  margin-top: 0.35rem !important;
+}}
+#exam-entry-wrap {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  margin-top: 0.25rem !important;
+}}
+#bottom-composer {{
+  position: fixed;
+  left: 50%;
+  transform: translateX(-50%);
+  bottom: 18px;
+  width: min(860px, calc(100vw - 28px));
+  z-index: 50;
+  background: rgba(24, 26, 34, 0.88);
+  border: 1px solid rgba(255,255,255,0.08);
+  border-radius: 999px;
+  box-shadow: 0 16px 40px rgba(0,0,0,0.22);
+  backdrop-filter: blur(10px);
+  padding: 8px 10px;
+}}
+#bottom-composer .wrap {{
+  border: none !important;
+}}
+#bottom-composer .block {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+}}
+#bottom-composer button {{
+  border-radius: 999px !important;
+}}
+#generate-btn button {{
+  min-height: 38px !important;
+  height: 38px !important;
+  padding: 0 18px !important;
+  font-size: 0.9rem !important;
+  line-height: 1 !important;
+  min-width: 132px !important;
+}}
+#pdf-uploader {{
+  min-height: 42px;
+}}
+#pdf-uploader .wrap {{
+  min-height: 42px !important;
+  padding: 4px 10px !important;
+}}
+#pdf-uploader [data-testid="file-upload-dropzone"] {{
+  min-height: 42px !important;
+  height: 42px !important;
+  padding: 2px 8px !important;
+  display: flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+}}
+#pdf-uploader [data-testid="file-upload-dropzone"] * {{
+  font-size: 0.88rem !important;
+}}
+#status-wrap, #quiz-wrap, #tts-wrap, #explain-wrap {{
+  background: rgba(18, 20, 28, 0.58) !important;
+  border-radius: 16px !important;
+}}
+#exam-page {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  padding: 0 !important;
+}}
+#exam-nav {{
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  justify-content: space-between;
+  align-items: center;
+}}
+.container {{max-width: 980px; margin: 0 auto;}}
+.mono {{font-family: ui-monospace, Menlo, Consolas, monospace;}}
+{bg_css}
+"""
+
+
+CSS = build_css()
+
+
+def _image_data_url(path: Path) -> str:
+    if not path.exists():
+        return ""
+    mime = "image/jpeg" if path.suffix.lower() in {".jpg", ".jpeg"} else "image/png"
+    return f"data:{mime};base64," + base64.b64encode(path.read_bytes()).decode("ascii")
+
+
+def build_character_header_html(character_id: Optional[str] = None) -> str:
+    cfg = get_character_config(character_id)
+    avatar_url = _image_data_url(Path(cfg.get("avatar_path", ""))) if cfg.get("avatar_path") else ""
+    avatar_img = f'<img class="char-avatar" src="{avatar_url}" alt="avatar" />' if avatar_url else ""
+    return f"""
+    <section class="hero">
+      <div class="char-wrap">
+        {avatar_img}
+        <div class="char-name">{cfg.get("display_name", "PDF Paper Tutor")}</div>
+        <div class="char-tag">{cfg.get("tagline", "")}</div>
+        <div class="char-byline">{cfg.get("byline", "")}</div>
+      </div>
+    </section>
+    """
+
+
+def build_chat_avatar_html(character_id: Optional[str] = None) -> str:
+    cfg = get_character_config(character_id)
+    avatar_url = _image_data_url(Path(cfg.get("avatar_path", ""))) if cfg.get("avatar_path") else ""
+    return f'<img class="mini-avatar" src="{avatar_url}" alt="avatar" />' if avatar_url else ""
+
+
+def build_chat_meta_html(character_id: Optional[str] = None) -> str:
+    cfg = get_character_config(character_id)
+    return f"""
+    <div id="chat-meta">{cfg.get("chat_label", "PDF Paper Tutor")} <span class="pill">{cfg.get("chat_mode", "paper mode")}</span></div>
+    """
+
+
+with gr.Blocks(css=CSS) as demo:
+    with gr.Column(elem_id="page-shell"):
+        character_header_html = gr.HTML(build_character_header_html(DEFAULT_CHARACTER_ID), elem_id="character-card")
+        character_dropdown = gr.Radio(
+            choices=[(cfg["display_name"], cid) for cid, cfg in CHARACTER_CONFIGS.items()],
+            value=DEFAULT_CHARACTER_ID,
+            label="",
+            show_label=False,
+            interactive=True,
+            elem_id="character-select-wrap",
+            container=False,
+        )
+
+        state = gr.State(new_session_state())
+
+        loading_md = gr.Markdown("正在生成中，请稍候...", elem_id="gen-loading", visible=False)
+
+        with gr.Column(visible=False, elem_id="results-panel") as explain_page:
+            with gr.Row(elem_id="chat-row"):
+                with gr.Column(scale=0, elem_id="chat-avatar-col"):
+                    chat_avatar_html = gr.HTML(build_chat_avatar_html(DEFAULT_CHARACTER_ID))
+                with gr.Column(elem_id="chat-main"):
+                    chat_meta_html = gr.HTML(build_chat_meta_html(DEFAULT_CHARACTER_ID))
+                    with gr.Column(elem_id="lecture-wrap"):
+                        lecture_box = gr.Textbox(
+                            label="",
+                            show_label=False,
+                            lines=10,
+                            interactive=False,
+                            placeholder="Generated lecture explanation will appear here...",
+                        )
+                    with gr.Row(elem_id="lecture-actions"):
+                        play_lecture_btn = gr.Button("Play Lecture Audio", interactive=False, scale=0)
+                    with gr.Row(elem_id="exam-entry-wrap"):
+                        exam_btn = gr.Button("Exam", interactive=False, variant="secondary", scale=0)
+
+            with gr.Column(elem_id="tts-wrap"):
+                lecture_audio = gr.Audio(label="Lecture TTS", type="filepath")
+
+        with gr.Column(visible=False, elem_id="exam-page") as exam_page:
+            with gr.Row(elem_id="exam-nav"):
+                back_btn = gr.Button("Back", variant="secondary", scale=0)
+            exam_character_radio = gr.Radio(
+                choices=[(cfg["display_name"], cid) for cid, cfg in CHARACTER_CONFIGS.items()],
+                value=None,
+                label="Choose character for MCQ",
+                interactive=True,
+                elem_id="character-select-wrap",
+                container=False,
+            )
+            with gr.Column(elem_id="status-wrap"):
+                status_box = gr.Textbox(label="Status", value="Idle", interactive=False)
+            with gr.Column(elem_id="quiz-wrap"):
+                quiz_header = gr.Markdown("### No question loaded", visible=False)
+                choice_radio = gr.Radio(choices=[], label="Select one answer", interactive=False)
+                with gr.Row():
+                    submit_btn = gr.Button("Submit Answer", interactive=False)
+                    next_btn = gr.Button("Next Question", visible=False)
+                    restart_btn = gr.Button("Restart Quiz", interactive=False)
+                score_box = gr.Textbox(label="Score", value="Score: 0 / 0", interactive=False)
+                feedback_box = gr.Textbox(label="Feedback / Explanation", lines=8, interactive=False)
+
+            with gr.Column(elem_id="explain-wrap"):
+                explanation_audio = gr.Audio(label="Explanation TTS (shown after wrong answer)", type="filepath")
+                play_expl_btn = gr.Button("Play Explanation Audio", visible=False, interactive=False)
+
+        with gr.Row(elem_id="bottom-composer"):
+            pdf_input = gr.File(
+                label="",
+                show_label=False,
+                file_types=[".pdf"],
+                type="filepath",
+                elem_id="pdf-uploader",
+                scale=7,
+                min_width=0,
+            )
+            run_btn = gr.Button("Generate", variant="primary", elem_id="generate-btn", scale=3, min_width=120)
+
+    outputs = [
+        state,
+        loading_md,
+        explain_page,
+        exam_page,
+        exam_character_radio,
+        status_box,
+        lecture_box,
+        lecture_audio,
+        play_lecture_btn,
+        exam_btn,
+        quiz_header,
+        choice_radio,
+        score_box,
+        feedback_box,
+        explanation_audio,
+        play_expl_btn,
+        next_btn,
+        submit_btn,
+        restart_btn,
+    ]
+
+    run_btn.click(fn=on_generate_click, inputs=[pdf_input, character_dropdown, exam_character_radio, state], outputs=outputs)
+    character_dropdown.change(
+        fn=on_character_change,
+        inputs=[character_dropdown, state],
+        outputs=[state, character_header_html, chat_avatar_html, chat_meta_html, explain_page, exam_page, loading_md, status_box],
+    )
+    exam_btn.click(fn=go_to_exam_page, inputs=[state], outputs=outputs)
+    exam_character_radio.change(fn=on_exam_character_select, inputs=[exam_character_radio, state], outputs=[state, status_box])
+    back_btn.click(fn=go_to_explain_page, inputs=[state], outputs=outputs)
+    submit_btn.click(fn=submit_answer, inputs=[choice_radio, state], outputs=outputs)
+    next_btn.click(fn=next_question, inputs=[state], outputs=outputs)
+    restart_btn.click(fn=restart_quiz, inputs=[state], outputs=outputs)
+    play_lecture_btn.click(
+        fn=play_lecture_audio,
+        inputs=[state],
+        outputs=[state, status_box, lecture_audio, feedback_box],
+    )
+    play_expl_btn.click(
+        fn=play_explanation_audio,
+        inputs=[state],
+        outputs=[state, status_box, explanation_audio, feedback_box],
+    )
+
+
+if __name__ == "__main__":
+    demo.queue()
+    demo.launch()

characters/Mcgonagall/lecture_prompt.txt

@@ -0,0 +1,10 @@
+你是一名风格冷静、严谨但清晰的课程助教（Snape 风格），请阅读用户上传的论文内容，并输出一段中文讲解，要求：
+1. 先说明论文要解决的问题和背景；
+2. 再解释核心方法（按步骤/模块）；
+3. 再总结实验结果或亮点；
+4. 最后给出局限性与适用场景；
+5. 语言精炼、逻辑清楚，适合课堂讲解（约 400-700 字）；
+6. 不要虚构论文中不存在的实验细节。
+
+论文内容（可能是节选）：
+{document}

characters/Mcgonagall/mcq_prompt.txt

@@ -0,0 +1,23 @@
+请基于下面论文内容，生成 5 道中文单选题（MCQ），用于课堂测验。
+严格输出 JSON（不要 markdown 代码块），格式如下：
+{
+  "questions": [
+    {
+      "question": "...",
+      "options": ["A选项", "B选项", "C选项", "D选项"],
+      "answer": "A",
+      "explanation": "..."
+    }
+  ]
+}
+
+要求：
+1. 共 5 题；
+2. 每题 4 个选项；
+3. answer 必须是 A/B/C/D；
+4. 解析要说明为什么正确，以及常见误区；
+5. 题目覆盖背景、方法、结果、局限性；
+6. 题目难度适中，适合课程课堂测验。
+
+论文内容（可能是节选）：
+{document}

characters/Mcgonagall/mcq_retry_prompt.txt

@@ -0,0 +1,14 @@
+基于以下论文内容生成 5 道中文单选题。只输出合法 JSON，不要任何解释，不要 markdown。
+
+限制：
+1. 必须是紧凑 JSON（单行也可以）；
+2. 共 5 题；
+3. 每题字段：question、options(4项)、answer(A/B/C/D)、explanation；
+4. explanation 保持简短（1-2句）；
+5. 不要输出任何 JSON 以外内容。
+
+输出格式：
+{"questions":[{"question":"...","options":["...","...","...","..."],"answer":"A","explanation":"..."}]}
+
+论文内容：
+{document}

characters/Mcgonagall/meta.json

@@ -0,0 +1,12 @@
+{
+  "id": "Mcgonagall",
+  "display_name": "Mcgonagall",
+  "tagline": "Research paper explainer · MCQ coach",
+  "byline": "By @local-demo",
+  "chat_label": "Mcgonagall",
+  "chat_mode": "paper mode",
+  "avatar": "avatar.jpg",
+  "lecture_prompt_file": "lecture_prompt.txt",
+  "mcq_prompt_file": "mcq_prompt.txt",
+  "mcq_retry_prompt_file": "mcq_retry_prompt.txt"
+}

characters/snape/lecture_prompt.txt

@@ -0,0 +1,10 @@
+你是一名风格冷静、严谨但清晰的课程助教（Snape 风格），请阅读用户上传的论文内容，并输出一段中文讲解，要求：
+1. 先说明论文要解决的问题和背景；
+2. 再解释核心方法（按步骤/模块）；
+3. 再总结实验结果或亮点；
+4. 最后给出局限性与适用场景；
+5. 语言精炼、逻辑清楚，适合课堂讲解（约 400-700 字）；
+6. 不要虚构论文中不存在的实验细节。
+
+论文内容（可能是节选）：
+{document}

characters/snape/mcq_prompt.txt

@@ -0,0 +1,23 @@
+请基于下面论文内容，生成 5 道中文单选题（MCQ），用于课堂测验。
+严格输出 JSON（不要 markdown 代码块），格式如下：
+{
+  "questions": [
+    {
+      "question": "...",
+      "options": ["A选项", "B选项", "C选项", "D选项"],
+      "answer": "A",
+      "explanation": "..."
+    }
+  ]
+}
+
+要求：
+1. 共 5 题；
+2. 每题 4 个选项；
+3. answer 必须是 A/B/C/D；
+4. 解析要说明为什么正确，以及常见误区；
+5. 题目覆盖背景、方法、结果、局限性；
+6. 题目难度适中，适合课程课堂测验。
+
+论文内容（可能是节选）：
+{document}

characters/snape/mcq_retry_prompt.txt

@@ -0,0 +1,14 @@
+基于以下论文内容生成 5 道中文单选题。只输出合法 JSON，不要任何解释，不要 markdown。
+
+限制：
+1. 必须是紧凑 JSON（单行也可以）；
+2. 共 5 题；
+3. 每题字段：question、options(4项)、answer(A/B/C/D)、explanation；
+4. explanation 保持简短（1-2句）；
+5. 不要输出任何 JSON 以外内容。
+
+输出格式：
+{"questions":[{"question":"...","options":["...","...","...","..."],"answer":"A","explanation":"..."}]}
+
+论文内容：
+{document}

characters/snape/meta.json

@@ -0,0 +1,12 @@
+{
+  "id": "snape",
+  "display_name": "Snape",
+  "tagline": "Research paper explainer · MCQ coach",
+  "byline": "By @local-demo",
+  "chat_label": "Snape",
+  "chat_mode": "paper mode",
+  "avatar": "avatar.jpg",
+  "lecture_prompt_file": "lecture_prompt.txt",
+  "mcq_prompt_file": "mcq_prompt.txt",
+  "mcq_retry_prompt_file": "mcq_retry_prompt.txt"
+}

characters/test/lecture_prompt.txt

@@ -0,0 +1,10 @@
+你是一名风格冷静、严谨但清晰的课程助教（Snape 风格），请阅读用户上传的论文内容，并输出一段中文讲解，要求：
+1. 先说明论文要解决的问题和背景；
+2. 再解释核心方法（按步骤/模块）；
+3. 再总结实验结果或亮点；
+4. 最后给出局限性与适用场景；
+5. 语言精炼、逻辑清楚，适合课堂讲解（约 400-700 字）；
+6. 不要虚构论文中不存在的实验细节。
+
+论文内容（可能是节选）：
+{document}

characters/test/mcq_prompt.txt

@@ -0,0 +1,23 @@
+请基于下面论文内容，生成 5 道中文单选题（MCQ），用于课堂测验。
+严格输出 JSON（不要 markdown 代码块），格式如下：
+{
+  "questions": [
+    {
+      "question": "...",
+      "options": ["A选项", "B选项", "C选项", "D选项"],
+      "answer": "A",
+      "explanation": "..."
+    }
+  ]
+}
+
+要求：
+1. 共 5 题；
+2. 每题 4 个选项；
+3. answer 必须是 A/B/C/D；
+4. 解析要说明为什么正确，以及常见误区；
+5. 题目覆盖背景、方法、结果、局限性；
+6. 题目难度适中，适合课程课堂测验。
+
+论文内容（可能是节选）：
+{document}

characters/test/mcq_retry_prompt.txt

@@ -0,0 +1,14 @@
+基于以下论文内容生成 5 道中文单选题。只输出合法 JSON，不要任何解释，不要 markdown。
+
+限制：
+1. 必须是紧凑 JSON（单行也可以）；
+2. 共 5 题；
+3. 每题字段：question、options(4项)、answer(A/B/C/D)、explanation；
+4. explanation 保持简短（1-2句）；
+5. 不要输出任何 JSON 以外内容。
+
+输出格式：
+{"questions":[{"question":"...","options":["...","...","...","..."],"answer":"A","explanation":"..."}]}
+
+论文内容：
+{document}

characters/test/meta.json

@@ -0,0 +1,12 @@
+{
+  "id": "test",
+  "display_name": "Test",
+  "tagline": "Research paper explainer · MCQ coach",
+  "byline": "By @local-demo",
+  "chat_label": "Test",
+  "chat_mode": "paper mode",
+  "avatar": "avatar.jpg",
+  "lecture_prompt_file": "lecture_prompt.txt",
+  "mcq_prompt_file": "mcq_prompt.txt",
+  "mcq_retry_prompt_file": "mcq_retry_prompt.txt"
+}

notebook_prototype.py

@@ -0,0 +1,156 @@
+"""
+Notebook-friendly prototype helpers for the coursework workflow:
+PDF -> lecture text -> 5 MCQs (with answers + explanations)
+
+Usage in Colab/Jupyter:
+    from notebook_prototype import run_prototype
+    result = run_prototype("/path/to/paper.pdf", mock=True)
+    print(result["lecture_text"])
+    print(result["mcqs"][0])
+
+Set mock=False to reuse the real Qwen3-VL backend from app.py (same prompts/parsing flow).
+"""
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Dict, List
+
+try:
+    from pypdf import PdfReader
+except Exception:
+    PdfReader = None  # type: ignore
+
+
+LECTURE_PROMPT = """
+你是一名课程助教。请阅读论文内容并写一段中文讲解（400-700字），包括：
+问题背景、核心方法、实验亮点、局限性与适用场景。
+
+论文内容：
+{document}
+""".strip()
+
+
+MCQ_PROMPT = """
+请基于论文内容生成 5 道中文单选题，并严格输出 JSON：
+{
+  "questions": [
+    {
+      "question": "...",
+      "options": ["...", "...", "...", "..."],
+      "answer": "A",
+      "explanation": "..."
+    }
+  ]
+}
+""".strip()
+
+
+def extract_pdf_text(pdf_path: str, max_chars: int = 16000) -> str:
+    if PdfReader is None:
+        raise RuntimeError("pypdf is not installed.")
+    reader = PdfReader(pdf_path)
+    chunks: List[str] = []
+    total = 0
+    for i, page in enumerate(reader.pages, start=1):
+        text = (page.extract_text() or "").strip()
+        if not text:
+            continue
+        part = f"[Page {i}]\\n{text}\\n"
+        chunks.append(part)
+        total += len(part)
+        if total >= max_chars:
+            break
+    if not chunks:
+        return "No extractable text found. For scanned PDFs, convert pages to images and feed them to a VL model."
+    return "\\n".join(chunks)[:max_chars]
+
+
+def _mock_lecture(document: str) -> str:
+    short = re.sub(r"\\s+", " ", document)[:1000]
+    return (
+        "【Mock讲解】这篇论文主要围绕一个机器学习/生成式AI任务展开，目标是改善现有方法在效果、效率或稳定性上的不足。"
+        "作者通过提出新的模型结构、训练策略或推理流程来解决该问题，并通过实验与基线比较验证方法有效性。"
+        "在阅读时建议重点关注：任务定义、输入输出、方法模块、实验设置、指标、消融实验，以及论文提到的局限性。\\n\\n"
+        f"论文节选：{short}"
+    )
+
+
+def _mock_mcqs() -> List[Dict[str, Any]]:
+    return [
+        {
+            "question": "论文讲解中首先应说明什么？",
+            "options": ["问题背景与任务目标", "部署服务器价格", "前端样式颜色", "Git分支命名"],
+            "answer": "A",
+            "explanation": "先解释背景与目标，听众才知道作者为什么提出该方法。",
+        },
+        {
+            "question": "哪一项更适合用于解释论文方法？",
+            "options": ["按模块/步骤描述输入到输出流程", "只贴公式不解释", "只读摘要", "只看结论"],
+            "answer": "A",
+            "explanation": "方法讲解应结构化呈现，否则难以理解论文贡献点。",
+        },
+        {
+            "question": "为什么要生成带解析的选择题？",
+            "options": ["支持交互式教学反馈", "为了减少推理时间", "为了替代PDF上传", "为了训练TTS模型"],
+            "answer": "A",
+            "explanation": "解析能帮助学生理解错误原因并形成学习闭环。",
+        },
+        {
+            "question": "长论文处理通常更稳妥的做法是？",
+            "options": ["分块阅读后汇总", "一次性全部输入且不做控制", "只看标题", "随机抽样一页"],
+            "answer": "A",
+            "explanation": "分块可以降低上下文长度风险并提高稳定性。",
+        },
+        {
+            "question": "在你的课程Demo里，TTS最主要用于？",
+            "options": ["讲解和错题解析语音输出", "替代VL模型阅读PDF", "生成图片", "训练新LoRA"],
+            "answer": "A",
+            "explanation": "TTS负责文本转语音，增强演示交互体验。",
+        },
+    ]
+
+
+def run_prototype(pdf_path: str, mock: bool = True) -> Dict[str, Any]:
+    pdf_path = str(Path(pdf_path))
+    document = extract_pdf_text(pdf_path)
+
+    lecture_prompt = LECTURE_PROMPT.format(document=document)
+    mcq_prompt = MCQ_PROMPT.format(document=document)
+
+    if mock:
+        lecture_text = _mock_lecture(document)
+        mcqs = _mock_mcqs()
+    else:
+        # Reuse the same backend implementation as app.py to keep notebook/app behavior aligned.
+        from app import QwenPipelineEngine, parse_mcq_json  # local import avoids gradio setup cost until needed
+
+        engine = QwenPipelineEngine()
+        engine.mock_mode = False
+        engine.ensure_vl_loaded()
+        lecture_text = engine._real_generate_text_from_pdf(pdf_path, lecture_prompt)
+        raw_mcq_json = engine._real_generate_text_from_pdf(pdf_path, mcq_prompt)
+        mcqs = [q.__dict__ for q in parse_mcq_json(raw_mcq_json)]
+
+    return {
+        "pdf_path": pdf_path,
+        "document_excerpt": document[:2000],
+        "lecture_prompt": lecture_prompt,
+        "mcq_prompt": mcq_prompt,
+        "lecture_text": lecture_text,
+        "mcqs": mcqs,
+    }
+
+
+def pretty_print_mcqs(mcqs: List[Dict[str, Any]]) -> None:
+    for i, q in enumerate(mcqs, start=1):
+        print(f"\\nQ{i}. {q['question']}")
+        for label, opt in zip(["A", "B", "C", "D"], q["options"]):
+            print(f"  {label}. {opt}")
+        print(f"Answer: {q['answer']}")
+        print(f"Explanation: {q['explanation']}")
+
+
+if __name__ == "__main__":
+    # Minimal local check (replace with a real PDF path).
+    print("Import this file in a notebook and call run_prototype('/path/to/file.pdf').")

requirements.txt

@@ -0,0 +1,6 @@
+gradio
+spaces
+requests
+pypdf
+pypdfium2
+Pillow