Deploy ZeroGPU algorithm research deck

.dockerignore

@@ -0,0 +1,7 @@
+.git
+.env
+__pycache__
+*.pyc
+.pytest_cache
+output
+tests

.gitignore

@@ -0,0 +1,5 @@
+.env
+__pycache__/
+*.pyc
+.pytest_cache/
+output/

DEPLOYMENT.md

@@ -0,0 +1,64 @@
+# Deploy to wingsxyp/algorithm-research-deck
+
+Target Space: `https://huggingface.co/spaces/wingsxyp/algorithm-research-deck`
+
+## Token roles
+
+- **Write token**: use only on your computer for Git authentication and pushing files to the Space repository.
+- **Read token**: add to the Space as the Secret `HF_TOKEN`; the running application uses it to download the configured open model.
+- Never commit either token. Never put the write token in Space Secrets.
+
+## Space settings
+
+The repository README configures a Gradio Space. In the Space settings, select ZeroGPU hardware if it is not already selected.
+
+Add this Secret:
+
+```text
+HF_TOKEN=<your read token>
+```
+
+Add these Variables:
+
+```text
+HF_MODEL_ID=Qwen/Qwen2.5-7B-Instruct
+CONTACT_EMAIL=<your email for polite arXiv requests>
+```
+
+The model must be public or accessible to the account that owns the read token. A gated model requires accepting its terms with the same account.
+
+## Local authentication and push
+
+From the project root:
+
+```powershell
+git init
+git add .
+git commit -m "Deploy ZeroGPU algorithm research deck"
+git branch -M main
+git remote add origin https://huggingface.co/spaces/wingsxyp/algorithm-research-deck
+git push -u origin main
+```
+
+When Git asks for credentials:
+
+```text
+Username: wingsxyp
+Password: <your write token>
+```
+
+The password field does not display typed characters. This is expected.
+
+## Verify
+
+Open the Space build logs. A successful build installs Gradio, Spaces, Transformers, PyTorch dependencies, and launches `app.py`. Test `Retrieval-Augmented Generation` in Quick mode first.
+
+Verify:
+
+- arXiv search completes
+- ZeroGPU allocation starts for model synthesis
+- the presentation appears in the right panel
+- HTML, JSON, and ZIP downloads work
+- the downloaded HTML opens independently in a browser
+
+If model loading fails, first confirm `HF_MODEL_ID`, the read token's model access, and ZeroGPU quota. Do not replace the read token with the write token.

README.md

@@ -0,0 +1,28 @@
+---
+title: Algorithm Research Deck
+emoji: 🔬
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 5.29.0
+app_file: app.py
+pinned: false
+license: apache-2.0
+---
+
+# Algorithm Research Deck
+
+Turn an algorithm research topic into an interactive, paper-backed HTML presentation. The Space searches arXiv on CPU, uses ZeroGPU for open-model synthesis, previews the result, and provides HTML, JSON, and ZIP downloads.
+
+## Space configuration
+
+Secret:
+
+- `HF_TOKEN`: a read token used only to download the configured model. Public models may not require it, but setting it avoids anonymous download limits.
+
+Variables:
+
+- `HF_MODEL_ID`: defaults to `Qwen/Qwen2.5-7B-Instruct`
+- `CONTACT_EMAIL`: contact address included in polite arXiv requests
+
+The token used on your computer to push this repository must be a write token. Never add that write token to Space Secrets.

app.py

