slide-stream 2.2.0__tar.gz → 2.4.0__tar.gz

{slide_stream-2.2.0 → slide_stream-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide-stream
-Version: 2.2.0
+Version: 2.4.0
 Summary: An AI-powered tool to automatically create video presentations from Markdown and PowerPoint files
 Project-URL: Homepage, https://github.com/michael-borck/slide-stream
 Project-URL: Repository, https://github.com/michael-borck/slide-stream
@@ -36,6 +36,7 @@ Requires-Dist: typing-extensions>=4.8.0
 Provides-Extra: all-ai
 Requires-Dist: anthropic>=0.7.0; extra == 'all-ai'
 Requires-Dist: elevenlabs<3.0.0,>=1.5.0; extra == 'all-ai'
+Requires-Dist: google-genai>=1.0.0; extra == 'all-ai'
 Requires-Dist: google-generativeai>=0.3.0; extra == 'all-ai'
 Requires-Dist: groq>=0.4.0; extra == 'all-ai'
 Requires-Dist: openai>=1.0.0; extra == 'all-ai'
@@ -51,6 +52,7 @@ Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Provides-Extra: elevenlabs
 Requires-Dist: elevenlabs<3.0.0,>=1.5.0; extra == 'elevenlabs'
 Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == 'gemini'
 Requires-Dist: google-generativeai>=0.3.0; extra == 'gemini'
 Provides-Extra: groq
 Requires-Dist: groq>=0.4.0; extra == 'groq'
@@ -168,7 +170,19 @@ slide-stream create --config my-config.yaml presentation.pptx video.mp4
 
 ## ⚙️ Configuration
 
-SlideStream uses YAML configuration files for maximum flexibility:
+SlideStream layers configuration so you set shared things (a TTS server URL,
+API keys) once and keep per-deck settings separate. Later layers win:
+
+1. Built-in defaults
+2. **`~/.slidestream.yaml`** — personal: your Chatterbox/LLM server URLs and
+   API-key references, shared across every project
+3. **`./slidestream.yaml`** (or `--config FILE`) — settings for the deck at hand
+4. **CLI flags** (`--voice`, `--tts-base-url`, `--narration-seconds`, …) — win
+   over everything, for one-off runs
+
+Run `slide-stream init` to write a starter `slidestream.yaml`. API keys are
+read from the environment via `${VAR}` expansion, so secrets never live in the
+files. Example:
 
 ```yaml
 # slidestream.yaml
@@ -357,10 +371,37 @@ sudo apt update && sudo apt install ffmpeg
 
 **Image Providers:**
 - `text`: Always available, no setup required
+- `local`: Pick images from a local folder by filename keywords (`providers.images.folder`); pair with `slide-stream scan` to AI-name them
 - `dalle3`: Requires `OPENAI_API_KEY`
+- `gemini`: Google Imagen generation, cheap (~$0.02/image) — `pip install "slide-stream[gemini]"` + `GEMINI_API_KEY`; set `providers.images.model` for the Imagen tier (default Fast)
+- `swarmui`: Self-hosted [SwarmUI](https://github.com/mcmonkeyprojects/SwarmUI) server (`base_url`), free local generation via its native API — set `providers.images.model` (e.g. `juggernautXL_v9`), optional `steps`/`width`/`height`/`api_key`
 - `pexels`: Requires `PEXELS_API_KEY`  
 - `unsplash`: Requires `UNSPLASH_ACCESS_KEY`
 
+### Enriching a deck with images (`enrich` / `scan`)
+
+Beyond making videos, SlideStream can add an image to each slide and write a
+**new editable deck** — no narration, no video, your original untouched:
+
+```bash
+# Markdown deck + images/ folder (default). Add --pptx for a PowerPoint too.
+slide-stream enrich deck.md out/ --image-provider dalle3
+slide-stream enrich deck.md out/ --image-provider local --image-folder ./pics --pptx
+```
+
+The output is a real artifact you can review, hand-edit, or narrate as a second
+pass (`slide-stream create out/deck.md video.mp4`). For a one-pass video that
+adds images *and* narrates internally, just run `create` with an image
+provider configured — `enrich` is the deck-only track.
+
+`scan` AI-renames a folder of images to keyword slugs so the `local` provider
+can match them to slides (dry-run by default):
+
+```bash
+slide-stream scan ./pics --provider claude          # preview renames
+slide-stream scan ./pics --provider claude --apply  # actually rename + write report
+```
+
 **TTS Providers:**
 - `gtts`: Free, always available (needs internet)
 - `kokoro`: Fully offline, no API key — `pip install "slide-stream[local-tts]"` (~340MB one-time model download; voices include `af_sarah`, `af_bella`, `am_adam`, `am_michael`)

{slide_stream-2.2.0 → slide_stream-2.4.0}/README.md

@@ -105,7 +105,19 @@ slide-stream create --config my-config.yaml presentation.pptx video.mp4
 
 ## ⚙️ Configuration
 
-SlideStream uses YAML configuration files for maximum flexibility:
+SlideStream layers configuration so you set shared things (a TTS server URL,
+API keys) once and keep per-deck settings separate. Later layers win:
+
+1. Built-in defaults
+2. **`~/.slidestream.yaml`** — personal: your Chatterbox/LLM server URLs and
+   API-key references, shared across every project
+3. **`./slidestream.yaml`** (or `--config FILE`) — settings for the deck at hand
+4. **CLI flags** (`--voice`, `--tts-base-url`, `--narration-seconds`, …) — win
+   over everything, for one-off runs
+
+Run `slide-stream init` to write a starter `slidestream.yaml`. API keys are
+read from the environment via `${VAR}` expansion, so secrets never live in the
+files. Example:
 
 ```yaml
 # slidestream.yaml
@@ -294,10 +306,37 @@ sudo apt update && sudo apt install ffmpeg
 
 **Image Providers:**
 - `text`: Always available, no setup required
+- `local`: Pick images from a local folder by filename keywords (`providers.images.folder`); pair with `slide-stream scan` to AI-name them
 - `dalle3`: Requires `OPENAI_API_KEY`
+- `gemini`: Google Imagen generation, cheap (~$0.02/image) — `pip install "slide-stream[gemini]"` + `GEMINI_API_KEY`; set `providers.images.model` for the Imagen tier (default Fast)
+- `swarmui`: Self-hosted [SwarmUI](https://github.com/mcmonkeyprojects/SwarmUI) server (`base_url`), free local generation via its native API — set `providers.images.model` (e.g. `juggernautXL_v9`), optional `steps`/`width`/`height`/`api_key`
 - `pexels`: Requires `PEXELS_API_KEY`  
 - `unsplash`: Requires `UNSPLASH_ACCESS_KEY`
 
+### Enriching a deck with images (`enrich` / `scan`)
+
+Beyond making videos, SlideStream can add an image to each slide and write a
+**new editable deck** — no narration, no video, your original untouched:
+
+```bash
+# Markdown deck + images/ folder (default). Add --pptx for a PowerPoint too.
+slide-stream enrich deck.md out/ --image-provider dalle3
+slide-stream enrich deck.md out/ --image-provider local --image-folder ./pics --pptx
+```
+
+The output is a real artifact you can review, hand-edit, or narrate as a second
+pass (`slide-stream create out/deck.md video.mp4`). For a one-pass video that
+adds images *and* narrates internally, just run `create` with an image
+provider configured — `enrich` is the deck-only track.
+
+`scan` AI-renames a folder of images to keyword slugs so the `local` provider
+can match them to slides (dry-run by default):
+
+```bash
+slide-stream scan ./pics --provider claude          # preview renames
+slide-stream scan ./pics --provider claude --apply  # actually rename + write report
+```
+
 **TTS Providers:**
 - `gtts`: Free, always available (needs internet)
 - `kokoro`: Fully offline, no API key — `pip install "slide-stream[local-tts]"` (~340MB one-time model download; voices include `af_sarah`, `af_bella`, `am_adam`, `am_michael`)

{slide_stream-2.2.0 → slide_stream-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "slide-stream"
-version = "2.2.0"
+version = "2.4.0"
 description = "An AI-powered tool to automatically create video presentations from Markdown and PowerPoint files"
 readme = "README.md"
 license = { text = "MIT" }
@@ -43,7 +43,7 @@ dependencies = [
 
 [project.optional-dependencies]
 # AI providers
-gemini = ["google-generativeai>=0.3.0"]
+gemini = ["google-generativeai>=0.3.0", "google-genai>=1.0.0"]
 openai = ["openai>=1.0.0"]
 claude = ["anthropic>=0.7.0"]
 groq = ["groq>=0.4.0"]
@@ -55,6 +55,7 @@ local-tts = [
 ]
 all-ai = [
     "google-generativeai>=0.3.0",
+    "google-genai>=1.0.0",
     "openai>=1.0.0",
     "anthropic>=0.7.0",
     "groq>=0.4.0",

{slide_stream-2.2.0 → slide_stream-2.4.0}/src/slide_stream/__init__.py

@@ -1,5 +1,5 @@
 """Slide Stream - AI-powered tool for creating video presentations from Markdown."""
 
-__version__ = "2.2.0"
+__version__ = "2.4.0"
 __author__ = "Michael Borck"
 __email__ = "michael.borck@curtin.edu.au"

{slide_stream-2.2.0 → slide_stream-2.4.0}/src/slide_stream/cli.py

@@ -604,6 +604,168 @@ def create(
             console.print("✅ Cleanup complete.")
 
 
+def _parse_deck(input_path: Path) -> list[dict[str, Any]]:
+    """Parse a .md or .pptx deck into slide dicts, or exit with an error."""
+    ext = input_path.suffix.lower()
+    if not input_path.exists():
+        err_console.print(f"Input file not found: {input_path}")
+        raise typer.Exit(code=1)
+    if ext == ".md":
+        with open(input_path, encoding="utf-8") as f:
+            text = f.read()
+        if not text.strip():
+            err_console.print("Markdown file is empty. Exiting.")
+            raise typer.Exit(code=1)
+        return parse_markdown(text)
+    if ext == ".pptx":
+        try:
+            return parse_powerpoint(input_path)
+        except ValueError as e:
+            err_console.print(f"Error parsing PowerPoint: {e}")
+            raise typer.Exit(code=1)
+    err_console.print(f"Unsupported file type: {ext}. Supported: .md, .pptx")
+    raise typer.Exit(code=1)
+
+
+@app.command()
+def enrich(
+    input_path: Annotated[
+        Path,
+        typer.Argument(help="Input deck (Markdown .md or PowerPoint .pptx)."),
+    ],
+    output_dir: Annotated[
+        str,
+        typer.Argument(help="Directory for the enriched deck and images."),
+    ] = "enriched",
+    config_file: Annotated[
+        str | None, typer.Option("--config", "-c", help="Config file (YAML).")
+    ] = None,
+    image_provider_option: Annotated[
+        str | None,
+        typer.Option(
+            "--image-provider",
+            help="Image provider (local, dalle3, pexels, unsplash, openai-compatible).",
+        ),
+    ] = None,
+    image_folder: Annotated[
+        str | None,
+        typer.Option("--image-folder", help="Folder of images for the 'local' provider."),
+    ] = None,
+    pptx: Annotated[
+        bool,
+        typer.Option("--pptx", help="Also write an enriched PowerPoint (.pptx)."),
+    ] = False,
+    zip_output: Annotated[
+        bool, typer.Option("--zip", help="Also write a .zip of the output folder.")
+    ] = False,
+) -> None:
+    """Add an image to each slide and write a new deck (no video).
+
+    The output is an editable Markdown deck plus an images/ folder — run
+    'create' on it to narrate, or use 'create' directly for a one-pass video.
+    """
+    console.print(
+        Panel.fit("[bold cyan]🖼️  Enriching deck[/bold cyan]", border_style="green")
+    )
+    try:
+        config = load_config(config_file)
+    except ConfigurationError as e:
+        err_console.print(f"Configuration Error: {e}")
+        raise typer.Exit(code=1)
+
+    if image_provider_option:
+        config["providers"]["images"]["provider"] = image_provider_option
+    if image_folder:
+        config["providers"]["images"]["folder"] = image_folder
+
+    slides = _parse_deck(input_path)
+    if not slides:
+        err_console.print("No slides found. Exiting.")
+        raise typer.Exit(code=1)
+    console.print(f"📄 Found [bold yellow]{len(slides)}[/bold yellow] slides.")
+
+    try:
+        image_provider = ProviderFactory.create_image_provider(config)
+    except StrictModeError as e:
+        err_console.print(f"{e}")
+        raise typer.Exit(code=1)
+
+    from .enrich import enrich_deck
+
+    out = enrich_deck(
+        slides,
+        image_provider,
+        Path(output_dir),
+        input_path.stem,
+        also_pptx=pptx,
+        also_zip=zip_output,
+    )
+    console.print(
+        Panel(
+            f"🎉 [bold green]Enriched deck written[/bold green]\n\n"
+            f"Markdown: [yellow]{out / (input_path.stem + '.md')}[/yellow]"
+            + (f"\nPowerPoint: [yellow]{out / (input_path.stem + '.pptx')}[/yellow]" if pptx else "")
+            + f"\nImages: [yellow]{out / 'images'}[/yellow]",
+            border_style="green",
+            expand=False,
+        )
+    )
+
+
+@app.command()
+def scan(
+    folder: Annotated[
+        Path, typer.Argument(help="Folder of images to AI-rename to keyword slugs.")
+    ],
+    provider: Annotated[
+        str,
+        typer.Option("--provider", help="Vision LLM provider (claude, openai, gemini)."),
+    ] = "claude",
+    model: Annotated[
+        str | None, typer.Option("--model", help="Specific vision model to use.")
+    ] = None,
+    apply: Annotated[
+        bool,
+        typer.Option(
+            "--apply",
+            help="Actually rename files (default is a dry-run preview).",
+        ),
+    ] = False,
+) -> None:
+    """AI-rename images in a folder to keyword slugs for the 'local' provider."""
+    if not folder.is_dir():
+        err_console.print(f"Not a directory: {folder}")
+        raise typer.Exit(code=1)
+
+    from .scan import apply_renames, build_rename_records, write_scan_report
+
+    try:
+        records = build_rename_records(folder, provider, model)
+    except (ImportError, ValueError) as e:
+        err_console.print(f"Vision provider error: {e}")
+        raise typer.Exit(code=1)
+
+    if not records:
+        console.print("No images found in the folder.")
+        return
+
+    applied = apply_renames(records, dry_run=not apply)
+
+    table = Table(title="Dry run — no files changed" if not apply else "Renamed")
+    table.add_column("Original", style="cyan")
+    table.add_column("→", style="dim")
+    table.add_column("New name", style="green")
+    for orig, new in applied:
+        table.add_row(orig.name, "→", new.name)
+    console.print(table)
+
+    if apply:
+        report = write_scan_report(folder, applied)
+        console.print(f"📝 Report: [yellow]{report}[/yellow]")
+    else:
+        console.print("\n[dim]Re-run with --apply to rename the files.[/dim]")
+
+
 @app.command()
 def init(
     output_path: Annotated[

{slide_stream-2.2.0 → slide_stream-2.4.0}/src/slide_stream/config_loader.py

@@ -26,7 +26,8 @@ DEFAULT_CONFIG = {
         "images": {
             "provider": "text",
             "fallback": "text",
-            "base_url": None  # used by the openai-compatible provider
+            "base_url": None,  # used by the openai-compatible provider
+            "folder": None     # used by the 'local' provider (enrich/create)
         },
         "tts": {
             "provider": "gtts",
@@ -91,47 +92,88 @@ def expand_env_vars(value: Any) -> Any:
     return value
 
 
-def find_config_file() -> Path | None:
-    """Find configuration file in standard locations."""
-    possible_locations = [
+def _first_existing(*candidates: Path) -> Path | None:
+    """Return the first path that exists, or None."""
+    for path in candidates:
+        if path.exists():
+            return path
+    return None
+
+
+def find_home_config() -> Path | None:
+    """Find the user-level config (~/.slidestream.yaml) — personal defaults
+    like a TTS server URL and API keys, shared across all projects."""
+    return _first_existing(
+        Path.home() / ".slidestream.yaml",
+        Path.home() / ".slidestream.yml",
+    )
+
+
+def find_project_config() -> Path | None:
+    """Find the project-level config (./slidestream.yaml) — settings for the
+    deck at hand."""
+    return _first_existing(
         Path("./slidestream.yaml"),
         Path("./slidestream.yml"),
-        Path.home() / ".slidestream.yaml",
-        Path.home() / ".slidestream.yml"
-    ]
+    )
 
-    for location in possible_locations:
-        if location.exists():
-            return location
 
-    return None
+def find_config_file() -> Path | None:
+    """Find a single config file (project preferred, then home).
 
+    Retained for backwards compatibility; ``load_config`` layers home and
+    project configs rather than using this.
+    """
+    return find_project_config() or find_home_config()
+
+
+def _read_config_file(config_file: Path) -> dict[str, Any] | None:
+    """Read and parse one YAML config file (None if empty)."""
+    try:
+        with open(config_file, encoding="utf-8") as f:
+            return yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise ConfigurationError(f"Invalid YAML in config file: {e}")
+    except Exception as e:
+        raise ConfigurationError(f"Error reading config file: {e}")
 
-def load_config(config_path: str | None = None) -> dict[str, Any]:
-    """Load configuration from file or return defaults."""
-    config = DEFAULT_CONFIG.copy()
 
+def load_config(config_path: str | None = None) -> dict[str, Any]:
+    """Load configuration by layering, later layers winning:
+
+    1. Built-in defaults
+    2. User-level config (~/.slidestream.yaml) — personal server URLs / keys
+    3. Project-level config — the explicit ``config_path`` if given, otherwise
+       ./slidestream.yaml
+
+    So a personal home config can hold your TTS server and API keys once, and
+    each project's config only needs its deck-specific overrides.
+    """
+    import copy
+
+    config = copy.deepcopy(DEFAULT_CONFIG)
+
+    # Layer sources: (label, path). Home is always layered underneath; an
+    # explicit --config replaces the auto-discovered project file but still
+    # sits on top of home.
+    sources: list[Path] = []
+    if home_config := find_home_config():
+        sources.append(home_config)
     if config_path:
-        config_file = Path(config_path)
-        if not config_file.exists():
+        project_config = Path(config_path)
+        if not project_config.exists():
             raise ConfigurationError(f"Configuration file not found: {config_path}")
-    else:
-        config_file = find_config_file()
-
-    if config_file:
-        try:
-            with open(config_file, encoding='utf-8') as f:
-                file_config = yaml.safe_load(f)
-
-            if file_config:
-                # Deep merge with defaults
-                config = merge_configs(config, file_config)
-                console.print(f"✅ Loaded configuration from: {config_file}")
-        except yaml.YAMLError as e:
-            raise ConfigurationError(f"Invalid YAML in config file: {e}")
-        except Exception as e:
-            raise ConfigurationError(f"Error reading config file: {e}")
-    else:
+        sources.append(project_config)
+    elif project_config := find_project_config():
+        sources.append(project_config)
+
+    for source in sources:
+        file_config = _read_config_file(source)
+        if file_config:
+            config = merge_configs(config, file_config)
+            console.print(f"✅ Loaded configuration from: {source}")
+
+    if not sources:
         console.print("📋 Using default configuration")
 
     # Expand environment variables
@@ -181,6 +223,13 @@ def validate_config(config: dict[str, Any]) -> None:
 def create_example_config() -> str:
     """Create example configuration file content."""
     return """# SlideStream Configuration File
+#
+# Config is layered, later winning:
+#   1. built-in defaults
+#   2. ~/.slidestream.yaml   (personal: TTS server URL, API keys — set once)
+#   3. ./slidestream.yaml    (this deck's settings; or pass --config FILE)
+# So keep your server and keys in the home file and only put per-deck
+# overrides here. Any CLI flag (e.g. --voice, --tts-base-url) wins over both.
 
 providers:
   llm:
@@ -194,8 +243,14 @@ providers:
     # narrated via vision-capable providers (claude, openai, gemini).
 
   images:
-    provider: dalle3        # text, dalle3, openai-compatible, pexels, unsplash
+    provider: dalle3        # text, local, dalle3, gemini, swarmui, openai-compatible, pexels, unsplash
     fallback: text         # fallback when primary fails
+    # folder: ./images     # for the 'local' provider — matched by filename keywords
+    # model: imagen-4.0-fast-generate-001   # for the 'gemini' (Imagen) provider
+    # --- self-hosted SwarmUI ---
+    # base_url: https://image.example.org
+    # model: juggernautXL_v9   # SwarmUI model name
+    # steps: 20
 
   tts:
     provider: elevenlabs   # gtts, kokoro, elevenlabs, openai, openai-compatible

slide_stream-2.4.0/src/slide_stream/enrich.py

@@ -0,0 +1,137 @@
+"""Deck enrichment: add an image to each slide and write a new deck.
+
+This is the ``enrich`` output track (ported/adapted from slide-vision): the
+same slide input, but instead of a narrated video the output is a new,
+editable deck — a Markdown file plus an ``images/`` folder, and optionally a
+PowerPoint. Run ``create`` on the result to narrate it, or use ``create``
+directly (it enriches internally) for a one-pass video.
+"""
+
+import zipfile
+from pathlib import Path
+from typing import Any
+
+from .providers.base import ImageProvider
+
+
+def _slide_query(slide: dict[str, Any]) -> str:
+    """A search/keyword query for a slide's image."""
+    title = str(slide.get("title", "")).strip()
+    if title:
+        return title
+    for item in slide.get("content", []):
+        text = str(item).strip()
+        if text:
+            return text
+    return "presentation slide"
+
+
+def enrich_deck(
+    slides: list[dict[str, Any]],
+    image_provider: ImageProvider,
+    output_dir: Path,
+    input_stem: str,
+    *,
+    also_pptx: bool = False,
+    also_zip: bool = False,
+) -> Path:
+    """Write an enriched Markdown deck (and optional PPTX) into output_dir.
+
+    Returns the output directory. Each slide gets an image from
+    ``image_provider``; slides the ``local`` provider could not match are
+    listed in ``prompts.md`` with ready-to-paste AI-image prompts.
+    """
+    images_dir = output_dir / "images"
+    images_dir.mkdir(parents=True, exist_ok=True)
+
+    enriched: list[dict[str, Any]] = []
+    for i, slide in enumerate(slides, 1):
+        img_path = images_dir / f"slide_{i}.png"
+        image_provider.generate_image(_slide_query(slide), str(img_path), slide=slide)
+        # The local provider reports whether it matched a real folder image;
+        # other providers always produce an image (or their own text fallback).
+        matched = getattr(image_provider, "matched_last", True)
+        enriched.append(
+            {
+                "index": i,
+                "title": str(slide.get("title", "")).strip(),
+                "content": [str(c).strip() for c in slide.get("content", []) if str(c).strip()],
+                "image": img_path.name,
+                "matched": matched,
+            }
+        )
+
+    md_path = output_dir / f"{input_stem}.md"
+    md_path.write_text(_build_markdown(enriched), encoding="utf-8")
+
+    missing = [s for s in enriched if not s["matched"]]
+    if missing:
+        (output_dir / "prompts.md").write_text(_build_prompts(missing), encoding="utf-8")
+
+    if also_pptx:
+        _write_pptx(enriched, images_dir, output_dir / f"{input_stem}.pptx")
+
+    if also_zip:
+        zip_path = output_dir.parent / f"{output_dir.name}.zip"
+        with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+            for f in output_dir.rglob("*"):
+                if f.is_file():
+                    zf.write(f, f.relative_to(output_dir.parent))
+
+    return output_dir
+
+
+def _build_markdown(slides: list[dict[str, Any]]) -> str:
+    blocks: list[str] = []
+    for slide in slides:
+        lines = [f"# {slide['title']}" if slide["title"] else f"# Slide {slide['index']}"]
+        lines.append("")
+        lines.append(f"![{slide['title']}](images/{slide['image']})")
+        if slide["content"]:
+            lines.append("")
+            for item in slide["content"]:
+                lines.append(f"- {item}")
+        blocks.append("\n".join(lines))
+    return "\n\n---\n\n".join(blocks) + "\n"
+
+
+def _build_prompts(missing: list[dict[str, Any]]) -> str:
+    lines = ["# Image Prompts", "",
+             "Slides with no matching local image. Paste a prompt into an AI "
+             "image tool (DALL-E, Midjourney, ...) and drop the result into "
+             "the images/ folder.", ""]
+    for slide in missing:
+        preview = " ".join(slide["content"])[:300]
+        lines += [
+            f"## Slide {slide['index']}: {slide['title']}",
+            "",
+            f'A high-quality, professional illustration for a presentation slide '
+            f'titled "{slide["title"]}".',
+        ]
+        if preview:
+            lines.append(f"The slide covers: {preview}.")
+        lines += ["Style: clean, modern, no text overlays.", "", "---", ""]
+    return "\n".join(lines)
+
+
+def _write_pptx(slides: list[dict[str, Any]], images_dir: Path, out_path: Path) -> None:
+    """Build a PowerPoint deck with one image slide per entry."""
+    from pptx import Presentation
+    from pptx.util import Emu, Inches
+
+    prs = Presentation()
+    # Default deck is 10" x 7.5"; fall back to that if the stubs report None.
+    width = Emu(prs.slide_width) if prs.slide_width else Inches(10)
+    blank = prs.slide_layouts[6]
+    content_width = Emu(width - Inches(1))
+    image_width = Emu(width - Inches(2))
+    for slide in slides:
+        s = prs.slides.add_slide(blank)
+        # Title textbox across the top.
+        title_box = s.shapes.add_textbox(Inches(0.5), Inches(0.3), content_width, Inches(1))
+        title_box.text_frame.text = slide["title"] or f"Slide {slide['index']}"
+        # Image centered below the title, scaled to fit.
+        img = images_dir / slide["image"]
+        if img.is_file():
+            s.shapes.add_picture(str(img), Inches(1), Inches(1.5), width=image_width)
+    prs.save(str(out_path))