Batch Renderer

A CLI tool for batch rendering AI image prompts from markdown files using the Poe API.

For AI image generation workflows: Write prompts in markdown, push to GitHub, and let Actions automatically render and commit the images. No local setup required.

Features

• 📝 Extract prompts from markdown files using configurable patterns
• 🎨 Batch render images using multiple AI models (GPT-Image-1, Nano-Banana, Flux, etc.)
• 📦 Nested or flat output structure organized by sections
• 🎯 Per-prompt metadata to override model, quality, aspect ratio, etc.
• 🔄 Automatic retries on errors with loud failures
• 📊 Rich CLI interface with progress bars and colored output
• ✅ Dry-run mode to preview extraction before rendering
• ⚙️ TAG LIBRARY for reusable prompt components (ADR-0006)
• 🤖 GitHub Actions integration for automated rendering
• 🖼️ LLM Gallery generation for multimodal review (ADR-0014)

Installation

For end users (recommended)

pip install batch-renderer

Version pinning recommended: Pin to a specific major.minor version to avoid breaking changes:

# Pin to 1.7.x series (recommended)
pip install "batch-renderer>=1.7,<1.8"

# Or pin to exact version
pip install batch-renderer==1.7.1

For GitHub Actions and CI, always pin — see the batch-renderer-action docs.

For development

# Clone the repository
cd batch-renderer

# Install dependencies
pipenv install

# Install the package in editable mode
pipenv install -e .

Quick Start

Recommended: GitHub Actions (CI-first)

The primary consumer workflow — write prompts locally, let GitHub Actions render automatically:

1. Use the template: Visit https://github.com/jlumbroso/batch-renderer-template and click "Use this template"
2. Add your Poe API key as a repository secret:
   • Settings → Secrets and variables → Actions
   • New repository secret: POE_API_KEY = your key from https://poe.com/api_key
3. Write prompts in prompts/ (markdown files with TAG LIBRARY — see template examples)
4. Push to GitHub:

   git add prompts/my-prompts.md
   git commit -m "feat: add new prompts"
   git push
   

   GitHub Actions automatically renders images and commits them to output/

View progress: Actions tab → "Generate Images" workflow

Alternative: Local CLI

For quick testing or one-off renders without CI:

# Install (if you haven't already)
pip install batch-renderer

# Set your API key
export POE_API_KEY=your_api_key_here

# Render images
batch-renderer prompts.md --no-confirm

# Preview extraction without rendering
batch-renderer prompts.md --dry-run

Note: For production workflows, use the GitHub Actions template above (handles secrets, retries, galleries, Git LFS).

For Contributors

Hacking on batch-renderer itself? See CONTRIBUTING.md for:

• Development setup (pipenv, .env, local testing)
• Release process and commit conventions
• Architecture overview and ADR guidelines

Markdown Format

Basic Format

## 1. Section Title

### Concept 1.1: Image Title
A detailed description of the image you want to generate...

### Concept 1.2: Another Image
Another prompt description...

With Metadata

Add metadata as bullet points after the heading to override settings:

### Concept 1.1: Custom Image
- model: GPT-Image-1
- aspect: 16:9
- quality: high
- retries: 5

A detailed prompt for the image...

Standard Metadata Keys

• model - Override the model for this prompt (e.g., GPT-Image-1, Nano-Banana)
• format - Override output format (e.g., png, jpg)
• skip - Set to true to skip this prompt
• retries - Number of retry attempts (default: 3)

Custom Metadata Keys

Any other keys are passed directly to the API via extra_body:

• aspect - Aspect ratio (1:1, 3:2, 2:3, 16:9, auto)
• quality - Image quality (low, medium, high)
• thinking_level - For thinking models (low, medium, high)
• thinking_budget - Thinking budget (extended)
• web_search - Enable web search (true / false)

CLI Usage

batch-renderer [OPTIONS] INPUT_FILE

Options

Examples

Basic usage:

batch-renderer prompts.md

Use a specific model:

batch-renderer prompts.md --model GPT-Image-1

Flat output structure:

batch-renderer prompts.md --flatten

Dry run to preview:

batch-renderer prompts.md --dry-run

Batch render without confirmation:

batch-renderer prompts.md --no-confirm

Strict metadata validation:

batch-renderer prompts.md --validation-mode strict

Output Structure

Nested (default)

out/
  1-artificial-lovers/
    concept-1-1-blade-runner-noir-romance.png
    concept-1-2-holographic-love.png
  2-fantastic-eight/
    concept-2-1-renaissance-group-portrait.png

Flattened (with --flatten)

out/
  concept-1-1-blade-runner-noir-romance.png
  concept-1-2-holographic-love.png
  concept-2-1-renaissance-group-portrait.png

Configuration Precedence

Settings are applied in this order (later overrides earlier):

1. Hard-coded defaults (Nano-Banana, png, etc.)
2. Environment variables (POE_DEFAULT_MODEL, POE_API_KEY)
3. Inline metadata (in markdown file)
4. CLI arguments (--model, --format, etc.)

Validation Modes

hybrid (default)

• Standard keys (model, format, skip, retries): Warns on malformed values
• Custom keys: Pass through without validation

strict

• Standard keys: Fails on malformed values
• Custom keys: Pass through without validation

lenient

• All keys: Warns only, never fails

Error Handling

• Automatic retries: Failed requests are retried 3 times by default (configurable per-prompt)
• Text responses: If model returns text instead of image, saves to .txt file with warning
• Partial failures: Continues rendering remaining prompts if one fails
• Summary report: Shows successful, text responses, and failed renders

Pattern Types

concept (default)

Extracts ### Concept X.Y: Title style prompts with section headers.

numbered

Extracts ### X.Y Title style prompts (no "Concept" keyword).

simple

Extracts all level-3 headings as prompts.

Environment Variables

For GitHub Actions: Set POE_API_KEY as a repository secret (see Quick Start above).

For local CLI:

# Set in your shell (recommended)
export POE_API_KEY=your_api_key_here
export POE_DEFAULT_MODEL=Nano-Banana  # optional

For contributors (development): Create a .env file — see CONTRIBUTING.md.

Contributing

Hacking on batch-renderer itself? See CONTRIBUTING.md for:

• Development setup: pipenv, .env, editable install
• Project structure: source layout, backend architecture
• Testing: pytest suite, test patterns
• Release process: semantic-release automation, commit format
• ADR conventions: Architecture Decision Records
• Pull request guidelines

The Quick Start above is for using batch-renderer in your projects. CONTRIBUTING.md is for developing the CLI tool itself.

Architecture Decisions

See docs/adr/ for detailed design decisions:

• ADR-0001: Core Architecture
• ADR-0002: Prompt Metadata Format

Troubleshooting

"POE_API_KEY not found"

Make sure you've created a .env file with your API key, or pass it via --api-key.

"No prompts found in file"

Check that your markdown file uses the correct pattern format. Use --dry-run to debug extraction.

Model returns text instead of image

This can happen if:

• The model doesn't support image generation
• The model name is incorrect
• The prompt is ambiguous

The tool will save the text response to a .txt file for inspection.

License

MIT

Author

Jérémie Lumbroso with Claude Sonnet 4.5 Additional contributions from Claude Opus 4.8 and Claude Fable 5