paperbanana-slide-deck

PaperBanana Slide Deck

End-to-end slide deck creation and modification. Two deck modes (image and editable, chosen explicitly in Phase M), and within image mode two workflows: creating new decks from scratch, and regenerating existing decks after prompt edits.

Image pipeline: Content → Style Selection → Outline → Prompts → Image Generation → PPTX Merge Editable pipeline: Content → slide-spec.json (native text/table/chart/shape/line/group) → validate → build PPTX → render previews → Critic review → revise spec → rebuild

Phase M: Deck mode selection

Record exactly one line in deck-mode.txt: image or editable.

• Use editable when the user asks to edit text/tables/charts/connectors in PowerPoint or explicitly asks for editable PPTX.
• Use image when the user asks for generated full-slide artwork or preserves the existing PaperBanana image workflow.
• If both are plausible, ask before generation. Do not infer from file presence.
• editable requires slide-spec.json; a missing or invalid spec is an error. Never fall back to image mode while claiming editability.

Mode Detection (image mode)

Within image mode, determine the workflow by checking the target directory:

Condition	Mode	Start Phase
Target dir missing OR no outline.md	New	Phase R (full RDIV)
Target dir has outline.md + prompts/	Modify	Phase I (generate + merge)

In Modify mode, the user has already edited prompts or outline externally. Skip directly to Phase I.

Dependencies

Component	Role	Location
google-genai SDK	Path B image generation	pip install google-genai
PaperBanana CLI	Path A image generation	python -m paperbanana.cli slide-batch
merge-to-pptx.ts	PPTX merge (image mode)	plugins/paperbanana-slide-deck/scripts/merge-to-pptx.ts
build-deck.ts	Explicit --mode image|editable router	plugins/paperbanana-slide-deck/scripts/build-deck.ts
Editable renderer	slide-spec.json → native PPTX	plugins/paperbanana-slide-deck/scripts/editable/
Style libraries	Style presets (4 sources, 150+)	See R1 for discovery paths
Bun	Run build/merge scripts	bun

Editable Mode Workflow

When deck-mode.txt says editable, skip Phases R/D/I below and follow this loop instead (contract details and full example: references/editable-slide-spec.md):

1. Generate only text-free assets (photos, illustration panels — no rendered text) with PaperBanana; record each asset's SHA-256.
2. Author slide-deck/{topic-slug}/slide-spec.json — native text, shape, line, table, chart, image, and group elements on the 13.333×7.5 in canvas, with [Sources] speaker notes per slide.
3. Validate + build (fail-closed; a missing or invalid spec is an error, never a silent image-mode fallback):

bun "${SKILL_DIR}/scripts/build-deck.ts" --mode editable "slide-deck/{topic-slug}"

1. Render PPTX previews with LibreOffice + Poppler (soffice --headless --convert-to pdf, then pdftoppm -png -r 150 … slide → slide-NN.png).
2. Run Critic on the previews (preview-only; never edits the PPTX):

python3 "${SKILL_DIR}/scripts/editable/review-editable.py" \
  --spec "slide-deck/{topic-slug}/slide-spec.json" \
  --rendered-dir "slide-deck/{topic-slug}/rendered" \
  --output "slide-deck/{topic-slug}/critic-review.json"

1. Map findings to element IDs (suggestions arrive as slide-id/element-id: …), revise slide-spec.json, and rebuild. Repeat until clean.

Phase R: Research (New Mode Only)

Skip this phase entirely in Modify mode.

R1: Discover style libraries — Scan all four sources and merge into a unified list.

# Source 0 (PRIMARY): Local extended library (123 styles from Fooocus/ComfyUI, structured)
LOCAL_STYLES="$(find ~/.claude/skills .claude/skills -maxdepth 1 -name 'paperbanana-slide-deck' -type d 2>/dev/null | head -1)/references/styles"

