tlnw-generate-image 0.2.0__tar.gz

tlnw_generate_image-0.2.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: tlnw-generate-image
+Version: 0.2.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, 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**: 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, while passing OpenAI dimensions as-is.
+- **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).
+- **Automated Jekyll/Hugo Updating**: Automatically updates the article frontmatter's `images` block.
+
+## Usage
+Generate illustration for a story folder:
+```bash
+generate-image /path/to/story_folder --model dall-e-3
+```
+
+Process specific prompt files:
+```bash
+generate-image --file /path/to/prompt-1536x1024.txt --model imagen-4-ultra
+```

tlnw_generate_image-0.2.0/README.md

@@ -0,0 +1,28 @@
+# 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, 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**: 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, while passing OpenAI dimensions as-is.
+- **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).
+- **Automated Jekyll/Hugo Updating**: Automatically updates the article frontmatter's `images` block.
+
+## Usage
+Generate illustration for a story folder:
+```bash
+generate-image /path/to/story_folder --model dall-e-3
+```
+
+Process specific prompt files:
+```bash
+generate-image --file /path/to/prompt-1536x1024.txt --model imagen-4-ultra
+```

tlnw_generate_image-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tlnw-generate-image"
+version = "0.2.0"
+description = "Generate illustrations and images dynamically using OpenAI DALL-E and Google Imagen models."
+readme = "README.md"
+authors = [
+    { name = "Tellers Network", email = "admin@tlnw.uk" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "openai>=1.0.0",
+    "requests>=2.25.0",
+    "pillow>=9.0.0",
+    "python-dotenv>=0.19.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.scripts]
+generate-image = "tlnw_generate_image.cli:main"
+
+[tool.setuptools]
+packages = ["tlnw_generate_image"]

tlnw_generate_image-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tlnw_generate_image-0.2.0/tests/test_generate_image.py

@@ -0,0 +1,176 @@
+import os
+from pathlib import Path
+from unittest import mock
+
+try:
+    import pytest
+except ImportError:
+    class MockPytest:
+        class RaisesContext:
+            def __init__(self, expected_exception):
+                self.expected_exception = expected_exception
+                self.value = None
+            def __enter__(self):
+                return self
+            def __exit__(self, exc_type, exc_val, exc_tb):
+                if exc_type is None:
+                    raise AssertionError(f"Did not raise {self.expected_exception}")
+                if issubclass(exc_type, self.expected_exception):
+                    self.value = exc_val
+                    return True
+                return False
+        def raises(self, expected_exception):
+            return self.RaisesContext(expected_exception)
+    pytest = MockPytest()
+
+from tlnw_generate_image.core import (
+    get_default_quality,
+    normalize_quality_for_model,
+    _resolve_size_for_orientation,
+    combine_master_prompt,
+    update_index_frontmatter_images,
+    update_figure_shortcodes_in_index,
+    load_master_prompt,
+)
+
+def test_get_default_quality():
+    assert get_default_quality("imagen-4") == "standard"
+    assert get_default_quality("gpt-image-1.5") == "medium"
+    assert get_default_quality("dall-e-3") == "standard"
+    assert get_default_quality("unknown-model") == "standard"
+
+def test_normalize_quality_for_model():
+    # gpt-image mapping
+    assert normalize_quality_for_model("gpt-image-1.5", "standard") == "medium"
+    assert normalize_quality_for_model("gpt-image-1.5", "hd") == "high"
+    assert normalize_quality_for_model("gpt-image-1.5", "low") == "low"
+    
+    # dall-e-3 mapping
+    assert normalize_quality_for_model("dall-e-3", "hd") == "hd"
+    assert normalize_quality_for_model("dall-e-3", "high") == "hd"
+    assert normalize_quality_for_model("dall-e-3", "medium") == "standard"
+    
+    # imagen mapping
+    assert normalize_quality_for_model("imagen-4.0", "medium") == "standard"
+    assert normalize_quality_for_model("imagen-4.0", "hd") == "high"
+
+def test_resolve_size_for_orientation():
+    assert _resolve_size_for_orientation("gpt-image-1.5", "square") == "1024x1024"
+    assert _resolve_size_for_orientation("dall-e-3", "landscape") == "1792x1024"
+    assert _resolve_size_for_orientation("dall-e-3", "portrait") == "1024x1792"
+    assert _resolve_size_for_orientation("gpt-image-1.5", "landscape") == "1536x1024"
+    assert _resolve_size_for_orientation("gpt-image-1.5", "portrait") == "1024x1536"
+    
+    with pytest.raises(ValueError):
+        _resolve_size_for_orientation("dall-e-2", "landscape")
+
+def test_combine_master_prompt():
+    assert combine_master_prompt("", "Specific scene") == "Specific scene"
+    assert combine_master_prompt("Master Style Note", "Scene details") == "Master Style Note\n\nScene details"
+
+def test_load_master_prompt(tmp_path=None):
+    if tmp_path is None:
+        import tempfile
+        with tempfile.TemporaryDirectory() as tmpdir:
+            _test_load_master_prompt_logic(Path(tmpdir))
+    else:
+        _test_load_master_prompt_logic(tmp_path)
+
+def _test_load_master_prompt_logic(tmp_path):
+    # Missing master prompt
+    assert load_master_prompt(tmp_path) == ""
+    
+    # Existing master prompt
+    master_file = tmp_path / "illustration-master-prompt.txt"
+    master_file.write_text("Paint in impressionism style.", encoding="utf-8")
+    assert load_master_prompt(tmp_path) == "Paint in impressionism style."
+
+def test_update_index_frontmatter_images(tmp_path=None):
+    with mock.patch('tlnw_generate_image.core.update_images_frontmatter_with_fmu', return_value=False):
+        if tmp_path is None:
+            import tempfile
+            with tempfile.TemporaryDirectory() as tmpdir:
+                _test_update_index_frontmatter_images_logic(Path(tmpdir))
+        else:
+            _test_update_index_frontmatter_images_logic(tmp_path)
+
+def _test_update_index_frontmatter_images_logic(tmp_path):
+    index_md = tmp_path / "index.md"
+    
+    # Standard Jekyll/Hugo markdown frontmatter
+    initial_content = """---
+title: My Story
+summary: A nice summary
+image: some-image.jpg
+---
+This is some content.
+"""
+    index_md.write_text(initial_content, encoding="utf-8")
+    
+    # Update and check
+    res = update_index_frontmatter_images(index_md, "thumbnail.webp")
+    assert res is not None
+    assert res.exists()
+    
+    updated_content = res.read_text(encoding="utf-8")
+    assert "images:" in updated_content
+    assert "- thumbnail.webp" in updated_content
+    
+    # Re-updating with the same image name should return None (no change) or keep it idempotent
+    res2 = update_index_frontmatter_images(index_md, "thumbnail.webp")
+    assert res2 is None  # Matches the core logic return None when nothing needs update
+
+def test_update_figure_shortcodes_in_index(tmp_path=None):
+    if tmp_path is None:
+        import tempfile
+        with tempfile.TemporaryDirectory() as tmpdir:
+            _test_update_figure_shortcodes_in_index_logic(Path(tmpdir))
+    else:
+        _test_update_figure_shortcodes_in_index_logic(tmp_path)
+
+def _test_update_figure_shortcodes_in_index_logic(tmp_path):
+    index_md = tmp_path / "index.md"
+    content = """---
+title: Post
+---
+{{< figure src="illustration.png" title="Story" >}}
+"""
+    index_md.write_text(content, encoding="utf-8")
+    
+    updated = update_figure_shortcodes_in_index(index_md)
+    assert updated is True
+    
+    new_content = index_md.read_text(encoding="utf-8")
+    assert '{{< figure src="illustration.webp"' in new_content
+
+def test_provider_registry():
+    from tlnw_generate_image.providers import get_provider_for_model
+    from tlnw_generate_image.providers.dalle import DalleProvider
+    from tlnw_generate_image.providers.gpt_image import GptImageProvider
+    from tlnw_generate_image.providers.google_imagen import GoogleImagenProvider
+    
+    assert isinstance(get_provider_for_model("dall-e-3"), DalleProvider)
+    assert isinstance(get_provider_for_model("dall-e-2"), DalleProvider)
+    assert isinstance(get_provider_for_model("gpt-image-1.5"), GptImageProvider)
+    assert isinstance(get_provider_for_model("imagen-4-ultra"), GoogleImagenProvider)
+    # Default fallback
+    assert isinstance(get_provider_for_model("custom-unsupported-model"), DalleProvider)
+
+def test_google_imagen_size_mapping():
+    from tlnw_generate_image.providers import get_provider_for_model
+    provider = get_provider_for_model("imagen-4")
+    
+    # Preset orientations
+    assert provider.resolve_size("imagen-4", "square") == "1:1"
+    assert provider.resolve_size("imagen-4", "landscape") == "16:9"
+    assert provider.resolve_size("imagen-4", "portrait") == "9:16"
+    
+    # Exact aspect ratio overrides
+    assert provider.resolve_size("imagen-4", "square", size="4:3") == "4:3"
+    assert provider.resolve_size("imagen-4", "square", size="16:9") == "16:9"
+    
+    # Resolution parsing to closest aspect ratio
+    assert provider.resolve_size("imagen-4", "square", size="1024x1024") == "1:1"
+    assert provider.resolve_size("imagen-4", "square", size="1536x1024") == "16:9"
+    assert provider.resolve_size("imagen-4", "square", size="1920x1080") == "16:9"
+    assert provider.resolve_size("imagen-4", "square", size="1080x1920") == "9:16"

tlnw_generate_image-0.2.0/tlnw_generate_image/__init__.py

@@ -0,0 +1,2 @@
+# Tellers Network Generate Image Tool
+__version__ = "0.2.0"

tlnw_generate_image-0.2.0/tlnw_generate_image/cli.py

@@ -0,0 +1,127 @@
+import argparse
+import os
+import sys
+import logging
+from pathlib import Path
+from dotenv import load_dotenv
+
+from .core import process_story_folder, get_default_quality, normalize_quality_for_model
+from .providers import get_provider_for_model
+
+# Setup local logger
+logger = logging.getLogger("tlnw-generate-image")
+
+def main():
+    # Load env variables (first local .env, then system env)
+    load_dotenv()
+    
+    parser = argparse.ArgumentParser(description="Generate illustrations for story folders and specific scene prompt files.")
+    
+    # Core positional / file targets
+    parser.add_argument("story_folders", nargs="*", help="Story folder paths to process.")
+    parser.add_argument("--file", action="append", help="Specific prompt file(s) to process directly.")
+    
+    # Basename and pattern configs
+    parser.add_argument("--basename", "-b", help="Custom basename for prompt files and output images (e.g., will look for <basename>-prompt.txt).")
+    parser.add_argument("--file-pattern", "-p", help="File pattern to match prompt files in a folder (e.g. 'illustration-prompt-cover-*.txt').")
+    
+    # Model configuration
+    parser.add_argument("--model", "-m", default="gpt-image-1.5", 
+                        help="Image generation model to use. Defaults to 'gpt-image-1.5'. Supports dall-e-3, imagen-4-ultra, etc.")
+    
+    # Quality & Sizing options
+    parser.add_argument("--quality", "-q", choices=["low", "medium", "high", "standard", "hd", "auto"],
+                        help="Image quality. Defaults to 'medium' for GPT models and 'standard' for Gemini Imagen models.")
+    parser.add_argument("--size", help="Explicit image size (e.g. 1536x1024) to override model/orientation defaults.")
+    
+    # Orientation options (mutually exclusive)
+    orientation_group = parser.add_mutually_exclusive_group()
+    orientation_group.add_argument("--landscape", action="store_true", help="Generate landscape format (1536x1024 for GPT-image, 1792x1024 for DALL-E 3).")
+    orientation_group.add_argument("--portrait", action="store_true", help="Generate portrait format (1024x1536 for GPT-image, 1024x1792 for DALL-E 3).")
+    
+    # Reference and Output adjustments
+    parser.add_argument("--reference", dest="reference_images", action="append", default=[],
+                        help="Reference image path(s) to influence image edits (DALL-E only).")
+    parser.add_argument("--output-prefix", dest="output_prefix", default=None,
+                        help="Prefix to prepend to generated output filenames (e.g. 'podcast').")
+    
+    # Format and Execution behavior options
+    parser.add_argument("--format", choices=["PNG", "WEBP", "JPEG", "JPG"], default="PNG", help="Image output format. Default is PNG.")
+    parser.add_argument("--skip-update", "-s", action="store_true", help="Skip updating frontmatter inside the Jekyll index.md file.")
+    parser.add_argument("--force", "-f", action="store_true", help="Force regeneration of illustrations even if they already exist.")
+    
+    # Verbose debugging
+    parser.add_argument("--debug", action="store_true", help="Enable verbose debug-level logging.")
+
+    args = parser.parse_args()
+
+    # Configure Logging based on Debug option
+    log_level = logging.DEBUG if args.debug else logging.INFO
+    logging.basicConfig(level=log_level, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s")
+    logger.setLevel(log_level)
+    
+    # Determine orientation string
+    if args.landscape:
+        orientation = "landscape"
+    elif args.portrait:
+        orientation = "portrait"
+    else:
+        orientation = "square"
+
+    # Default quality resolving
+    quality = args.quality if args.quality else get_default_quality(args.model)
+
+    # API key environment verification based on model family
+    try:
+        provider = get_provider_for_model(args.model)
+        provider.validate_env(args.model)
+    except ValueError as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+    # Execute file-based targets if specified
+    if args.file:
+        logger.info("Processing %d specific file(s)...", len(args.file))
+        for item in args.file:
+            process_story_folder(
+                item,
+                model=args.model,
+                quality=quality,
+                orientation=orientation,
+                reference_images=args.reference_images,
+                output_prefix=args.output_prefix,
+                size=args.size,
+                skip_update=args.skip_update,
+                force=args.force,
+                file_pattern=args.file_pattern,
+                basename=args.basename
+            )
+
+    # Execute folder-based targets if specified
+    if args.story_folders:
+        logger.info("Processing %d story folder(s)...", len(args.story_folders))
+        for story_folder in args.story_folders:
+            logger.info("Processing: %s", story_folder)
+            process_story_folder(
+                story_folder,
+                model=args.model,
+                quality=quality,
+                orientation=orientation,
+                reference_images=args.reference_images,
+                output_prefix=args.output_prefix,
+                size=args.size,
+                skip_update=args.skip_update,
+                force=args.force,
+                file_pattern=args.file_pattern,
+                basename=args.basename
+            )
+            
+    if not args.file and not args.story_folders:
+        print("Error: No files (--file) or story folders specified.")
+        parser.print_help()
+        sys.exit(1)
+
+    print("\nAll tasks processed!")
+
+if __name__ == "__main__":
+    main()

tlnw_generate_image-0.2.0/tlnw_generate_image/core.py

@@ -0,0 +1,401 @@
+import logging
+import os
+import sys
+import re
+import contextlib
+import base64
+import subprocess
+from pathlib import Path
+import requests
+from PIL import Image
+
+from .providers import get_provider_for_model
+
+logger = logging.getLogger("tlnw-generate-image")
+
+FEATURED_WEBP_FILENAME = "featured.webp"
+THUMBNAIL_WEBP_FILENAME = "thumbnail.webp"
+THUMBNAIL_MAX_DIMENSION = 768
+THUMBNAIL_WEBP_QUALITY = 75
+
+def get_default_quality(model):
+    """Return default quality by model family."""
+    provider = get_provider_for_model(model)
+    return provider.get_default_quality(model)
+
+
+def normalize_quality_for_model(model, quality):
+    """Normalize cross-model quality values to model-specific acceptable values."""
+    provider = get_provider_for_model(model)
+    return provider.normalize_quality(model, quality)
+
+
+def _resolve_size_for_orientation(model, orientation):
+    """Map a requested orientation to an OpenAI-compatible image size."""
+    provider = get_provider_for_model(model)
+    return provider.resolve_size(model, orientation)
+
+
+def load_master_prompt(story_folder: Path) -> str:
+    """Load the shared illustration master prompt if the story provides one."""
+    master_prompt_path = story_folder / "illustration-master-prompt.txt"
+    if not master_prompt_path.exists():
+        return ""
+
+    try:
+        return master_prompt_path.read_text(encoding="utf-8").strip()
+    except Exception as e:
+        logger.warning("Failed to load master prompt from %s: %s", master_prompt_path, e)
+        return ""
+
+
+def combine_master_prompt(master_prompt_text: str, prompt_text: str) -> str:
+    """Prepend the shared master prompt to an individual scene prompt."""
+    if not master_prompt_text:
+        return prompt_text
+
+    return f"{master_prompt_text.rstrip()}\n\n{prompt_text.lstrip()}"
+
+
+def generate_image(prompt, out_path, model="gpt-image-1.5", size="1024x1024", quality="medium", reference_images: list[str] | None = None):
+    """Route to correct image generation provider based on the model."""
+    provider = get_provider_for_model(model)
+    return provider.generate(
+        prompt,
+        out_path,
+        model=model,
+        size=size,
+        quality=quality,
+        reference_images=reference_images
+    )
+
+
+def convert_png_to_webp(
+    png_path: Path,
+    webp_path: Path | None = None,
+    *,
+    max_dimension: int | None = None,
+    lossless: bool = True,
+    quality: int | None = None,
+) -> Path:
+    target_path = webp_path or png_path.with_suffix(".webp")
+    logger.debug(
+        "Converting PNG to WebP: source=%s target=%s max_dimension=%s lossless=%s quality=%s",
+        png_path, target_path, max_dimension, lossless, quality,
+    )
+    with Image.open(png_path) as img:
+        if img.mode not in ("RGB", "RGBA"):
+            img = img.convert("RGBA")
+        else:
+            img = img.copy()
+
+        if max_dimension is not None:
+            img.thumbnail((max_dimension, max_dimension), Image.Resampling.LANCZOS)
+
+        save_kwargs = {"format": "WEBP"}
+        if lossless:
+            save_kwargs["lossless"] = True
+        else:
+            save_kwargs["lossless"] = False
+            save_kwargs["method"] = 6
+            if quality is not None:
+                save_kwargs["quality"] = quality
+
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        img.save(target_path, **save_kwargs)
+    return target_path
+
+
+def update_images_frontmatter_with_fmu(index_path: Path, image_name: str = "illustration.webp") -> bool:
+    """Update the images frontmatter field via the 'fmu' external command."""
+    command = [
+        "fmu",
+        "update",
+        str(index_path),
+        "--name",
+        "images",
+        "--compute",
+        f"=flat_list({image_name})",
+    ]
+
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            env={**os.environ, "PYTHONIOENCODING": "utf-8"},
+        )
+        if result.returncode == 0:
+            return True
+        logger.warning("fmu command failed with return code %d. Stderr: %s", result.returncode, result.stderr)
+    except FileNotFoundError:
+        logger.debug("fmu command not found on PATH. Standard YAML parsing will be used.")
+    except Exception as e:
+        logger.warning("Error running fmu: %s", e)
+        
+    return False
+
+
+def update_index_frontmatter_images(index_path: Path, image_name: str = THUMBNAIL_WEBP_FILENAME) -> Path | None:
+    """Update standard frontmatter images block in index.md using robust inline parsing."""
+    if not index_path.exists():
+        return None
+
+    # First attempt updating using 'fmu' command if possible
+    if update_images_frontmatter_with_fmu(index_path, image_name):
+        logger.debug("Successfully updated frontmatter via fmu.")
+        # Re-read file to return updated path
+        return index_path
+
+    try:
+        text = index_path.read_text(encoding="utf-8")
+    except Exception as e:
+        logger.warning("Failed to read %s: %s", index_path, e)
+        return None
+
+    lines = text.splitlines()
+    logger.debug("Updating frontmatter images in %s to include %s", index_path, image_name)
+
+    if not lines or lines[0].strip() != "---":
+        logger.warning("Skipping frontmatter update for %s: missing YAML frontmatter", index_path)
+        return None
+
+    try:
+        frontmatter_end = lines.index("---", 1)
+    except ValueError:
+        logger.warning("Skipping frontmatter update for %s: unterminated YAML frontmatter", index_path)
+        return None
+
+    frontmatter_lines = lines[1:frontmatter_end]
+    thumbnail_entry = f"- {image_name}"
+
+    images_index = next((i for i, line in enumerate(frontmatter_lines) if line.strip() == "images:"), None)
+    if images_index is None:
+        insert_after = len(frontmatter_lines)
+        for key in ("image:", "summary:", "url:"):
+            key_index = next((i for i, line in enumerate(frontmatter_lines) if line.strip().startswith(key)), None)
+            if key_index is not None:
+                insert_after = key_index + 1
+                break
+        frontmatter_lines[insert_after:insert_after] = ["images:", thumbnail_entry]
+    else:
+        block_end = images_index + 1
+        while block_end < len(frontmatter_lines) and frontmatter_lines[block_end].lstrip().startswith("-"):
+            if frontmatter_lines[block_end].strip() == thumbnail_entry:
+                # Value already exists, nothing to update
+                return None
+            block_end += 1
+        frontmatter_lines.insert(block_end, thumbnail_entry)
+
+    updated_text = "\n".join([lines[0], *frontmatter_lines, lines[frontmatter_end], *lines[frontmatter_end + 1:]])
+    if text.endswith("\n"):
+        updated_text += "\n"
+
+    try:
+        index_path.write_text(updated_text, encoding="utf-8")
+        return index_path
+    except Exception as e:
+        logger.warning("Failed to write updated frontmatter to %s: %s", index_path, e)
+        return None
+
+
+def update_figure_shortcodes_in_index(index_path: Path) -> bool:
+    """Replace any standard markdown figure shortcodes referencing .png with .webp."""
+    if not index_path.exists():
+        return False
+        
+    try:
+        content = index_path.read_text(encoding="utf-8")
+        if '{{< figure src="illustration.png"' in content:
+            updated_content = content.replace('{{< figure src="illustration.png"', '{{< figure src="illustration.webp"')
+            index_path.write_text(updated_content, encoding="utf-8")
+            logger.info("Updated figure shortcode references in: %s", index_path)
+            return True
+    except Exception as e:
+        logger.warning("Failed to update figure shortcodes in %s: %s", index_path, e)
+        
+    return False
+
+
+def generate_image_from_prompt(
+    prompt_path: Path, 
+    out_path: Path, 
+    model="dall-e-3", 
+    quality="medium", 
+    orientation="square", 
+    reference_images: list[str] | None = None, 
+    size: str | None = None
+) -> Path:
+    """Generate image based on prompt read from the filesystem, resolving size automatically."""
+    try:
+        prompt = prompt_path.read_text(encoding="utf-8").strip()
+    except Exception as e:
+        logger.error("Failed to read prompt file %s: %s", prompt_path, e)
+        sys.exit(1)
+        
+    logger.debug("Loaded prompt file %s (%d characters)", prompt_path, len(prompt))
+    
+    # Try to parse the size from the prompt file's name if not specified
+    if not size:
+        # Extract trailing suffix matching -<width>x<height>
+        size_match = re.search(r'-(\d+)x(\d+)(?:\.txt)?$', prompt_path.name)
+        if size_match:
+            size = f"{size_match.group(1)}x{size_match.group(2)}"
+            logger.debug("Parsed size %s from prompt filename %s", size, prompt_path.name)
+
+    if not size:
+        try:
+            size = _resolve_size_for_orientation(model, orientation)
+        except ValueError as exc:
+            print(f"ERROR: {exc}")
+            sys.exit(1)
+            
+    print(f"Generating image for: {out_path} using model: {model}, quality: {quality}, orientation: {orientation}, size: {size}")
+    
+    # Prepend master prompt if present in the folder
+    master_text = load_master_prompt(prompt_path.parent)
+    prompt = combine_master_prompt(master_text, prompt)
+    
+    result_path = generate_image(
+        prompt, 
+        str(out_path), 
+        model=model, 
+        size=size, 
+        quality=quality, 
+        reference_images=reference_images
+    )
+    return Path(result_path)
+
+
+def process_story_folder(
+    source: str,
+    model="dall-e-3",
+    quality="medium",
+    orientation="square",
+    reference_images: list[str] | None = None,
+    output_prefix: str | None = None,
+    size: str | None = None,
+    skip_update=False,
+    force=False,
+    file_pattern=None,
+    basename=None,
+):
+    """Unified handler that can process entire story folders or individual files with optional filters."""
+    source_path = Path(source)
+    if not source_path.exists():
+        print(f"Error: Path not found: {source_path}")
+        return
+
+    # Determine prompt files
+    prompt_files = []
+    
+    if source_path.is_file():
+        prompt_files = [source_path]
+    else:
+        # Source is a directory
+        if basename:
+            candidate = source_path / f"{basename}-prompt.txt"
+            if candidate.exists():
+                prompt_files = [candidate]
+        elif file_pattern:
+            import fnmatch
+            try:
+                files = os.listdir(source_path)
+                prompt_files = [source_path / f for f in files if fnmatch.fnmatch(f, file_pattern)]
+            except Exception as e:
+                logger.error("Failed to list directory %s: %s", source_path, e)
+                return
+        else:
+            # Default lookup: illustration-prompt*.txt
+            prompt_files = sorted(source_path.glob("illustration-prompt*.txt"))
+            # Fallback to legacy file name if none found
+            if not prompt_files:
+                legacy = source_path / "illustration-prompt.txt"
+                if legacy.exists():
+                    prompt_files = [legacy]
+
+    if not prompt_files:
+        print(f"No prompt files found in: {source}")
+        return
+
+    for prompt_file in prompt_files:
+        # Check master prompt and skip it if it was matched accidentally
+        if prompt_file.name == "illustration-master-prompt.txt":
+            logger.debug("Skipping master prompt file: %s", prompt_file)
+            continue
+            
+        # Determine output PNG base name
+        if source_path.is_file():
+            # Source is file: out base name is prompt name minus '-prompt'
+            stem = prompt_file.stem
+            out_base = stem.replace("-prompt", "", 1)
+            png_filename = f"{out_base}.png"
+            if output_prefix:
+                png_filename = f"{output_prefix}-{png_filename}"
+            png_path = prompt_file.with_name(png_filename)
+        else:
+            # Source is directory: default output filename is featured.png or base derived from prompt
+            stem = prompt_file.stem
+            out_base = stem.replace("-prompt", "", 1)
+            # Default to "featured.png" for standard single-illustration case, or derivative
+            if out_base == "illustration":
+                png_filename = "featured.png"
+            else:
+                png_filename = f"{out_base}.png"
+                
+            if output_prefix:
+                png_filename = f"{output_prefix}-{png_filename}"
+            png_path = source_path / png_filename
+
+        # Derive WebP and final target paths
+        featured_webp_name = FEATURED_WEBP_FILENAME
+        thumbnail_webp_name = THUMBNAIL_WEBP_FILENAME
+        if output_prefix:
+            featured_webp_name = f"{output_prefix}-{FEATURED_WEBP_FILENAME}"
+            thumbnail_webp_name = f"{output_prefix}-{THUMBNAIL_WEBP_FILENAME}"
+
+        featured_webp_path = png_path.with_name(featured_webp_name)
+        thumbnail_webp_path = png_path.with_name(thumbnail_webp_name)
+
+        # Skip regeneration if not forced and target outputs already exist
+        if not force and (featured_webp_path.exists() or png_path.exists()):
+            print(f"Skipping {png_path.name} (already exists)")
+            continue
+
+        # Generate PNG
+        generated_png = generate_image_from_prompt(
+            prompt_file, 
+            png_path, 
+            model=model, 
+            quality=quality, 
+            orientation=orientation, 
+            reference_images=reference_images, 
+            size=size
+        )
+
+        # Convert to featured/optimized WebPs
+        convert_png_to_webp(generated_png, featured_webp_path)
+        convert_png_to_webp(
+            generated_png,
+            thumbnail_webp_path,
+            max_dimension=THUMBNAIL_MAX_DIMENSION,
+            lossless=False,
+            quality=THUMBNAIL_WEBP_QUALITY,
+        )
+
+        print(f"Saved: {generated_png}")
+        print(f"Saved: {featured_webp_path}")
+        print(f"Saved: {thumbnail_webp_path}")
+
+        # Update Jekyll/Hugo post if index.md exists
+        if not skip_update:
+            article_dir = source_path if source_path.is_dir() else source_path.parent
+            index_path = article_dir / "index.md"
+            if index_path.exists():
+                updated_index = update_index_frontmatter_images(index_path, image_name=thumbnail_webp_name)
+                if updated_index:
+                    print(f"Updated: {updated_index}")
+                # Also replace figure references
+                update_figure_shortcodes_in_index(index_path)

tlnw_generate_image-0.2.0/tlnw_generate_image.egg-info/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: tlnw-generate-image
+Version: 0.2.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, 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**: 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, while passing OpenAI dimensions as-is.
+- **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).
+- **Automated Jekyll/Hugo Updating**: Automatically updates the article frontmatter's `images` block.
+
+## Usage
+Generate illustration for a story folder:
+```bash
+generate-image /path/to/story_folder --model dall-e-3
+```
+
+Process specific prompt files:
+```bash
+generate-image --file /path/to/prompt-1536x1024.txt --model imagen-4-ultra
+```

tlnw_generate_image-0.2.0/tlnw_generate_image.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+tests/test_generate_image.py
+tlnw_generate_image/__init__.py
+tlnw_generate_image/cli.py
+tlnw_generate_image/core.py
+tlnw_generate_image.egg-info/PKG-INFO
+tlnw_generate_image.egg-info/SOURCES.txt
+tlnw_generate_image.egg-info/dependency_links.txt
+tlnw_generate_image.egg-info/entry_points.txt
+tlnw_generate_image.egg-info/requires.txt
+tlnw_generate_image.egg-info/top_level.txt

tlnw_generate_image-0.2.0/tlnw_generate_image.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tlnw_generate_image-0.2.0/tlnw_generate_image.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+generate-image = tlnw_generate_image.cli:main

tlnw_generate_image-0.2.0/tlnw_generate_image.egg-info/requires.txt

@@ -0,0 +1,4 @@
+openai>=1.0.0
+requests>=2.25.0
+pillow>=9.0.0
+python-dotenv>=0.19.0

tlnw_generate_image-0.2.0/tlnw_generate_image.egg-info/top_level.txt

@@ -0,0 +1 @@
+tlnw_generate_image