Metadata-Version: 2.4
Name: batch-renderer
Version: 1.8.0
Summary: CLI tool for batch rendering AI image prompts from markdown files
Author-email: Jérémie Lumbroso <lumbroso@seas.upenn.edu>
License: MIT
Project-URL: Homepage, https://github.com/jlumbroso/batch-renderer
Project-URL: Repository, https://github.com/jlumbroso/batch-renderer
Project-URL: Bug Tracker, https://github.com/jlumbroso/batch-renderer/issues
Keywords: ai,image-generation,batch,cli,poe,prompts,markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: structlog>=24.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# 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)

```bash
pip install batch-renderer
```

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

```bash
# 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](https://github.com/jlumbroso/batch-renderer-action) docs.

### For development

```bash
# 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**:
   ```bash
   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:

```bash
# 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](CONTRIBUTING.md) for:
- Development setup (pipenv, `.env`, local testing)
- Release process and commit conventions
- Architecture overview and ADR guidelines

## Markdown Format

### Basic Format

```markdown
## 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:

```markdown
### 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

```bash
batch-renderer [OPTIONS] INPUT_FILE
```

### Options

| Option | Description | Default |
|--------|-------------|---------|
| `--model`, `-m` | Model to use | `Nano-Banana` (or `POE_DEFAULT_MODEL` env) |
| `--output`, `-o` | Output directory | `out` |
| `--pattern`, `-p` | Extraction pattern (`concept`, `numbered`, `simple`) | `concept` |
| `--format`, `-f` | Output image format | `png` |
| `--flatten` | Flatten output (no subdirectories) | `false` |
| `--dry-run` | Extract and display without rendering | `false` |
| `--no-confirm` | Skip confirmation prompt | `false` |
| `--cache-images` | Cache images in `logs/image_cache` | `false` |
| `--validation-mode` | Metadata validation (`strict`, `lenient`, `hybrid`) | `hybrid` |
| `--api-key` | Poe API key (or `POE_API_KEY` env) | - |

### Examples

**Basic usage**:
```bash
batch-renderer prompts.md
```

**Use a specific model**:
```bash
batch-renderer prompts.md --model GPT-Image-1
```

**Flat output structure**:
```bash
batch-renderer prompts.md --flatten
```

**Dry run to preview**:
```bash
batch-renderer prompts.md --dry-run
```

**Batch render without confirmation**:
```bash
batch-renderer prompts.md --no-confirm
```

**Strict metadata validation**:
```bash
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**:

```bash
# 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.md).

## Contributing

**Hacking on batch-renderer itself?** See [CONTRIBUTING.md](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/](docs/adr/) for detailed design decisions:
- [ADR-0001: Core Architecture](docs/adr/0001-core-architecture.md)
- [ADR-0002: Prompt Metadata Format](docs/adr/0002-prompt-metadata-format.md)

## 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
