batch-renderer 1.0.0__tar.gz

batch_renderer-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jérémie Lumbroso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

batch_renderer-1.0.0/MANIFEST.in

@@ -0,0 +1,26 @@
+# MANIFEST.in — controls what goes into the source distribution (sdist)
+# The wheel is already clean via [tool.setuptools.packages.find] where = ["src"]
+
+# Include core files
+include README.md
+include LICENSE
+include pyproject.toml
+
+# Exclude internal methodology and development artifacts
+# These should never appear on PyPI
+recursive-exclude docs *
+exclude CLAUDE.md
+recursive-exclude .claude *
+recursive-exclude tests/fixtures *
+recursive-exclude _prompts *
+recursive-exclude _output *
+recursive-exclude logs *
+exclude temp
+recursive-exclude temp *
+
+# Exclude development config files
+exclude Pipfile
+exclude Pipfile.lock
+exclude setup.py
+exclude .env
+exclude .env.*

batch_renderer-1.0.0/PKG-INFO

@@ -0,0 +1,318 @@
+Metadata-Version: 2.4
+Name: batch-renderer
+Version: 1.0.0
+Summary: CLI tool for batch rendering AI image prompts from markdown files
+Author: Jérémie Lumbroso
+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: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# 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

batch_renderer-1.0.0/README.md

@@ -0,0 +1,279 @@
+# 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