image-generator

name	image-generator
description	Generates publication-quality academic illustrations using the PaperBanana package (llmsresearch/paperbanana) — a multi-agent pipeline (Retriever → Planner → Stylist → Visualizer ↔ Critic) with OpenAI as the provider.

Image Generator (PaperBanana Pipeline)

When to use

• When Illustrator agent needs to generate academic diagrams
• When regenerating specific diagrams after Critic feedback

CRITICAL: Choosing the right mode

Full PaperBanana pipeline (DEFAULT — all illustration types)

.venv/bin/python .github/skills/image-generator/scripts/paperbanana_generate.py "[description]" "illustrations/diagram_N.png" --context "[section text, 200-500 words]" --critic-rounds 2

The wrapper calls the real paperbanana package (PaperBananaPipeline.generate()) with OpenAI provider:

• Phase 1 (Linear Planning): Retriever → Planner → Stylist
• Phase 2 (Iterative Refinement): Visualizer ↔ Critic (default 2 rounds)

VLM agent (Planner/Stylist/Critic) uses gpt-5.2, image generation (Visualizer) uses gpt-image-1.5.

Pipeline takes 3–5 min per illustration (5–7 API calls). Always use run_in_terminal with timeout: 0 (no timeout limit).

Direct generation (via --direct flag)

.venv/bin/python .github/skills/image-generator/scripts/paperbanana_generate.py "[description]" "illustrations/diagram_N.png" --direct

Use --direct when: explicitly requested via flag or prompt. Single API call, ~40 sec.

Prompt guidelines for --direct:

• Keep prompts SHORT (2-4 sentences max)
• Focus on visual structure, not exact text labels
• Describe shapes, colors, spatial layout
• Do NOT list exact text for every label
• Do NOT write multi-paragraph layout specs — this causes ASCII-art output

Configuration

The script reads from .env file in project root:

Variable	Default	Description
OPENAI_API_KEY	(required)	OpenAI API key for all agents
TEXT_MODEL	gpt-5.2	VLM model for Planner/Stylist/Critic
IMAGE_MODEL	gpt-image-1.5	Image generation model
MAX_CRITIC_ROUNDS	2	Visualizer-Critic refinement iterations

Dependencies

pip install "paperbanana[openai]" python-dotenv

Output

• Generates one PNG at the specified path (copied from PaperBanana's outputs/ dir)
• All intermediate iterations and metadata saved by PaperBanana in outputs/