scholar-slides

# scholar-slides Turn a research paper (or topic) into a **fidelity-first** academic slide deck. Academia inverts the priorities of a normal deck tool: **source fidelity > polish, evidence > persuasion, editability > flash.** Equations, tables, numbers, figures, and citations stay **true text/vector and traceable to the source** — never rasterized by an image model, never fabricated. Design rationale and the survey it is built on live in `docs/`; build plan in `IMPLEMENTATION_PLAN.md`. ## Locked stack (see docs/03-design-proposal.md §0) - **Render backend:** reveal.js + KaTeX → vector PDF (Playwright) + editable PPTX (parity-tested). Beamer later. - **Default deck type:** lab meeting / journal club (组会) — reading-first, high density. - **Citations:** Zotero-first (`mcp__zotero__*`), Crossref/arXiv/DOI fallback. - **Language:** bilingual, English-default. ## The non-negotiable integrity gate (ALWAYS on — see references/integrity.md) Apply at every stage; enforced at Checkpoint 3: - **Never fabricate** numbers, citations, or figures. Everything traces to the source digest. - **Math/tables/citations stay vector/text** — never an image model's pixels. - **Reuse real figures** (bbox-cropped + `Figure N [cite]`); a conceptual schematic may be redrawn only if labeled "redrawn, not from source". - **Flag, don't invent:** an unresolved figure/number/citation emits a visible `[MISSING: …]` / `[UNVERIFIED: …]` placeholder surfaced to the user — never a silent fill. - **Provenance is mandatory:** every reused asset carries its source; every claim is traceable. ## Pipeline (7 stages, 3 human checkpoints) ``` INPUT → 1.INGEST/DIGEST → [CKPT-1] → 2.DECK-TYPE → 3.OUTLINE → [CKPT-2] → 4.PER-SLIDE SPEC → 5.RENDER → 6.SELF-REVIEW(QA) → [CKPT-3] → 7.EXPORT ``` 1. **Ingest → typed digest** — `references/ingestion.md`. Run `scripts/prepare_source.py <pdf|arXiv id|arXiv URL>` to build the digest-input bundle (text, figure/table inventory with bboxes, cropped figures), then synthesize the typed **paper digest** from it (grounded in the bundle, never invented). **→ [CKPT-1]** confirm the digest with the user (contributions, headline result, figure→slide map, any FLAGGED asset). 2. **Deck-type & parameters** — `references/deck-types.md`. Pick deck type (default 组会), audience, time budget → slide budget, density register, required archetypes. 3. **Narrative outline** — `references/narrative.md`. Re-sequence the paper into talk order; action-title per slide; arc-tension check. **→ [CKPT-2]** approve the story arc. 4. **Per-slide spec** — `references/slide-spec.md`. One self-contained, on-disk spec per slide (layout, content, equations, figures, citations, speaker notes). 5. **Render** — `references/math.md`, `references/figures-tables.md`, `references/citations.md`, `references/charts.md`, `references/design-system.md`, `references/export.md`. reveal.js + KaTeX; real tables; real bbox-cropped figures (furniture-stripped; one panel per slide for multi-panel); data-bound redrawn charts; Zotero/BibTeX citations. Pick the visual theme via `meta.theme` (`journal-club` default / `conference`). 6. **Self-review QA** — `references/qa-self-review.md` + `references/integrity.md`, then the **aesthetics loop** in `references/aesthetics-review.md`. Integrity scan + static validator + render screenshots + narrative/timing checks; the render pass also measures geometry deterministically (canvas voids, figure-text projected below the 12px legibility floor). Then score the rendered *pixels* on the 6-dimension rubric (adversarial persona), **write the scores to `<deck>/aesthetics_report.json`** (schema in aesthetics-review.md), and rework any slide with a dimension ≤ 2 or total < 18 until the report's `rework` list is empty — the QA gate flags a missing report (P3) and an unspent rework list (P2). It also nudges on bullet-ratio and layout monotony. **→ [CKPT-3]** truth sign-off: review every `[MISSING]`/`[UNVERIFIED]` and generated asset. 7. **Export** — `references/export.md`. Vector PDF (projection) + speaker notes + editable PPTX; verify the PPTX preserves the spec natively with `scripts/verify_pptx_parity.py` (protects the minimal-manual-edits promise). Regress the whole corpus with `node scripts/run_benchmark.mjs`. Read **only** the reference file for the stage you are in (progressive disclosure — never glob `references/`). Each stage reads the **confirmed artifact of the prior stage** — the digest (Stage 1, user-confirmed at CKPT-1) and then `deck.json` — rather than re-deriving from the paper. ## Scripts (`scripts/`) Ingestion — pipeline stage 1 (Python, via `./.venv/bin/python`; deps in `requirements.txt`): - `prepare_source.py` — **Stage 1 entry point**: PDF/arXiv → digest-input bundle. - `ingest_pdf.py` — PyMuPDF text+layout extraction; arXiv-id detection. - `detect_figures.py` — figure/table caption inventory + bounding-box localization. - `crop_figure.py` — clean single-figure bbox crop (no neighbor columns). Deck build & render — pipeline stage 5 (Node, via `node`; deps in `package.json`, `npm install` + `npx playwright install chromium`): - `build_deck.mjs` — **render entry point**: `deck.json` → self-contained reveal.js deck. - `render_deck.mjs` — deck → one-page-per-slide **vector PDF** (and per-slide PNGs for QA). - `lib/` — `layouts` (registered-layout lock), `math` (KaTeX), `table`, `figure`, `escape`, `qa`. Citations & QA — pipeline stages 5–6 (citations = Python; QA = Node): - `fetch_bib.py` — citation resolver (arXiv/DOI/Crossref) with order-sensitive title verification. - `qa_report.mjs` — **CKPT-3 gate**: integrity scan + `validate_deck.mjs` + `verify_slides.mjs` + timing. Speaker notes (Node): - `speaker_notes.mjs` — `deck.json` → `notes.md` handout + bilingual talk-length estimate. - `lib/notes.mjs` — timing + handout pure logic; design system in `assets/templates/themes/`. Export & charts — pipeline stage 7 (export = Node; charts = Python): - `export_pptx.mjs` — `deck.json` → **editable PPTX** (native text/tables/notes; figures+equations as images). - `make_chart.py` — chart spec → **data-bound** Okabe–Ito plot (values plotted verbatim). Tests: `./.venv/bin/python -m pytest` (Python) and `node --test tests/deck.test.mjs tests/qa.test.mjs tests/notes.test.mjs tests/pptx.test.mjs` (Node). ## Learnings: read before changing pipeline behavior [`learnings/`](learnings/) holds post-incident notes with measured numbers (figure-size vertical budget, craft rules vs looks). Scan it before changing rendering, sizing, or QA behavior; append a dated note after any rework-worthy surprise. ## Build status The whole pipeline is implemented and validated on real papers. Not built: Beamer export, OCR for scanned PDFs, draft-deck ingestion; conference/答辩 deck types are authoring guidance in `references/deck-types.md` (no dedicated code). A deck is "done" only after the CKPT-3 human truth sign-off — the gate surfaces defects but cannot certify truth.