Metadata-Version: 2.4
Name: tlnw-generate-image
Version: 0.6.0
Summary: Generate illustrations and images dynamically using OpenAI DALL-E and Google Imagen models.
Author-email: Tellers Network <admin@tlnw.uk>
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: python-dotenv>=0.19.0

# Tellers Network Image Generation Tool (`tlnw-generate-image`)

`tlnw-generate-image` is a standalone, publishable package that unifies AI image generation for stories and posts in the Tellers Network ecosystem. It supports OpenAI (DALL-E 2, DALL-E 3, `gpt-image-2`, and legacy `gpt-image-1.5`) as well as Google Gemini Imagen 4 models.

## Installation
```bash
pip install tlnw-generate-image
```

## Features
- **Extensible OOP Provider Architecture**: Clean separation of model providers (`DalleProvider`, `GptImageProvider`, `GoogleImagenProvider`) with registry-based dynamic routing.
- **Intelligent Size & Quality Preset Mapping**: Standardizes orientation presets (`landscape`, `portrait`, `square`) and qualities, automatically converting them to provider-native formats: aspect ratios (e.g. `"16:9"`) for Google Imagen, or concrete dimensions (e.g. `"1792x1024"`) for OpenAI.
- **Custom Dimension Resolution & Validation**: Automatically maps exact resolution values (e.g., `1920x1080` or `1536x1024.txt` in file names) to the closest supported native aspect ratios when routing to Imagen. For `gpt-image-2`, it validates custom resolution constraints locally (divisibility by 16, aspect ratios between 1:3 and 3:1, and a maximum resolution edge of 3840px with a minimum edge of 2160px).
- **Auto-resolution of Output Sizing**: Extracts target sizes from prompt filename trailing suffixes (e.g., `-1536x1024.txt`).
- **Prompt Composition**: Concatenates local directory `illustration-master-prompt.txt` automatically with individual scene prompts.
- **Automatic WebP Conversion**: Generates and optimizes WebP formats (`featured.webp` and `thumbnail.webp` with max-dimension constraints).
- **Standardized Output Filenames**: Output filenames are derived from the prompt file base: `<prefix>-prompt.txt` or `<prefix>-prompt-<size>.txt` become `<prefix>.<ext>`.
- **Optional WEBP Copy**: Use `--webp` to create an additional lossless `<prefix>.webp` copy alongside the main output.
- **Thumbnail Generation**: Use `--thumbnail` to create `<prefix>-thumbnail.webp` resized to max 768px with 75% quality.
 - **Dry Run**: Use `--dry-run` to run the full pipeline locally without calling remote image generation APIs. This creates small placeholder PNGs and performs conversions so you can validate outputs without API keys.
 - **Recursive File Patterns**: `--file-pattern` accepts glob patterns including `**` for recursive discovery (e.g. `--file-pattern "**/*-prompt-*.txt" root-folder`).
 

## Usage
Generate illustration for a story folder:
```bash
generate-image /path/to/story_folder --model dall-e-3 --webp --thumbnail
```

Process specific prompt files:
```bash
generate-image --file /path/to/prompt-1536x1024.txt --model imagen-4-ultra
```

Dry-run example (creates placeholders, no API calls):
```bash
generate-image /path/to/story_folder --dry-run --file-pattern "**/*-prompt-*.txt"
```