@@ -0,0 +1,375 @@
+from __future__ import annotations
+
+import html
+import io
+import json
+import os
+import re
+import uuid
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote_plus
+from xml.etree import ElementTree
+
+import gradio as gr
+import httpx
+import spaces
+import torch
+from pydantic import BaseModel, Field
+from pypdf import PdfReader
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+
+BASE_DIR = Path(__file__).resolve().parent
+STATIC_DIR = BASE_DIR / "static"
+DATA_DIR = Path("/data/research-decks") if Path("/data").exists() else BASE_DIR / "output"
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+MODEL_ID = os.getenv("HF_MODEL_ID", "Qwen/Qwen2.5-7B-Instruct")
+_model = None
+_tokenizer = None
+
+
+class ResearchRequest(BaseModel):
+    topic: str = Field(min_length=2, max_length=180)
+    purpose: str = Field(default="算法团队内部技术分享", max_length=500)
+    audience: str = Field(default="熟悉机器学习基础的算法工程师", max_length=300)
+    focus: str = Field(default="", max_length=1200)
+    date_range: str = Field(default="经典工作至今", max_length=120)
+    depth: str = Field(default="standard", pattern="^(quick|standard|deep)$")
+    language: str = Field(default="中文", max_length=40)
+    paper_urls: list[str] = Field(default_factory=list, max_length=12)
+
+
+DEPTHS = {
+    "quick": {"discover": 30, "screen": 10, "deep": 2},
+    "standard": {"discover": 60, "screen": 20, "deep": 4},
+    "deep": {"discover": 100, "screen": 35, "deep": 8},
+}
+
+
+def safe_slug(value: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", value).strip("-").lower()
+    return (slug or "algorithm-topic")[:64]
+
+
+def arxiv_search(topic: str, limit: int) -> list[dict[str, Any]]:
+    query = quote_plus(f'all:"{topic}"')
+    url = (
+        "https://export.arxiv.org/api/query"
+        f"?search_query={query}&start=0&max_results={limit}"
+        "&sortBy=submittedDate&sortOrder=descending"
+    )
+    headers = {"User-Agent": f"algorithm-research-deck/1.0 ({os.getenv('CONTACT_EMAIL', 'contact-not-set')})"}
+    with httpx.Client(timeout=30, follow_redirects=True, headers=headers) as client:
+        response = client.get(url)
+        response.raise_for_status()
+    ns = {"a": "http://www.w3.org/2005/Atom"}
+    root = ElementTree.fromstring(response.text)
+    papers = []
+    for entry in root.findall("a:entry", ns):
+        abs_url = (entry.findtext("a:id", default="", namespaces=ns) or "").strip()
+        authors = [x.findtext("a:name", default="", namespaces=ns) for x in entry.findall("a:author", ns)]
+        papers.append({
+            "id": abs_url.rsplit("/", 1)[-1],
+            "title": " ".join((entry.findtext("a:title", default="", namespaces=ns) or "").split()),
+            "summary": " ".join((entry.findtext("a:summary", default="", namespaces=ns) or "").split()),
+            "authors": authors,
+            "published": entry.findtext("a:published", default="", namespaces=ns),
+            "updated": entry.findtext("a:updated", default="", namespaces=ns),
+            "url": abs_url,
+            "pdf_url": abs_url.replace("/abs/", "/pdf/") + ".pdf",
+        })
+    return papers
+
+
+def normalize_user_papers(urls: list[str]) -> list[dict[str, Any]]:
+    result = []
+    for raw in urls:
+        match = re.search(r"arxiv\.org/(?:abs|pdf)/([\w.\-/]+)", raw)
+        if match:
+            paper_id = match.group(1).removesuffix(".pdf")
+            result.append({
+                "id": paper_id,
+                "title": f"User supplied arXiv paper {paper_id}",
+                "summary": "User-supplied paper; prioritize during screening.",
+                "authors": [],
+                "published": "",
+                "updated": "",
+                "url": f"https://arxiv.org/abs/{paper_id}",
+                "pdf_url": f"https://arxiv.org/pdf/{paper_id}.pdf",
+                "user_supplied": True,
+            })
+    return result
+
+
+def deduplicate(papers: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    seen = set()
+    output = []
+    for paper in papers:
+        key = re.sub(r"v\d+$", "", paper["id"])
+        if key not in seen:
+            seen.add(key)
+            output.append(paper)
+    return output
+
+
+@spaces.GPU(duration=120)
+def generate_text(system: str, prompt: str, max_tokens: int) -> str:
+    global _model, _tokenizer
+    token = os.getenv("HF_TOKEN") or None
+    if _tokenizer is None:
+        _tokenizer = AutoTokenizer.from_pretrained(MODEL_ID, token=token)
+    if _model is None:
+        _model = AutoModelForCausalLM.from_pretrained(
+            MODEL_ID,
+            token=token,
+            torch_dtype=torch.bfloat16,
+            device_map="auto",
+        )
+    messages = [{"role": "system", "content": system}, {"role": "user", "content": prompt}]
+    model_input = _tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    inputs = _tokenizer(model_input, return_tensors="pt").to(_model.device)
+    with torch.inference_mode():
+        generated = _model.generate(
+            **inputs,
+            max_new_tokens=max_tokens,
+            do_sample=False,
+            repetition_penalty=1.05,
+        )
+    return _tokenizer.decode(generated[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
+
+
+def chat_json(system: str, prompt: str, max_tokens: int = 6000) -> dict[str, Any]:
+    content = generate_text(system, prompt, max_tokens)
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError:
+        match = re.search(r"\{[\s\S]*\}", content)
+        if not match:
+            raise RuntimeError("The model did not return valid JSON")
+        return json.loads(match.group(0))
+
+
+def select_papers(request: ResearchRequest, papers: list[dict[str, Any]], screen_limit: int, deep_limit: int) -> list[str]:
+    compact = [{k: p[k] for k in ("id", "title", "summary", "authors", "published", "url")} for p in papers[:screen_limit]]
+    prompt = json.dumps({
+        "topic": request.topic,
+        "purpose": request.purpose,
+        "focus": request.focus,
+        "papers": compact,
+        "instruction": f"Select at most {deep_limit} pivotal papers. Return JSON with selected_ids and a short selection_reason per id.",
+    }, ensure_ascii=False)
+    result = chat_json("You select technically pivotal ML papers. Prefer lineage coverage and evidence over recency.", prompt, 900)
+    valid = {p["id"] for p in papers}
+    return [x for x in result.get("selected_ids", []) if x in valid][:deep_limit]
+
+
+def extract_pdf(paper: dict[str, Any], max_chars: int = 14000) -> str:
+    with httpx.Client(timeout=45, follow_redirects=True) as client:
+        response = client.get(paper["pdf_url"])
+        response.raise_for_status()
+        if len(response.content) > 20 * 1024 * 1024:
+            return "PDF omitted because it exceeds the 20 MB limit."
+    reader = PdfReader(io.BytesIO(response.content))
+    pages = []
+    indexes = list(range(min(8, len(reader.pages))))
+    if len(reader.pages) > 8:
+        indexes += list(range(max(8, len(reader.pages) - 3), len(reader.pages)))
+    for index in dict.fromkeys(indexes):
+        text = reader.pages[index].extract_text() or ""
+        pages.append(f"[Page {index + 1}]\n{text}")
+        if sum(map(len, pages)) >= max_chars:
+            break
+    return "\n".join(pages)[:max_chars]
+
+
+def build_report(request: ResearchRequest, papers: list[dict[str, Any]], deep_texts: dict[str, str]) -> dict[str, Any]:
+    evidence = []
+    for paper in papers:
+        item = {k: paper.get(k) for k in ("id", "title", "summary", "authors", "published", "updated", "url")}
+        if paper["id"] in deep_texts:
+            item["selected_full_text_extract"] = deep_texts[paper["id"]]
+        evidence.append(item)
+    payload = {
+        "request": request.model_dump(),
+        "research_cutoff": datetime.now(timezone.utc).date().isoformat(),
+        "evidence": evidence,
+        "schema": {
+            "title": "string",
+            "subtitle": "string",
+            "executive_summary": ["string"],
+            "lineage": [{"year": "string", "method": "string", "paper_id": "string", "bottleneck": "string", "innovation": "string", "limitation": "string"}],
+            "sections": [{"title": "string", "takeaway": "string", "body": ["string"], "paper_ids": ["string"], "details": "string"}],
+            "comparisons": [{"method": "string", "mechanism": "string", "strengths": "string", "limitations": "string", "engineering": "string"}],
+            "open_questions": ["string"],
+        },
+    }
+    return chat_json(
+        "You are a rigorous algorithm research lead. Return only JSON matching the supplied schema. "
+        "Trace classical ideas to current methods, distinguish preprints, avoid incomparable benchmark claims, "
+        "and cite only supplied paper IDs. Write concise presentation-ready content.",
+        json.dumps(payload, ensure_ascii=False),
+        3800,
+    )
+
+
+def esc(value: Any) -> str:
+    return html.escape(str(value or ""))
+
+
+def render_presentation(report: dict[str, Any], papers: list[dict[str, Any]], cutoff: str) -> str:
+    deck_css = (STATIC_DIR / "deck.css").read_text(encoding="utf-8")
+    deck_js = (STATIC_DIR / "deck.js").read_text(encoding="utf-8").replace("</script", "<\\/script")
+    citations = {p["id"]: p for p in papers}
+    lineage = report.get("lineage", [])
+    sections = report.get("sections", [])
+    summary = report.get("executive_summary", [])
+    comparisons = report.get("comparisons", [])
+
+    timeline = "".join(
+        f'<button class="milestone" data-index="{i}" aria-pressed="{str(i == 0).lower()}"><span>{esc(x.get("year"))}</span>{esc(x.get("method"))}</button>'
+        for i, x in enumerate(lineage)
+    )
+    timeline_data = html.escape(json.dumps(lineage, ensure_ascii=False), quote=True)
+    summary_html = "".join(f"<li>{esc(x)}</li>" for x in summary)
+    section_html = "".join(
+        f'''<section class="slide" id="section-{i + 1}">
+        <p class="eyebrow">{i + 3:02d}</p><h2>{esc(x.get('title'))}</h2>
+        <p class="takeaway">{esc(x.get('takeaway'))}</p>
+        <ul>{''.join(f'<li>{esc(b)}</li>' for b in x.get('body', []))}</ul>
+        <details><summary>方法细节与证据</summary><p>{esc(x.get('details'))}</p><p class="sources">论文：{', '.join(esc(pid) for pid in x.get('paper_ids', []))}</p></details>
+        </section>'''
+        for i, x in enumerate(sections)
+    )
+    rows = "".join(
+        f"<tr><th>{esc(x.get('method'))}</th><td>{esc(x.get('mechanism'))}</td><td>{esc(x.get('strengths'))}</td><td>{esc(x.get('limitations'))}</td><td>{esc(x.get('engineering'))}</td></tr>"
+        for x in comparisons
+    )
+    refs = "".join(
+        f'<li id="ref-{esc(pid)}"><a href="{esc(p.get("url"))}" target="_blank" rel="noopener noreferrer">{esc(p.get("title"))}</a><br><span>{esc(", ".join(p.get("authors", [])[:6]))} · {esc((p.get("published") or "")[:10])} · arXiv:{esc(pid)}</span></li>'
+        for pid, p in citations.items()
+    )
+    open_questions = "".join(f"<li>{esc(x)}</li>" for x in report.get("open_questions", []))
+    title = esc(report.get("title", "Algorithm Research"))
+    subtitle = esc(report.get("subtitle", ""))
+    return f'''<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>{title}</title><style>{deck_css}</style></head><body>
+<nav><strong>{title}</strong><span id="counter"></span><button id="prev" aria-label="上一页">←</button><button id="next" aria-label="下一页">→</button><button onclick="window.print()">保存 PDF</button></nav>
+<main>
+<section class="slide active" id="cover"><p class="eyebrow">ALGORITHM RESEARCH · {esc(cutoff)}</p><h1>{title}</h1><p class="subtitle">{subtitle}</p><p>使用方向键翻页，滚动和打印模式同样可用。</p></section>
+<section class="slide" id="summary"><p class="eyebrow">01</p><h2>核心结论</h2><ol>{summary_html}</ol></section>
+<section class="slide" id="lineage" data-lineage="{timeline_data}"><p class="eyebrow">02</p><h2>技术路线</h2><div class="timeline">{timeline}</div><article id="milestone-detail" aria-live="polite"></article></section>
+{section_html}
+<section class="slide" id="comparison"><h2>方法对比</h2><div class="table-wrap"><table><thead><tr><th>方法</th><th>机制</th><th>优势</th><th>局限</th><th>工程考虑</th></tr></thead><tbody>{rows}</tbody></table></div></section>
+<section class="slide" id="questions"><h2>开放问题</h2><ul>{open_questions}</ul></section>
+<section class="slide references" id="references"><h2>论文与研究截止日期</h2><p>检索截止：{esc(cutoff)}。预印本结论可能随修订发生变化。</p><ol>{refs}</ol></section>
+</main><div class="progress"><span id="progress-bar"></span></div><script>{deck_js}</script></body></html>'''
+
+
+def create_bundle(job_dir: Path, html_path: Path, report_path: Path) -> Path:
+    bundle = job_dir / "research-package.zip"
+    with zipfile.ZipFile(bundle, "w", zipfile.ZIP_DEFLATED) as archive:
+        archive.write(html_path, html_path.name)
+        archive.write(report_path, report_path.name)
+    return bundle
+
+
+def preview_frame(content: str) -> str:
+    source = html.escape(content, quote=True)
+    return f'<iframe title="Interactive research presentation" srcdoc="{source}" style="width:100%;height:76vh;border:1px solid #30394a;border-radius:10px;background:#080b12" sandbox="allow-scripts allow-popups"></iframe>'
+
+
+def run_research_ui(
+    topic: str,
+    purpose: str,
+    audience: str,
+    focus: str,
+    date_range: str,
+    depth: str,
+    language: str,
+    paper_urls: str,
+    progress=gr.Progress(),
+):
+    request = ResearchRequest(
+        topic=topic,
+        purpose=purpose,
+        audience=audience,
+        focus=focus,
+        date_range=date_range,
+        depth=depth.lower(),
+        language=language,
+        paper_urls=[x.strip() for x in paper_urls.splitlines() if x.strip()],
+    )
+    budget = DEPTHS[request.depth]
+    progress(0.08, desc="正在检索 arXiv")
+    papers = deduplicate(normalize_user_papers(request.paper_urls) + arxiv_search(request.topic, budget["discover"]))
+    if not papers:
+        raise gr.Error("没有检索到论文，请尝试英文关键词或提供 arXiv 链接。")
+    screen = papers[: budget["screen"]]
+    progress(0.28, desc="ZeroGPU 正在筛选关键论文")
+    selected_ids = select_papers(request, screen, budget["screen"], budget["deep"])
+    if not selected_ids:
+        selected_ids = [p["id"] for p in screen[: budget["deep"]]]
+    progress(0.48, desc="正在读取关键论文")
+    deep_texts = {}
+    for index, paper in enumerate(screen):
+        if paper["id"] in selected_ids:
+            try:
+                deep_texts[paper["id"]] = extract_pdf(paper)
+            except Exception as exc:
+                deep_texts[paper["id"]] = f"PDF extraction failed: {exc}"
+        progress(0.48 + 0.16 * (index + 1) / len(screen), desc="正在提取论文证据")
+    progress(0.68, desc="ZeroGPU 正在生成技术路线")
+    report = build_report(request, screen, deep_texts)
+    cutoff = datetime.now(timezone.utc).date().isoformat()
+    content = render_presentation(report, screen, cutoff)
+    job_dir = DATA_DIR / uuid.uuid4().hex
+    job_dir.mkdir(parents=True, exist_ok=True)
+    slug = safe_slug(request.topic)
+    html_path = job_dir / f"{slug}-research.html"
+    report_path = job_dir / f"{slug}-research.json"
+    html_path.write_text(content, encoding="utf-8")
+    report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    bundle_path = create_bundle(job_dir, html_path, report_path)
+    progress(1, desc="完成")
+    status = f"✅ 已完成：检索 {len(papers)} 篇，筛选 {len(screen)} 篇，深读 {len(deep_texts)} 篇。"
+    return status, preview_frame(content), str(html_path), str(report_path), str(bundle_path)
+
+
+CSS = """
+.gradio-container{max-width:none!important}.preview-column{min-width:0}.input-column{max-width:430px}
+"""
+
+with gr.Blocks(title="Algorithm Research Deck", css=CSS, theme=gr.themes.Soft()) as demo:
+    gr.Markdown("# Algorithm Research Deck\n从经典方法到最新论文，生成可保存的交互式 HTML 技术演示。")
+    with gr.Row():
+        with gr.Column(scale=1, elem_classes="input-column"):
+            topic = gr.Textbox(label="调研主题", placeholder="例如：Diffusion Transformer")
+            purpose = gr.Textbox(label="用途", value="算法团队内部技术分享")
+            audience = gr.Textbox(label="受众", value="熟悉机器学习基础的算法工程师")
+            focus = gr.Textbox(label="重点关注", lines=3, placeholder="技术路线、推理加速、工程部署……")
+            with gr.Row():
+                depth = gr.Radio(["Quick", "Standard", "Deep"], value="Quick", label="研究深度")
+                language = gr.Dropdown(["中文", "English"], value="中文", label="输出语言")
+            date_range = gr.Textbox(label="时间范围", value="经典工作至今")
+            paper_urls = gr.Textbox(label="指定 arXiv 链接", lines=3, placeholder="每行一个，可选")
+            submit = gr.Button("开始调研", variant="primary")
+            status = gr.Markdown("等待任务")
+            html_file = gr.File(label="保存交互式 HTML")
+            json_file = gr.File(label="保存研究 JSON")
+            zip_file = gr.File(label="下载完整包")
+        with gr.Column(scale=2, elem_classes="preview-column"):
+            preview = gr.HTML("<div style='height:76vh;display:grid;place-items:center;color:#758099'>交互演示将在这里生成</div>")
+
+    submit.click(
+        run_research_ui,
+        inputs=[topic, purpose, audience, focus, date_range, depth, language, paper_urls],
+        outputs=[status, preview, html_file, json_file, zip_file],
+    )
+
+demo.queue(default_concurrency_limit=1, max_size=8)
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,7 @@
+gradio==5.29.0
+spaces==0.42.1
+httpx==0.28.1
+huggingface-hub==0.31.2
+pypdf==5.5.0
+transformers==4.51.3
+accelerate==1.6.0

research-ppt/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: research-ppt
+description: Research an algorithm, model, machine-learning method, or AI engineering topic from foundational work through the latest papers, then create an evidence-backed interactive HTML presentation. Use for technical landscape reviews, paper surveys, algorithm comparisons, and interview or team knowledge-sharing decks; do not use for general market research or static PowerPoint output.
+---
+
+# Algorithm Research Deck
+
+Turn a technical topic for algorithm engineers into a self-contained interactive HTML presentation. Build a traceable lineage from foundational ideas to current research, explain why each transition happened, and keep paper claims faithful to the original evidence.
+
+## Inputs and defaults
+
+Use the user's topic, audience level, purpose, scope, language, and desired depth. Ask only when an omitted choice would materially change the technical treatment. Otherwise use these defaults:
+
+- Audience: algorithm engineers familiar with machine learning fundamentals
+- Purpose: understand concepts, method evolution, representative papers, tradeoffs, and implementation implications
+- Scope: foundational work through the newest credible work available on the research date
+- Output: one responsive, self-contained `.html` file
+- Language: the user's language; preserve standard English technical terms where translation would reduce precision
+- Length: approximately 12-18 presentation sections, adjusted to the topic
+- Research budget: token-efficient standard mode unless the user requests exhaustive coverage
+
+Record the research cutoff date visibly. Treat preprints published near that cutoff as preliminary evidence.
+
+## Workflow
+
+### 1. Define the technical question
+
+Frame the topic as a decision or learning question. Define the task, inputs and outputs, assumptions, evaluation criteria, and exclusions. Read [algorithm-research.md](references/algorithm-research.md) before planning.
+
+Decompose the work into questions such as:
+
+- What problem does the method solve, and what formal objective defines it?
+- Which classical ideas made the modern approach possible?
+- Which bottleneck caused each major transition in the technical lineage?
+- Which papers represent the lineage rather than merely being recent?
+- How do methods compare on mechanism, complexity, data, compute, latency, quality, robustness, and reproducibility?
+- What should an algorithm engineer implement, test, or monitor?
+
+### 2. Search the literature
+
+Read [academic-search.md](references/academic-search.md) and [token-efficient-research.md](references/token-efficient-research.md). Use available academic-search tools first, including AlphaXiv, arXiv, Semantic Scholar, OpenAlex, Crossref, Papers with Code, or connected scholarly MCP tools. When a named tool is unavailable, use another scholarly index or the official arXiv API/site and disclose the limitation only if it materially reduces coverage.
+
+Search iteratively:
+
+1. terminology and survey discovery
+2. foundational and highly influential work
+3. milestone methods and their successors
+4. recent work, sorted and filtered by date
+5. citations, replications, benchmarks, and documented limitations
+
+Do not rank papers by recency alone. Include a paper when it changes the problem formulation, architecture, objective, training/inference strategy, efficiency frontier, evaluation practice, or real-world feasibility.
+
+Maintain a paper ledger with:
+
+`paper | year | venue/status | canonical URL | problem | core idea | delta vs predecessor | evidence | datasets | metrics | compute/setup | limitations | code | lineage stage | confidence`
+
+Use the ledger as the compact research memory. Do not keep full paper text in the working context after extracting verified notes and precise source locations.
+
+### 3. Read and interpret papers
+
+Escalate reading depth only when a paper survives the previous screening tier. Do not download or ingest every candidate PDF. Use the full paper for pivotal papers and disputed claims; inspect only the sections needed to verify supporting claims. For pivotal papers, extract:
+
+- problem formulation and assumptions
+- objective or key equations, with every symbol defined
+- architecture or algorithm steps
+- claimed contribution and the evidence supporting it
+- baseline fairness, dataset, metric, and compute conditions
+- ablations and failure cases
+- reproducibility details and official code availability
+- what later work retained, replaced, or challenged
+
+Default standard-mode budget:
+
+- discover and deduplicate at most 60 candidate papers from metadata
+- screen at most 20 papers using abstracts, surveys, citation context, and canonical metadata
+- perform structured section-level reading on at most 8 papers
+- deeply read at most 4 pivotal papers, including only necessary appendix sections
+
+These are ceilings rather than quotas. Expand a tier only when coverage has a clear gap, a central claim remains unresolved, or the user requests exhaustive research. Prefer one additional targeted paper over widening every tier.
+
+Separate author claims from your synthesis. Do not infer superiority across papers whose datasets, metrics, model scales, or compute budgets are not comparable. Never treat an abstract, AlphaXiv summary, search snippet, or benchmark leaderboard as a substitute for the paper's experimental context.
+
+### 4. Construct the technical lineage
+
+Organize the narrative by conceptual transitions rather than a flat chronological paper list:
+
+`problem and classical baseline → bottleneck → new mechanism → evidence → remaining limitation → next transition`
+
+Read [technical-deck-structure.md](references/technical-deck-structure.md). Include the classic-to-current route even when older work no longer leads benchmarks. Explain why it mattered and which idea survived.
+
+### 5. Build the interactive HTML presentation
+
+Read [html-presentation.md](references/html-presentation.md) and create the deliverable in a task-owned `output/` directory. The final file must open locally in a modern browser without a build step.
+
+Use interactions only when they improve technical understanding. Strong candidates include:
+
+- clickable technical-route timeline with method details
+- paper filters by year, family, task, or evidence status
+- method comparison table with sortable or selectable dimensions
+- architecture or algorithm step-through
+- metric and compute tradeoff chart with hover details
+- collapsible equations, experiment details, caveats, and citations
+
+Keep navigation presentation-friendly with keyboard controls, visible progress, direct section links, and a printable fallback. The first view of every section must remain meaningful without interaction.
+
+### 6. Verify
+
+Before delivery:
+
+- Re-open every pivotal paper and verify titles, authors, dates, URLs, equations, datasets, metrics, and claimed results.
+- Confirm that the lineage includes foundational, milestone, strong current, and important dissenting or negative evidence where available.
+- Confirm every comparison names the experimental conditions that make it valid.
+- Test keyboard navigation, mouse/touch interactions, filters, expandable content, external links, and print layout.
+- Inspect at desktop and mobile widths for overflow, clipped equations, unreadable figures, and inaccessible controls.
+- Check the browser console for errors and ensure the HTML works without a local server unless clearly disclosed.
+- Confirm that no large raw PDF text, duplicated abstracts, or unused research dumps were embedded in the final HTML or retained as deliverables.
+
+Deliver the final `.html` and mention material evidence gaps, inaccessible papers, or unverified preprints. Provide the paper ledger separately only when requested.
+
+## Boundaries
+
+- Never invent papers, citations, benchmark values, equations, code repositories, or publication status.
+- Label arXiv-only work as a preprint and distinguish first submission from the latest revision.
+- Do not call a method state of the art without a task, dataset, metric, date, and comparable evaluation setting.
+- Do not equate citation count, social attention, or benchmark rank with technical validity.
+- Do not recommend production adoption solely from paper results.

research-ppt/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "算法技术调研演示"
+  short_description: "从经典方法到最新论文完成算法调研并生成交互式 HTML 演示"
+  default_prompt: "使用 $research-ppt 调研一个算法主题，梳理从经典方法到最新论文的技术路线，并生成交互式 HTML 演示。"

research-ppt/references/academic-search.md

@@ -0,0 +1,43 @@
+# Academic search and paper verification
+
+## Tool routing
+
+Use connected scholarly tools when available. Prefer AlphaXiv for paper discussion and accessible explanations, arXiv for canonical preprint metadata and versions, Semantic Scholar or OpenAlex for citation graph discovery, Crossref or the venue site for publication metadata, and Papers with Code or official repositories for implementations and benchmark context.
+
+Tool output is discovery material, not authority. Verify important claims against the paper, official supplement, dataset page, or repository.
+
+When dedicated tools are unavailable:
+
+- query the arXiv API or arxiv.org with title, author, category, and date filters
+- search official proceedings such as ACL Anthology, CVF Open Access, PMLR, OpenReview, ACM, IEEE, or publisher DOI pages as appropriate
+- follow references and citing papers from a verified seed paper
+- use general web search only to locate canonical sources
+
+Do not automate authentication, bypass access controls, or rely on inaccessible paywalled text. Use a lawful author manuscript or preprint when available.
+
+## Query design
+
+Build synonym sets for the task, mechanism, historical terminology, and benchmark. Combine them with:
+
+- `survey`, `review`, or `tutorial`
+- `benchmark`, `dataset`, `ablation`, `replication`, `negative result`, or `limitations`
+- method-family names and predecessor names
+- venue/category and date constraints
+
+Run a forward search from classical terms and a backward search from current terminology. Record queries that materially define coverage.
+
+## Metadata rules
+
+- Use DOI links for published versions when available and arXiv links for preprint versions.
+- Record both first-submission and latest-revision dates when recency matters.
+- Preserve the declared venue status: accepted, under review, workshop, technical report, or preprint.
+- Deduplicate conference, journal, and arXiv versions; cite the version actually read.
+- Treat withdrawn papers and papers with material corrections explicitly.
+
+## Reading priority
+
+Read pivotal papers deeply. For supporting papers, retrieve only the sections needed to verify the exact claim. Prioritize method, experiment setup, results, ablations, limitations, and only the relevant appendix passages. Use external explanations to clarify, never to overwrite the authors' definitions or evidence.
+
+Do not repeatedly retrieve the same abstract, metadata, or paper section. Reuse the paper ledger and record a precise section, figure, table, equation, or page locator for later verification. Fetch the source again only when the stored note cannot support the final claim.
+
+For equations, transcribe from the source and verify notation. For diagrams, create an original explanatory representation or clearly label an adapted figure with its source and license status.

research-ppt/references/algorithm-research.md

@@ -0,0 +1,34 @@
+# Algorithm research framing
+
+## Coverage model
+
+Frame the survey across five layers when relevant:
+
+1. Concept: task definition, assumptions, notation, and evaluation target
+2. Classical foundations: statistical, optimization, signal-processing, information-theoretic, or early neural methods
+3. Modern technical routes: the main competing families and the bottleneck each addresses
+4. Current frontier: recent credible methods, scaling behavior, efficiency, robustness, and open problems
+5. Engineering implications: data, training, inference, evaluation, monitoring, and failure handling
+
+Depth matters more than filling all five layers. Omit a layer when it does not help explain the topic.
+
+## Technical comparison dimensions
+
+Select only dimensions that affect the user's decision:
+
+- formulation and inductive bias
+- training objective and optimization behavior
+- asymptotic complexity and measured resource use
+- dataset requirements and sensitivity to distribution shift
+- inference latency, throughput, memory, and deployment constraints
+- quality metrics and statistical uncertainty
+- robustness, safety, interpretability, and failure modes
+- implementation complexity, code maturity, and reproducibility
+
+Normalize notation across papers before comparison. If authors use the same term differently, preserve the distinction.
+
+## Freshness strategy
+
+For mature fields, start from authoritative surveys and trace backward to primary work, then perform a separate recent-paper search from the survey cutoff to the current date. For fast-moving fields, search the last 12-24 months explicitly and use citation graphs to connect recent papers to foundational work.
+
+Avoid arbitrary "top 10 papers" selections. Prefer a small set of lineage-defining papers plus enough alternative and negative evidence to show the actual decision space.

research-ppt/references/evidence-and-citations.md

@@ -0,0 +1,46 @@
+# Evidence and citations
+
+Use this reference for factual claims outside the papers themselves, such as framework releases, model cards, benchmark governance, hardware characteristics, or production case studies. Use [academic-search.md](academic-search.md) for paper-specific discovery and verification.
+
+## Source hierarchy
+
+Prefer sources in this order when they can answer the claim:
+
+1. Primary records: papers, official datasets, benchmark specifications, standards, model cards, and product documentation
+2. Reputable analysis: established research organizations, academic reviews, and transparent industry reports
+3. Credible reporting with named sources and clear dates
+4. Vendor or consultancy material, used with its commercial incentive visible
+5. Aggregators and informal commentary, used only as leads or clearly labeled perspective
+
+Recency matters most for fast-changing metrics, product capabilities, policy status, and forecasts. Older sources remain useful for definitions, history, and foundational research.
+
+## Claim discipline
+
+For each claim, retain the exact source passage, table cell, or dataset field until final verification. Preserve:
+
+- metric definition and unit
+- numerator and denominator
+- time period and publication date
+- geography and population
+- actual, estimate, target, or forecast status
+- scenario or methodology when relevant
+
+When calculating a growth rate, share, index, or conversion, cite the inputs and keep the formula in working notes. Do not mix nominal and real values, calendar and fiscal years, or stocks and flows without explicit normalization.
+
+## Confidence
+
+Use a simple internal rating:
+
+- High: direct primary evidence with a clear definition
+- Medium: reputable secondary evidence or consistent triangulation
+- Low: single interested source, unclear methodology, old data, or unresolved disagreement
+
+Low-confidence evidence can frame an open question but should not carry the central conclusion without a visible caveat.
+
+## Presentation citations
+
+In the HTML, map citations to the precise claim, equation, chart, table, or figure. Include author or organization, title, publication date, canonical URL, and access date. Add section, equation, figure, table, or appendix identifiers when relevant. For datasets, include version, split, filters, and retrieval date.
+
+Use concise inline citation markers linked to a complete references section. Show the source beside central quantitative evidence and any adapted figure. Avoid a generic bibliography that leaves claim provenance ambiguous.
+
+For web research completed on the current date, use the environment's current date as the access date. Never guess missing metadata.

research-ppt/references/html-presentation.md

@@ -0,0 +1,37 @@
+# Interactive HTML presentation
+
+## Delivery contract
+
+Create one self-contained `output/<topic-slug>-research.html` that opens locally in a modern browser. Inline the content, styles, scripts, and compact data. If a library is essential, bundle it locally when feasible; otherwise use a version-pinned CDN and disclose that offline use needs network access. Do not require npm, a build step, or a local server for ordinary viewing.
+
+Use semantic HTML, responsive CSS, and plain JavaScript unless the existing project already provides an appropriate framework. Avoid generated application scaffolding for a single presentation.
+
+## Presentation behavior
+
+- Treat each major section as a slide-like scene with a stable anchor.
+- Support previous/next controls, left/right arrow keys, Home/End, and a clickable progress indicator or table of contents.
+- Preserve normal scrolling as a fallback, especially on mobile and for printing.
+- Keep browser back/forward behavior meaningful when section hashes change.
+- Provide a print stylesheet that removes controls, expands essential collapsed material, and avoids splitting core figures where possible.
+- Respect `prefers-reduced-motion`; do not use looping or decorative animation.
+
+## Technical interactions
+
+Use native buttons, links, details/summary, selects, and checkboxes. Every control needs a visible label, keyboard access, focus indication, and an initial state that already communicates the main point.
+
+For equations, prefer MathJax or KaTeX only when needed and pin the version. Provide readable fallback text. For charts and route maps, prefer semantic HTML, CSS, or inline SVG; use D3 only for data-rich interactions. Do not redraw paper figures without explaining that they are simplified interpretations.
+
+External paper links must point to canonical destinations and open safely. Place citations adjacent to claims and include a complete reference section with DOI/arXiv/venue links.
+
+## Visual and accessibility requirements
+
+- Design first for a 16:9 desktop presentation while remaining usable at 320px width.
+- Avoid fixed-height text regions and horizontal page overflow.
+- Maintain strong contrast and do not encode meaning with color alone.
+- Provide accessible names or descriptions for charts and diagrams.
+- Keep code, tables, equations, and long URLs from overflowing.
+- Use progressive disclosure for derivations and experimental details, not for the central conclusion.
+
+## Validation
+
+Open the file through a browser automation or rendering tool when available. Test section navigation, hashes, filters, toggles, accordions, paper links, print preview, responsive layouts, and the browser console. If automated browser access is unavailable, perform static checks and disclose only limitations that affect confidence in the deliverable.

research-ppt/references/technical-deck-structure.md

@@ -0,0 +1,36 @@
+# Technical presentation structure
+
+Use this as a flexible narrative, not a mandatory section count.
+
+1. Topic, audience, and research cutoff
+2. Executive technical conclusions
+3. Problem definition, assumptions, and evaluation criteria
+4. Classical foundations and baseline
+5. Technical-route map from classical to current
+6. One or more transition sections: bottleneck, mechanism, evidence, limitation
+7. Current method-family comparison
+8. Representative paper deep dives
+9. Benchmark evidence with comparability caveats
+10. Efficiency, data, and deployment tradeoffs
+11. Failure cases, unresolved debates, and negative evidence
+12. Engineering implications and recommended experiments
+13. Outlook with observable research signposts
+14. Search method and references
+
+## Section rules
+
+- Introduce notation before equations and define every symbol near first use.
+- Explain mechanism before reporting benchmark deltas.
+- Pair every milestone with the limitation that motivated the next transition.
+- Use the same comparison dimensions across method families.
+- Give paper deep dives a reason for inclusion: foundational, transition-defining, current strong evidence, alternative route, or corrective result.
+- Keep conclusions conditional on dataset, scale, compute, and evaluation protocol.
+
+## Useful interactive views
+
+- Timeline: selecting a milestone reveals its problem, idea, evidence, and limitation.
+- Route map: selecting a branch highlights predecessor and successor relationships.
+- Comparison matrix: users choose a deployment constraint and see relevant tradeoffs.
+- Algorithm walkthrough: step controls update pseudocode, tensors, or data flow.
+- Evidence chart: users can toggle only genuinely comparable experimental groups.
+- Paper drawer: citation, abstract-level summary, verified contribution, limitations, and canonical links.

research-ppt/references/token-efficient-research.md

@@ -0,0 +1,66 @@
+# Token-efficient research
+
+## Default funnel
+
+Use staged retrieval so that detailed content enters context only after a paper proves useful.
+
+| Tier | Default ceiling | Read | Purpose |
+| --- | ---: | --- | --- |
+| Discovery | 60 papers | title, authors, year, venue/status, abstract snippet, citation links | maximize recall and identify terminology |
+| Screening | 20 papers | full abstract, introduction conclusion, survey or citation context | select lineage-defining and contrary evidence |
+| Structured reading | 8 papers | method overview, relevant experiments, limitations, selected figures/tables | extract comparable evidence |
+| Deep reading | 4 papers | necessary full sections, equations, ablations, appendix details | support pivotal explanations and disputed claims |
+
+The ceilings are defaults, not targets. Stop earlier when the technical lineage is covered and new papers repeat known mechanisms or evidence.
+
+## Promotion criteria
+
+Promote a paper to the next tier only when at least one condition holds:
+
+- it introduced or materially changed a lineage branch
+- it provides central comparative evidence
+- it challenges a conclusion or documents a failure mode
+- it is necessary to connect the classical and current terminology
+- it supplies implementation details needed by the target audience
+
+Do not promote a paper because it is merely recent, highly cited, or frequently mentioned.
+
+## Compact notes
+
+After reading, store conclusions in the paper ledger rather than retaining copied prose. Use concise paraphrases plus exact anchors:
+
+`claim | evidence value | condition | source section/figure/table/equation | confidence`
+
+Keep direct quotations only when wording itself matters. Store equations only when they are explained in the presentation. Retain benchmark rows only for methods that are meaningfully comparable.
+
+## Retrieval discipline
+
+- Start with metadata APIs or search results, then open canonical sources only for shortlisted papers.
+- Prefer HTML source or extracted text for targeted reading. Use PDF page images only when layout, figures, formulas, or tables require them.
+- Retrieve selected sections or page ranges when tools support it.
+- Avoid sending an entire survey and every paper it cites into the same context.
+- Use a survey to map terminology and lineage, then verify important statements in primary papers.
+- Deduplicate arXiv, conference, journal, and repository versions before reading.
+- Do not include full abstracts or raw paper text in the final HTML; include concise synthesis and citations.
+
+## Stop conditions
+
+Stop expanding the search when all of the following are true:
+
+- each major lineage branch has at least one verified representative
+- every central conclusion has adequate evidence
+- recent searches return mostly duplicate mechanisms or weaker evidence
+- important disagreements and limitations are represented
+- the research cutoff and remaining gaps can be stated honestly
+
+If a central claim remains unresolved after two targeted searches, present the uncertainty instead of continuing broad retrieval indefinitely.
+
+## User-selectable depth
+
+Interpret user requests as follows unless they define their own budget:
+
+- Quick: 30 discovery, 10 screening, 4 structured, 2 deep
+- Standard: 60 discovery, 20 screening, 8 structured, 4 deep
+- Deep: 100 discovery, 35 screening, 15 structured, 8 deep
+
+For Deep mode, warn only if external API cost, rate limits, or a materially long run is expected. Never trade source verification away merely to meet a token target; narrow scope or expose uncertainty instead.

static/deck.css

@@ -0,0 +1 @@
+:root{font-family:Inter,"Microsoft YaHei",sans-serif;color:#eef3fb;background:#080b12;color-scheme:dark;--accent:#7aa2ff;--muted:#9aa8bd}*{box-sizing:border-box}body{margin:0;background:radial-gradient(circle at 80% 10%,#17213d 0,#080b12 35%);color:#eef3fb}nav{position:fixed;z-index:10;left:0;right:0;top:0;height:56px;display:flex;align-items:center;gap:10px;padding:0 3vw;background:rgba(8,11,18,.9);backdrop-filter:blur(12px);border-bottom:1px solid #273143}nav strong{margin-right:auto;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}nav button{border:1px solid #344158;background:#131c2b;color:#eef3fb;border-radius:7px;padding:7px 10px;cursor:pointer}.slide{display:none;min-height:100vh;padding:11vh 8vw 9vh;align-content:center;max-width:1400px;margin:auto}.slide.active{display:grid}.eyebrow{letter-spacing:.14em;color:var(--accent);font-size:12px}h1{font-size:clamp(42px,7vw,94px);max-width:1050px;line-height:1.02;margin:.25em 0}h2{font-size:clamp(30px,4vw,58px);margin:.2em 0 .6em}.subtitle,.takeaway{font-size:clamp(20px,2.4vw,34px);color:#c8d3e7;max-width:1000px}li,p,td,th{font-size:clamp(16px,1.25vw,21px);line-height:1.55}li{margin:.45em 0}.timeline{display:flex;gap:10px;overflow-x:auto;padding:12px 0}.milestone{min-width:150px;text-align:left;padding:13px;border:1px solid #344158;border-radius:9px;background:#101827;color:#eaf0fb;cursor:pointer}.milestone span{display:block;color:var(--accent);font-size:12px}.milestone[aria-pressed="true"]{border-color:var(--accent);background:#182643}#milestone-detail{margin-top:18px;padding-top:16px;border-top:1px solid #344158}.table-wrap{overflow:auto}table{width:100%;border-collapse:collapse}th,td{text-align:left;vertical-align:top;border-bottom:1px solid #344158;padding:12px}details{margin-top:20px;border-top:1px solid #344158;padding-top:14px}summary{cursor:pointer;color:var(--accent)}.sources,.references span{font-size:13px;color:var(--muted)}.references li{font-size:14px}.references a{color:#a9c3ff}.progress{position:fixed;bottom:0;left:0;right:0;height:4px;background:#1b2434}.progress span{display:block;height:100%;background:var(--accent);transition:width .25s}@media(max-width:700px){nav strong{display:none}.slide{display:block;min-height:auto;padding:90px 22px 50px;border-bottom:1px solid #273143}.slide.active{display:block}.progress{display:none}}@media print{nav,.progress{display:none}.slide{display:block;min-height:auto;break-after:page;padding:10mm;background:#fff;color:#111}.references{break-after:auto}body{background:#fff;color:#111}.subtitle,.takeaway,.sources,.references span{color:#333}a{color:#111}}

static/deck.js

@@ -0,0 +1,8 @@
+const slides=[...document.querySelectorAll('.slide')];let current=0;
+const counter=document.getElementById('counter');const bar=document.getElementById('progress-bar');
+function show(index,push=true){current=Math.max(0,Math.min(slides.length-1,index));slides.forEach((s,i)=>s.classList.toggle('active',i===current));counter.textContent=`${current+1} / ${slides.length}`;bar.style.width=`${(current+1)/slides.length*100}%`;if(push)history.replaceState(null,'',`#${slides[current].id}`);slides[current].scrollIntoView({block:'start'});}
+document.getElementById('prev').onclick=()=>show(current-1);document.getElementById('next').onclick=()=>show(current+1);
+document.addEventListener('keydown',e=>{if(['ArrowRight','PageDown'].includes(e.key))show(current+1);if(['ArrowLeft','PageUp'].includes(e.key))show(current-1);if(e.key==='Home')show(0);if(e.key==='End')show(slides.length-1);});
+const initial=slides.findIndex(s=>`#${s.id}`===location.hash);show(initial>=0?initial:0,false);
+const lineage=document.getElementById('lineage');if(lineage){const data=JSON.parse(lineage.dataset.lineage||'[]');const detail=document.getElementById('milestone-detail');function pick(i){const x=data[i]||{};detail.innerHTML=`<h3>${escapeText(x.method||'')}</h3><p><strong>突破：</strong>${escapeText(x.innovation||'')}</p><p><strong>解决的瓶颈：</strong>${escapeText(x.bottleneck||'')}</p><p><strong>遗留限制：</strong>${escapeText(x.limitation||'')}</p>`;document.querySelectorAll('.milestone').forEach((b,j)=>b.setAttribute('aria-pressed',String(i===j)));}document.querySelectorAll('.milestone').forEach((b,i)=>b.onclick=()=>pick(i));if(data.length)pick(0);}
+function escapeText(value){const d=document.createElement('div');d.textContent=value;return d.innerHTML;}

tests/test_app.py

@@ -0,0 +1,22 @@
+import unittest
+
+from app import deduplicate, render_presentation, safe_slug
+
+
+class AppTests(unittest.TestCase):
+    def test_slug(self):
+        self.assertEqual(safe_slug("Diffusion Transformer 研究"), "diffusion-transformer")
+
+    def test_deduplicate_versions(self):
+        papers = [{"id": "1234.5678v1"}, {"id": "1234.5678v2"}]
+        self.assertEqual(len(deduplicate(papers)), 1)
+
+    def test_render_is_downloadable_document(self):
+        report = {"title": "Test", "executive_summary": ["Result"], "lineage": [], "sections": [], "comparisons": [], "open_questions": []}
+        output = render_presentation(report, [], "2026-01-01")
+        self.assertIn("<!doctype html>", output)
+        self.assertIn("保存 PDF", output)
+
+
+if __name__ == "__main__":
+    unittest.main()