Paperbanana

PaperBanana - Academic Illustration Generator

Multi-agent pipeline (Retriever → Planner → Stylist → Visualizer → Critic) for publication-quality academic diagrams, statistical plots, and presentation slides.

API key: Set provider keys in PaperBanana project's .env file. Timeout: 300000 (5 min) for all generation commands.

Commands

All commands run from project root: cd <paperbanana_dir> && python -m paperbanana.cli <cmd>

Command Selection Decision Tree

Route user requests to the right subcommand before looking up parameters:

Ambiguous input: If user provides just a description with no subcommand signal, default to generate (see Argument Parsing table for details).

Out-of-scope: Pure code generation (matplotlib/seaborn script) is NOT paperbanana's job — those go to matplotlib / scientific-visualization skills. Paperbanana is for AI-driven image generation + critique loops.

Note (upstream sync pending): Upstream paperbanana CLI also adds subcommands (plot-batch #123, sweep #118) not yet reflected in this table. See the llmsresearch/paperbanana CHANGELOG for the authoritative CLI surface.

generate — Methodology Diagrams

python -m paperbanana.cli generate --input '<file>' --caption '<caption>' --optimize --verbose

When user provides inline text (no file): write to temp file, use as --input.

Venue styles: --venue neurips applies NeurIPS-specific methodology and plot style guides from data/guidelines/. Each venue has distinct color palettes, layout conventions, and typography expectations.

PDF input: --input paper.pdf --pages 3-5 extracts text from the specified pages as source context.

Exemplar advanced flags: --exemplar-retrieval enables retrieval; see generate --help for additional config flags (--exemplar-endpoint, --exemplar-mode, --exemplar-top-k, --exemplar-timeout, --exemplar-retries).

plot — Statistical Plots

python -m paperbanana.cli plot --data '<data.csv>' --intent '<intent>' --optimize --verbose

slide — Presentation Slides

python -m paperbanana.cli slide --input '<prompt.md>' --resolution 4k

slide-batch — Batch Slide Generation

python -m paperbanana.cli slide-batch --prompts-dir '<dir>' --resolution 4k

Wave-Parallel Batch Generation (speed default for ≥2 slides)

With a concurrency-enabled paperbanana build, batch generation runs slides in parallel with identical per-slide quality — every slide keeps its full Critic loop, its own pipeline instance, and its own run directory:

python -m paperbanana.cli slide-batch --prompts-dir '<dir>' --output-dir '<out>' --resolution 4k --concurrent 3

Measured (2026-08-03): 6 slides at --concurrent 3 in 309s vs 768s serial estimate (0.40x, ~2.5x speedup). Built-in resilience: 5s start-up stagger (same-second bursts to the image API fail or hang server-side long before per-minute quotas are near), in-batch delayed retry for transient 503s (recovery overlaps with other slides), and an end-of-batch serial retry pass for stragglers. Delivery quality is protected twice over: the final image per slide is the highest-critic-score iteration (not simply the last), and critic_score_threshold=9.0 skips provably-done rounds early — calibrated on 69 historical runs with zero false early-stops.

If the installed paperbanana lacks --concurrent, fall back to serial slide-batch — do NOT spawn more than 3 parallel slide processes yourself, as there is no cross-process rate-limit coordination.

Style Presets (23 available)

Use --style <name> with slide or slide-batch. Use --list-styles to see all.

evaluate — Comparative Evaluation

python -m paperbanana.cli evaluate --generated '<gen.png>' --reference '<ref.png>' \
  --context '<text_file>' --caption '<caption>'

data — Manage Reference Datasets

python -m paperbanana.cli data download   # Download expanded reference set (~257MB)
python -m paperbanana.cli data info       # Show cached dataset info
python -m paperbanana.cli data clear      # Remove cached dataset

ablate-retrieval — Retrieval Ablation (Advanced)

Research utility for running baseline vs retrieval ablation (k sweep). See ablate-retrieval --help for details.

setup — Interactive Setup Wizard

python -m paperbanana.cli setup

Guides through API key configuration and provider selection. No flags needed.

Provider Selection

Use --vlm-provider and --image-provider flags to select providers per command.

⚠️ Provider naming asymmetry (common trap): VLM providers use short names (gemini / openai / anthropic / bedrock / openrouter), but image providers require the _imagen suffix: google_imagen (not gemini), openai_imagen (not openai), bedrock_imagen, openrouter_imagen. The error ValueError: Unknown image provider: openai. Available: google_imagen, openrouter_imagen, openai_imagen, bedrock_imagen means you hit this. Every --image-provider example in this document uses the X_imagen form.

Auto-routing decision table

When the user doesn't specify an image model, pick --image-provider by the first matching rule (top priority wins). Calibrated from a controlled 16-prompt two-provider comparison (2026-04) plus slide-deck production use:

Never second-guess an explicit user choice. If the user says which provider to use, use it — even when the auto-rules would pick differently.

Argument Parsing

Error Handling

Two types of API failure can occur during generation. Handle them differently:

Type 1: Image Generation API Failure (Visualizer)

The image provider (Gemini Imagen, DALL-E, Nova Canvas) fails to return an image.

Fallback chain: google_imagen → openai → bedrock → openrouter. Use the next provider in chain that has a valid API key in .env. If all fail, stop and report the error.

Type 2: VLM Critic API Failure

The VLM provider (Gemini Flash, Claude, GPT-4o) fails during quality evaluation.

VLM fallback chain: gemini → anthropic → openai → openrouter.

Critical rule: A Critic failure must NEVER silently approve an image. If Critic cannot evaluate, the output status must be UNREVIEWED, not APPROVED. Report this clearly to the user.

Recovery with --continue

Use --continue to resume after any failure:

The run directory preserves all intermediate state (plans, images, critic feedback). --continue picks up from the last successful step.

Batch Mode (slide-batch) Resilience

When generating multiple slides, a single slide failure should NOT kill the batch:

1. Log the failure for the specific slide
2. Continue generating remaining slides
3. At the end, report which slides succeeded and which failed
4. User can re-run with --continue to retry only failed slides

🔴 User Confirmation Checkpoints

Paperbanana is CLI-first, but three user-facing actions are expensive or irreversible. 🛑 STOP and ask for explicit confirmation before running any row below — do not proceed on assumed consent.

✅ No checkpoint needed: normal generate / plot / slide (no --auto, within iteration cap 3) — these are short, cheap, and the Critic loop is self-bounded. Run them directly.

⛔ Anti-Patterns — Red-Line Blacklist

Hard "do NOT" rules. Each maps to a failure mode already encoded above — this section consolidates them into one scannable list.

After Generation

1. Parse output to find image path
2. Use Read tool to display the generated image
3. Report Run ID, iteration count, and Critic feedback
4. If any outputs are marked UNREVIEWED, warn the user explicitly
5. If user expresses dissatisfaction OR status is UNREVIEWED, proactively suggest: python -m paperbanana.cli <cmd> --continue --feedback "<specific fix>" — preserves run state, avoids full regeneration