Metadata-Version: 2.4
Name: batch-renderer
Version: 1.2.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.

## Features

- 📝 **Extract prompts from markdown** files using configurable patterns
- 🎨 **Batch render images** using multiple AI models (GPT-Image-1, Nano-Banana, etc.)
- 📦 **Nested output structure** organized by sections
- 🎯 **Per-prompt metadata** to override model, quality, aspect ratio, etc.
- 🔄 **Automatic retries** on errors
- 📊 **Rich CLI interface** with progress bars and colored output
- ✅ **Dry-run mode** to preview extraction before rendering
- ⚙️ **Flexible configuration** via CLI, environment variables, or inline metadata

## Installation

```bash
# Clone the repository
cd batch-renderer

# Install dependencies
pipenv install

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

## Quick Start

1. **Set up your Poe API key**:
   ```bash
   echo "POE_API_KEY=your_api_key_here" >> .env
   ```

2. **Create a markdown file with prompts** (see [Format](#markdown-format) below)

3. **Dry run to preview**:
   ```bash
   pipenv run batch-renderer docs/SAMPLE-CONCEPTS.md --dry-run
   ```

4. **Render images**:
   ```bash
   pipenv run batch-renderer docs/SAMPLE-CONCEPTS.md
   ```

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

Create a `.env` file in the project root:

```env
# Required
POE_API_KEY=your_api_key_here

# Optional
POE_DEFAULT_MODEL=Nano-Banana
```

## Development

### Project Structure

```
batch-renderer/
├── src/batch_renderer/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py           # CLI interface
│   ├── config.py        # Configuration management
│   ├── patterns.py      # Prompt extraction patterns
│   └── renderer.py      # Image rendering
├── docs/
│   ├── adr/            # Architecture Decision Records
│   └── SAMPLE-CONCEPTS.md
├── setup.py
├── Pipfile
└── README.md
```

### Running Tests

```bash
# Dry run with test file
pipenv run batch-renderer test_prompts.md --dry-run

# Dry run with full sample
pipenv run batch-renderer docs/SAMPLE-CONCEPTS.md --dry-run
```

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