paper-report-ppt-python

name

paper-report-ppt-python

description

Create rigorous academic literature-report PowerPoint decks from paper PDFs as one standalone Python builder, with complete bibliographic information, Google Scholar evidence-driven key-author profiles, editable Office Math, speaker notes, natural first-use terminology definitions, exhaustive figure-by-figure coverage, and explicit narrative-flow audits. Use for journal clubs, paper presentations, research-group literature reports, or any PPTX that must explain every figure without breaking the scientific story.

Python Literature-report PPT

Use this skill as a standalone workflow for academic content architecture, Python implementation, editable formulas, Microsoft PowerPoint rendering, and validation. Always start from assets/build_paper_report_template.py; do not depend on another skill at runtime or while assembling the builder.

assets/build_paper_report_template.py is a paper-agnostic scaffold. It must not contain a real paper's title, authors, DOI, figure inventory, claims, panel crops, or audit rows. Copy and customize it into build_<topic>_ppt.py next to the supplied paper; that generated builder is the paper-specific source of truth.

When this skill is explicitly invoked, keep the Python/python-pptx route required here. Apply general presentation visual-quality rules without switching the implementation to another backend.

Required deliverables

Create next to the paper:

• build_<topic>_ppt.py: complete source of truth; no JSON slide specification;
• <topic>_文献汇报.pptx;
• ppt_work/rendered_slides/: Microsoft PowerPoint render images for final visual inspection;
• ppt_work/: all temporary equation, PDF-export, crop, render, and QA files. Keep this name short because Microsoft PowerPoint may hang on excessively long export paths.

The generated builder must remain compatible with uv run and must not import from either skill at runtime. The default execution path still uses the workspace-root .venv described below. It must require --paper-pdf, read that PDF during every build, and reject an empty or unresolved figure inventory. It must refuse to overwrite existing output unless --force explicitly names that target. Unless the user explicitly overrides a path, derive the PPTX, working directory, rendered slides, and all temporary files from the supplied PDF directory. Do not use /tmp, /private/tmp, or another system temporary root for this workflow.

Python environment

At the start of the task, treat the current working directory as the workspace root. Keep the reusable Python environment at <workspace-root>/.venv even when the paper PDF and generated builder are elsewhere. Do not create a separate virtual environment beside each paper.

1. Record the workspace root before changing directories, for example PPT_WORKSPACE_ROOT="$PWD".
2. Reuse $PPT_WORKSPACE_ROOT/.venv when it exists and its Python can import the required packages.
3. If it does not exist, create it with uv venv "$PPT_WORKSPACE_ROOT/.venv".
4. Install only the required local dependencies with:

uv pip install --python "$PPT_WORKSPACE_ROOT/.venv/bin/python" \
  "lxml>=5.3" "pillow>=11.0" "python-pptx>=1.0.2"

5. Run the builder with $PPT_WORKSPACE_ROOT/.venv/bin/python /absolute/path/build_<topic>_ppt.py ... by default.
6. Never install these packages globally. Keep the builder's PEP 723 metadata so uv run /absolute/path/build_<topic>_ppt.py ... remains a portable fallback.

Pandoc, Poppler (pdfinfo, pdftotext, and pdftoppm), and Microsoft PowerPoint remain required external tools; the Python virtual environment does not replace them.

Evidence preparation

Before writing slides, read the paper sufficiently to extract:

• exact title, journal, year, volume/article number, DOI;
• complete author order, affiliations, equal-contribution and corresponding-author marks;
• correspondence details, author contributions, and collaboration structure;
• Google Scholar profiles, portraits, metrics, recent publications, and highly cited publications for key authors when profiles are available;
• research question, hypotheses, methods, evidence, limitations, and conclusions;
• every numbered figure and every panel label in the supplied paper PDF;
• all specialist terms, abbreviations, symbols, structural motifs, and metrics needed by the story.

Create the three audit tables defined in references/literature-report-audit.md before finalizing the deck. Keep them as Python data or code comments inside the standalone builder, not as JSON.

Slide architecture

Design the story before assigning figures to slides. Write a question-and-evidence chain that a reader can follow without opening the paper: motivation → unresolved question → approach → observations → eliminated explanations → mechanism → validation or counterexample → contribution and limits. Then map figures and panels into the point where each one best advances that chain.

1. Make slide 1 the exact paper title and bibliographic information.
2. Make slide 2 a one-page author overview titled with the exact paper title. Place the complete author list beneath it and profile only the two most relevant key authors. Follow the author-page content contract below.
3. State the core question and conclusion early, then build a cumulative claim-evidence-consequence story.
4. Give each slide one main claim and use a conclusion-style title. Reading only the slide titles in order must reveal the paper's complete argument.
5. Make the visible slides self-contained. A reader who has neither the paper nor the speaker notes must still understand the research question, essential method, experimental or simulation conditions, axes, units, legend encodings, key observation, and scientific consequence.
6. Keep essential reasoning on the slide. Speaker notes may expand explanations, likely questions, and timing, but must not contain a missing premise or conclusion required to understand the story.
7. Define every unfamiliar concept at its first narrative appearance:
   • Chinese name;
   • English term and abbreviation or symbol;
   • one-sentence operational meaning in this paper;
   • how to read its magnitude, sign, color, curve, or structural encoding when relevant.
8. Never use an abbreviation or specialist symbol before defining it.
9. End with synthesis, contribution beyond prior work, limitations, and productive discussion questions.

Author-page content contract

Read references/author-profile-workflow.md before researching or building slide 2. Follow its Scholar extraction, topic-clustering, sourcing, fallback, layout, and visual-QA rules.