# Source 1: baoyu-slide-deck styles (16 slide-optimized)
BAOYU_SLIDE=$(ls -td ~/.claude/plugins/cache/baoyu-skills/content-skills/*/skills/baoyu-slide-deck/references/styles 2>/dev/null | head -1)

# Source 2: baoyu-infographic styles (20 visual-rich)
BAOYU_INFOG=$(ls -td ~/.claude/plugins/cache/baoyu-skills/content-skills/*/skills/baoyu-infographic/references/styles 2>/dev/null | head -1)

# Source 3: theme-factory themes (10 color/typography presets)
THEME_FACTORY=$(ls -td ~/.claude/plugins/cache/anthropic-agent-skills/document-skills/*/skills/theme-factory/themes 2>/dev/null | head -1)

Merge: Glob all four directories for *.md, deduplicate by filename (priority: baoyu-slide-deck > local > baoyu-infographic > theme-factory). Present the full unified list to user during R3.

If none found: Use PaperBanana's 23 built-in presets.

R2: Analyze content — Topic, audience, tone, recommended slide count.

R3: Style recommendation — Recommend 2-3 styles based on content signals. See references/style-guide.md for the full style-to-content mapping table.

R4: Interactive selection — Use AskUserQuestion for style, audience, and slide count.

R5: Save analysis — Create slide-deck/{topic-slug}/analysis.md.

Phase D: Design (New Mode Only)

In Modify mode, the user handles prompt edits directly.

D1: Load style spec — Read from baoyu styles or PaperBanana built-ins.

D2: Generate outline — Create outline.md with slide structure. See references/outline-format.md.

D3: Optional outline review — Ask user if they want to review before proceeding.

D4: Generate prompts — For each slide, create prompts/NN-slide-{slug}.md. Each prompt file has the style instructions block, then ---, then the slide-specific content and design requirements.

Phase I: Implement (Both Modes)

Step I1: Image Generation (Dual Path)

Path A — PaperBanana CLI (preferred, has critic quality review):

cd <project_root>
python -m paperbanana.cli slide-batch \
  --prompts-dir "slide-deck/{topic-slug}/prompts" \
  --output-dir "slide-deck/{topic-slug}" \
  --resolution 4k \
  --iterations 2

Auto-degrade trigger: Switch to Path B if any slide (not just the first) hits one of these. Don't keep retrying Path A:

• RetryError / ResourceExhausted / HTTP 429 (rate-limited)
• ServerError (5xx) or non-429 ClientError (4xx)
• Critic takes longer than 3 minutes on any single slide
• User reports "一直 429" / persistent rate limits → degrade immediately, skip further Path A retries

Distinguish two 429 sources:

Source	Symptom	Response
Critic 429 (VLM rate limit)	Error inside critic loop, Path A specific	Auto-degrade to Path B (no critic → bypasses the issue)
Image-gen 429 (gemini-3-pro-image-preview)	Same error in Path B	Exponential backoff: time.sleep(30 * 2**retry) up to 5 min, then surface to user

Partial-batch recovery: If some slides were already generated before 429 hit, preserve existing PNGs and resume from the next missing slide (cross-reference prompts/*.md with existing NN-slide-*.png).

Note (upstream sync pending): Upstream paperbanana CLI (≥ #129) has native batch_checkpoint.json for Path A slide-batch — resume is automatic there. The skip logic above is for the Path B fallback code, which doesn't yet use the upstream checkpoint format.

Path B — Direct Gemini API (fallback, no critic, stable):

from google import genai
from google.genai import types
from PIL import Image
from io import BytesIO
import base64, os, time

# Read API key from paperbanana/.env
client = genai.Client(api_key=GOOGLE_API_KEY)

config = types.GenerateContentConfig(
    response_modalities=['IMAGE'],
    image_config=types.ImageConfig(
        aspect_ratio='16:9',
        image_size='4K',
    ),
)

MAX_RETRIES = 5   # after which surface to user
BASE_SLEEP = 30   # seconds

for prompt_file in sorted(os.listdir(prompts_dir)):
    name = prompt_file.replace('.md', '')
    out_path = os.path.join(output_dir, f'{name}.png')

    # Partial-batch resume: skip slides already generated
    if os.path.exists(out_path):
        continue

    with open(os.path.join(prompts_dir, prompt_file), 'r', encoding='utf-8') as f:
        prompt_text = f.read()

    # Exponential backoff on 429 / transient errors
    for retry in range(MAX_RETRIES):
        try:
            response = client.models.generate_content(
                model='gemini-3-pro-image-preview',
                contents=prompt_text,
                config=config,
            )
            break
        except Exception as e:
            msg = str(e).lower()
            if '429' in msg or 'resource' in msg or 'rate' in msg:
                wait = min(BASE_SLEEP * (2 ** retry), 300)  # cap at 5 min
                time.sleep(wait)
                continue
            raise  # non-429 error → surface immediately
    else:
        raise RuntimeError(f'{name}: 429 after {MAX_RETRIES} retries, surface to user')

    for part in response.candidates[0].content.parts:
        inline = getattr(part, 'inline_data', None)
        if inline and getattr(inline, 'data', None):
            data = inline.data
            img_bytes = base64.b64decode(data) if isinstance(data, str) else data
            img = Image.open(BytesIO(img_bytes))
            img.save(out_path, 'PNG')
            break

    time.sleep(BASE_SLEEP)  # baseline cooldown between slides

The API key is in <project_root>/paperbanana/.env as GOOGLE_API_KEY. Read it with dotenv or manually.

Step I2: Smart Cleanup (Pre-Merge)

Run AFTER I1 generation, not before. I1 is partial-batch-aware and skips already-generated slides; Cleanup's job is only to remove PNGs whose prompt was deleted/renamed since the last run. Running Cleanup before I1 would delete valid WIP slides from a resumed batch.

Sequencing: I1 (generate + resume) → I2 (cleanup orphans) → I3 (merge).

1. Scan prompts/*.md → build expected PNG set (e.g. 01-slide-hook.md → 01-slide-hook.png)
2. Scan target directory for *.png files matching pattern NN-slide-*.png
3. Delete slide PNGs NOT in expected set (orphans from renamed/deleted prompts)
4. Preserve non-slide PNGs (e.g. logo.png, background.png) and all expected-set PNGs

Step I3: Merge to PPTX

# Locate skill directory dynamically (works on any platform)
SKILL_DIR="$(find ~/.claude/skills .claude/skills -maxdepth 1 -name 'paperbanana-slide-deck' -type d 2>/dev/null | head -1)"
bun "${SKILL_DIR}/scripts/merge-to-pptx.ts" "slide-deck/{topic-slug}"

If merge script unavailable: inform user that PNG images are ready but PPTX merge requires bun and the local merge-to-pptx.ts script.

Phase V: Verify (Both Modes)

V1: Display results — Read and display each generated slide image. Report total slides, output directory, PPTX file path.

V2: User feedback — Ask:

• "Looks great, done!"
• "Regenerate — I'll tell you what to fix in the prompts"

V3: Regeneration — If user wants changes:

1. User edits the specific prompt files
2. Regenerate ALL slides (not just changed ones — ensures visual consistency)
3. Smart cleanup + re-merge PPTX
4. Return to V1

Fallback Behavior

Situation	Fallback
All style libraries missing	Use PaperBanana built-in presets
Local merge script missing	Output PNG only, skip PPTX
Bun/npx missing	Skip PPTX merge, inform user
Critic 429 / RetryError	Auto-degrade to Path B (no critic)
Image-gen 429 in Path B	Exponential backoff up to 5 min, then surface
Partial batch already generated	Resume from next missing slide, preserve existing PNGs

Output Structure

slide-deck/{topic-slug}/
  analysis.md            ← R phase (New mode only)
  outline.md             ← D phase
  prompts/               ← D phase
    01-slide-hook.md
    02-slide-cover.md
    ...
  01-slide-hook.png      ← I phase
  02-slide-cover.png
  ...
  {topic-slug}.pptx      ← I phase

Quick Reference

# Path A: PaperBanana CLI batch
python -m paperbanana.cli slide-batch --prompts-dir prompts/ --resolution 4k --iterations 2

# Path A: single slide (supports --vlm-model)
python -m paperbanana.cli slide --input prompt.md --resolution 4k

# List available styles
python -m paperbanana.cli slide --list-styles