The visible page must make the paper and its key people understandable at a glance:

• Use the exact paper title as the slide title. Place the complete author list immediately below it in smaller type, preserving order, affiliation indices, equal-contribution marks, and corresponding-author marks.
• Profile exactly two key authors by default: normally a first/equal-first author who drove the work and a corresponding senior investigator or theory/method collaborator central to the paper. Use three only when the user asks or the paper genuinely cannot be explained with two.
• For each profile, show a Scholar portrait when available, English name, Chinese name when reliably known, paper role, verified current position, verified current institution, and concise research direction.
• Derive 近期论文聚类 from the titles of the latest Scholar publications sorted by year. Derive 高被引论文聚类 from the titles of the highest-cited Scholar publications sorted by citations. Use compact topic phrases, not prose biography, publication titles, or unsupported intellectual-lineage claims.
• Keep Scholar citations, h-index, and i10-index as small secondary information near the card bottom. Never make metrics the visual center. Add Google Scholar，查询于 YYYY-MM-DD on the page.
• Use an institutional or laboratory page for current position and institution. Scholar may identify a profile and supply publications, portrait, research labels, and metrics, but it is not sufficient evidence for a formal title unless it states one explicitly.
• Omit an unavailable portrait, metric, Chinese name, or formal title instead of guessing. Write a neutral description such as 公开主页未列明正式职称 only when the missing fact would otherwise be misleading.
• Keep the full affiliation index in one compact line near the bottom. Move detailed author-contribution wording and supporting source URLs to speaker notes unless a short, explicitly sourced role fits naturally on the card.
• Do not add collaboration-chain diagrams, generic CV paragraphs, award lists, publication-count claims, or decorative metric cards to this page.

Before accepting the page, hide portraits and metrics and read only the remaining text. It must still communicate the exact paper, complete authorship, key-author identity, institutional context, recent work, and recognized work.

Exhaustive figure coverage

• Give every numbered figure in the supplied paper at least one dedicated slide. Do not silently omit a figure because it appears secondary to the chosen story.
• If the supplied PDF contains numbered supplementary figures, cover each of them as well; place lower-priority evidence in a clearly signposted appendix only when presentation time requires it.
• Let the figure or its relevant panels dominate each dedicated slide. Identify the original figure number and panel labels visibly.
• For a composite figure, first determine its internal argument. Split panels across multiple slides when necessary for legibility or explanation; a figure may therefore occupy several consecutive or separated slides.
• Do not use paper figure order as the default slide order. Order evidence by the audience's question chain and causal logic. Figures and panels may be reordered, split, revisited, or placed non-consecutively when that makes the mechanism clearer.
• When panels are reordered, visibly retain the original figure and panel identifiers, conditions, legends, and provenance. Add enough local context that the reader does not need an earlier unseen panel or the original caption.
• Do not redraw, smooth, recolor, or alter scientific data. Crop or enlarge panels without changing their content, and explain any omitted legend area.
• For every figure slide, explain: what is plotted or depicted, how to read it, the key observation, what claim it supports, and why the next slide follows.
• Expand the total slide count as needed. Figure coverage and narrative clarity take priority over an arbitrary 16–18 page target.

Standalone story test

Before final delivery, perform a slide-only read with the paper and speaker notes closed. The visible deck must allow a domain student to retell:

1. why the problem matters and what was unknown;
2. what the authors did and under which essential conditions;
3. what each decisive piece of evidence shows;
4. which alternative explanations were rejected;
5. how the proposed mechanism follows from the evidence;
6. what the paper contributes, what remains uncertain, and what should be tested next.

If any answer requires consulting the paper, add the missing definition, method context, visual reading rule, or reasoning step to the relevant slide. Do not solve a slide-only comprehension gap only in speaker notes.

Notes and formulas

• Use editable native Office Math for display and inline formulas.
• Add complete Chinese speaker notes to every slide: speaking order, visual encoding, terminology, likely misreadings, transition to the next slide, and estimated time.
• Keep total talk time aligned with the user's target by moving nonessential detail to appendix slides rather than deleting figure coverage.

Final rendering

• Render final slides with Microsoft PowerPoint followed by Poppler pdftoppm; this is the only accepted visual authority.
• Render automatically after a successful build. Default the PPTX to <paper-directory>/<paper-stem>_文献汇报.pptx, the work directory to <paper-directory>/ppt_work, and PNG files to <work-dir>/rendered_slides.
• Default to --render-backend powerpoint, record the selected backend, and require equal PPTX, exported PDF, and PNG page counts.
• Identify the opened presentation by its absolute path. Never export an unrelated active presentation.
• On first use, ask the user to allow Codex or its terminal host to control Microsoft PowerPoint under System Settings > Privacy & Security > Automation. Do not change that permission automatically.
• Permit --render-backend libreoffice only for diagnostics. Mark it final_eligible=false and do not deliver it as final QA evidence.

Mandatory semantic QA

Read references/literature-report-audit.md and complete all three audits:

1. Figure coverage: every figure/panel maps to at least one slide and a scientific claim, regardless of paper order.
2. Slide logic: every adjacent pair has an explicit reason to follow; each slide records input, claim, evidence, consequence, and bridge. The ordered rows must describe the audience's reasoning path rather than the paper's section order.
3. Terminology: every professional term is defined at first use and used consistently afterward.

Revise until no audit row is unresolved. Then run structural validation, render every slide with Microsoft PowerPoint, and visually inspect all pages. Use references/builder-contract.md for final acceptance.