caudate-cli 0.1.0__py3-none-any.whl

execution/tools/storyboard_tool.py

@@ -0,0 +1,727 @@
+"""Storyboard — turn a story description into a sequence of images.
+
+Pipeline (per request):
+  1. Ask the LLM to break the story into N panel-sized beats.
+  2. Generate panel 1 with FLUX-schnell text→image (Draw backend).
+  3. For panels 2..N, use FLUX.1-Kontext with the previous panel as
+     the reference image — Kontext preserves character identity and
+     setting across panels, which is the whole point of a storyboard.
+  4. Persist every panel to the FileStore.
+  5. Return a markdown gallery the chat UI renders inline (one image
+     per beat, captioned with the beat description).
+
+Time budget on a 24 GB 3090 with `enable_sequential_cpu_offload`:
+  - Panel 1 (Draw, 4 steps): ~10–30 s
+  - Panel N>1 (Kontext, 28 steps): ~6–10 min each
+  So a 6-panel story ≈ 35–50 min. Use `panels` carefully.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from core.image import (
+    DiffusersImageEdit,
+    DiffusersImageGen,
+    ImageEdit,
+    ImageGen,
+)
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+_BREAKDOWN_SYSTEM = """You output a JSON object and nothing else.
+Do NOT include reasoning, analysis, commentary, planning steps, or
+prose of any kind. No code fences, no markdown, no preamble — only
+the raw JSON object. The first character of your response must be
+`{` and the last must be `}`.
+
+You are a story-to-storyboard planner. Given a script or scene
+description, produce a JSON object that captures the structure
+needed to render a visually consistent storyboard.
+
+Use these EXACT keys (do not invent your own; do not use synonyms
+like `description`, `panel_number`, `dialogue`, etc.):
+
+{
+  "art_style": "<global art-style description applied to every panel.
+                Be precise: medium (2D digital, watercolor, oil),
+                line quality, colour palette, lighting, era. ~30 words.>",
+  "characters": [
+    {
+      "name": "<short proper name used to refer to this character>",
+      "visual_description": "<concrete physical traits: hair colour
+                              and style, eye colour, age range, height,
+                              specific clothing items, distinguishing
+                              accessories. ~30 words. Generic enough that
+                              a diffusion model can render it.>"
+    }
+  ],
+  "panels": [
+    {
+      "panel_text": "<the relevant slice of the original script>",
+      "scene_action": "<what is happening visually in this panel:
+                       location, action, framing, time of day. ~25 words.>",
+      "character_names_in_scene": ["<name1>", "<name2>"]
+    }
+  ]
+}
+
+Rules:
+  - Use exactly N panels (the user will specify N).
+  - Reuse the same character names across every panel they appear in.
+    Do NOT invent new names mid-storyboard for the same person.
+  - Every name in a panel's `character_names_in_scene` MUST also appear
+    in the top-level `characters` list.
+  - Keep `scene_action` purely visual (no internal monologue, no
+    inaudible thoughts, no spoken dialogue lines).
+"""
+
+
+def _strip_code_fence(s: str) -> str:
+    s = s.strip()
+    m = re.match(r"^```(?:json)?\s*(.*?)\s*```$", s, re.DOTALL)
+    return m.group(1) if m else s
+
+
+class StoryboardTool(BaseTool):
+    mutates = True
+    name = "Storyboard"
+    description = (
+        "Turn a story description into a SEQUENCE of images (a "
+        "storyboard / comic strip / picture-book spread).\n\n"
+        "Pipeline:\n"
+        "  1. The LLM extracts a structured plan from the script:\n"
+        "       - global art_style description\n"
+        "       - cast list (each character with consistent visual "
+        "         descriptors: hair, clothing, distinguishing traits)\n"
+        "       - per-panel scene_action + which characters appear\n"
+        "  2. Panel 1 is rendered with FLUX-schnell text-to-image,\n"
+        "     prompt = art_style + scene_action + each character's\n"
+        "     visual description.\n"
+        "  3. Panels 2..N use FLUX.1-Kontext img2img referencing the\n"
+        "     previous panel, so faces/outfits/world stay consistent.\n"
+        "Returns a markdown gallery the chat UI renders inline.\n\n"
+        "Use this when the user asks for a comic, picture book, "
+        "storyboard, manga page, multiple images of the story, or to "
+        "'visualize this script'.\n\n"
+        "Time budget on a 24 GB GPU: ~30 s breakdown + ~30 s for panel "
+        "1 + ~7 min per subsequent panel. Default is 6 panels — pick "
+        "fewer for speed.\n\n"
+        "NOTE: panels 2..N use Kontext (non-commercial license)."
+    )
+
+    def __init__(
+        self,
+        file_store: Any | None = None,
+        llm: Any | None = None,
+        image_gen: ImageGen | None = None,
+        image_edit: ImageEdit | None = None,
+    ):
+        self._file_store = file_store
+        self._llm = llm
+        self._image_gen = image_gen
+        self._image_edit = image_edit
+        # Dedicated LLM for the structured-JSON breakdown step.
+        # Lazy-loaded on first use from settings.json::system1, which
+        # is typically a model that's good at strict JSON output (e.g.
+        # GLM-5.1) — distinct from the agent's primary LLM (system2)
+        # used for chat reasoning.
+        self._breakdown_llm: Any | None = None
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "story": {
+                    "type": "string",
+                    "description": (
+                        "The story or scene description. Can be a few "
+                        "lines or several paragraphs. Include character "
+                        "names + visual descriptors so panels stay "
+                        "consistent."
+                    ),
+                },
+                "panels": {
+                    "type": "integer",
+                    "description": "Number of panels (default 6, max 12).",
+                    "default": 6,
+                },
+                "style": {
+                    "type": "string",
+                    "description": (
+                        "Visual style hint, e.g. 'comic book panels with "
+                        "halftone dots', 'watercolor children's book', "
+                        "'noir film stills', 'anime'. Applied to every "
+                        "panel for stylistic consistency."
+                    ),
+                },
+                "size": {
+                    "type": "string",
+                    "description": "Pixel size per panel, e.g. '1024x1024'. Default 1024x1024.",
+                    "default": "1024x1024",
+                },
+                "seed": {
+                    "type": "integer",
+                    "description": "Seed for panel 1 only (Kontext panels follow the chain).",
+                },
+            },
+            "required": ["story"],
+        }
+
+    def set_file_store(self, fs: Any) -> None:
+        self._file_store = fs
+
+    def set_llm(self, llm: Any) -> None:
+        self._llm = llm
+
+    def set_image_gen(self, gen: ImageGen) -> None:
+        self._image_gen = gen
+
+    def set_image_edit(self, edit: ImageEdit) -> None:
+        self._image_edit = edit
+
+    async def _breakdown_story(
+        self, story: str, panels: int, style: str,
+    ) -> dict[str, Any]:
+        """Call the LLM to extract a structured storyboard plan.
+
+        Returns:
+            {
+              "art_style": str,
+              "characters": [{"name": str, "visual_description": str}, ...],
+              "panels": [
+                {"panel_text": str, "scene_action": str,
+                 "character_names_in_scene": [str, ...]}
+              ]
+            }
+
+        Falls back to a heuristic breakdown if the LLM is unavailable
+        or returns malformed JSON — never raises.
+        """
+        # Heuristic fallback used both when no LLM is wired and when
+        # JSON parsing fails. Splits on sentences and packs each into
+        # a panel with no character extraction.
+        def _fallback() -> dict[str, Any]:
+            sentences = re.split(r"(?<=[.!?])\s+", story.strip())
+            sentences = [s for s in sentences if s][:panels] or [story]
+            return {
+                "art_style": (style or "warm storybook illustration").strip(),
+                "characters": [],
+                "panels": [
+                    {
+                        "panel_text": s,
+                        "scene_action": s,
+                        "character_names_in_scene": [],
+                    }
+                    for s in sentences
+                ],
+            }
+
+        # Resolve the breakdown LLM. Prefer the dedicated `system1`
+        # model from settings (typically GLM-5.1, strong at strict
+        # JSON). Fall back to the agent's main LLM if system1 isn't
+        # configured or instantiation fails.
+        breakdown_llm = self._breakdown_llm
+        if breakdown_llm is None:
+            try:
+                from core.settings import Settings
+                from llm.provider import LLMProvider
+                cfg = Settings.load()
+                model_id = cfg.get("system1")
+                if model_id:
+                    breakdown_llm = LLMProvider(model=model_id)
+                    self._breakdown_llm = breakdown_llm
+                    logger.info(
+                        f"Storyboard breakdown will use system1 model: {model_id}"
+                    )
+            except Exception as e:
+                logger.warning(
+                    f"could not init system1 LLM for breakdown ({e}); "
+                    f"falling back to primary LLM"
+                )
+        if breakdown_llm is None:
+            breakdown_llm = self._llm
+        if breakdown_llm is None:
+            return _fallback()
+
+        user = (
+            f"Script:\n{story}\n\nProduce a structured storyboard with "
+            f"exactly {panels} panels. Visual style hint from the user: "
+            f"{style or '(none — choose something appropriate)'}.\n"
+            f"Remember: output a single JSON object as specified."
+        )
+        # Hard-bound the LLM breakdown so a slow / runaway thinking
+        # model can't make the SSE stream stall past the browser's
+        # fetch timeout. 90s is generous for 6 panels of structured
+        # JSON; if it's not back by then, the user is better served
+        # by the heuristic fallback than by a hung connection.
+        try:
+            import asyncio as _asyncio
+            resp = await _asyncio.wait_for(
+                breakdown_llm.chat(
+                    messages=[
+                        {"role": "system", "content": _BREAKDOWN_SYSTEM},
+                        {"role": "user", "content": user},
+                    ],
+                    # Reasoning models (GLM-5.1, Kimi) consume tokens
+                    # in their `thinking` block. 5000 leaves headroom
+                    # for both the chain-of-thought and the JSON.
+                    max_tokens=5000,
+                    temperature=0.5,
+                ),
+                timeout=90.0,
+            )
+        except _asyncio.TimeoutError:
+            logger.warning(
+                "breakdown LLM call timed out at 90s; using fallback"
+            )
+            return _fallback()
+        except Exception as e:
+            logger.warning(f"breakdown LLM call failed ({e}); using fallback")
+            return _fallback()
+
+        # Some thinking-models return content="" with the JSON tucked
+        # inside the `thinking` block. Search both before giving up.
+        content_raw = (resp.content or "").strip()
+        if not content_raw:
+            content_raw = (getattr(resp, "thinking", "") or "").strip()
+        raw = _strip_code_fence(content_raw)
+        try:
+            plan = json.loads(raw)
+        except Exception as e:
+            # Try to recover the JSON object embedded in surrounding prose
+            m = re.search(r"\{[\s\S]+\}", raw)
+            if m:
+                try:
+                    plan = json.loads(m.group(0))
+                except Exception:
+                    logger.warning(
+                        f"breakdown JSON un-parseable ({e}); using fallback"
+                    )
+                    return _fallback()
+            else:
+                logger.warning(
+                    f"breakdown returned no JSON ({e}); using fallback"
+                )
+                return _fallback()
+
+        if not isinstance(plan, dict) or "panels" not in plan:
+            logger.warning("breakdown JSON missing `panels`; using fallback")
+            return _fallback()
+
+        # Normalise + clamp to N panels
+        plan["art_style"] = str(
+            plan.get("art_style") or style or "warm storybook illustration"
+        ).strip()
+        chars = plan.get("characters") or []
+        plan["characters"] = [
+            {
+                "name": str(c.get("name", "")).strip(),
+                "visual_description": str(
+                    c.get("visual_description", "")
+                ).strip(),
+            }
+            for c in chars
+            if isinstance(c, dict) and c.get("name")
+        ]
+        normd_panels = []
+        for p in (plan.get("panels") or [])[:panels]:
+            if not isinstance(p, dict):
+                continue
+            normd_panels.append({
+                "panel_text": str(p.get("panel_text", "")).strip(),
+                "scene_action": str(p.get("scene_action", "")).strip(),
+                "character_names_in_scene": [
+                    str(n).strip()
+                    for n in (p.get("character_names_in_scene") or [])
+                    if isinstance(n, str) and str(n).strip()
+                ],
+            })
+        if not normd_panels:
+            return _fallback()
+        plan["panels"] = normd_panels
+        return plan
+
+    @staticmethod
+    def _panel_prompt(
+        plan: dict[str, Any],
+        panel: dict[str, Any],
+        *,
+        include_full_cast: bool = False,
+    ) -> str:
+        """Build the full prompt for one panel.
+
+        Always includes:
+          - global `art_style`
+          - panel `scene_action`
+          - visual descriptors of characters listed `in_scene`
+
+        When `include_full_cast=True` (used for Kontext panels 2..N),
+        also appends a "World cast (for visual continuity)" block with
+        every other named character's descriptor — strong consistency
+        anchor across the storyboard. Skipped for panel 1 (text→image
+        mode) because FLUX-schnell would risk rendering off-scene
+        characters that the prompt is reminding it about.
+        """
+        parts: list[str] = []
+        if plan.get("art_style"):
+            parts.append(plan["art_style"])
+        if panel.get("scene_action"):
+            parts.append(panel["scene_action"])
+
+        cast = {
+            c["name"].lower(): c["visual_description"]
+            for c in plan.get("characters") or []
+            if c.get("name")
+        }
+        in_scene = [n for n in panel.get("character_names_in_scene") or []]
+        in_scene_lower = {n.lower() for n in in_scene}
+
+        for n in in_scene:
+            desc = cast.get(n.lower())
+            parts.append(f"{n}: {desc}" if desc else n)
+
+        if include_full_cast:
+            offscene = [
+                c for c in plan.get("characters") or []
+                if c.get("name") and c["name"].lower() not in in_scene_lower
+            ]
+            if offscene:
+                world = " | ".join(
+                    f"{c['name']}: {c['visual_description']}"
+                    for c in offscene
+                )
+                parts.append(
+                    "World cast (visual continuity reference, only if "
+                    f"present in this panel): {world}"
+                )
+        return ". ".join(p.strip(". ") for p in parts if p) + "."
+
+    def _release_image_gen(self) -> None:
+        """Free the FLUX-schnell pipeline + GPU memory.
+
+        Called after panel 1 in the storyboard pipeline so the
+        FluxKontextPipeline can be loaded without offload-hook
+        collisions. Best-effort: any exception is swallowed because
+        we don't want pipeline cleanup to abort the storyboard.
+        """
+        gen = self._image_gen
+        if gen is None:
+            return
+        try:
+            # DiffusersImageGen owns a `_pipe` attribute. Drop it so
+            # accelerate's hooks deregister and CUDA tensors get
+            # collected. Force-empty the cache too.
+            inner = getattr(gen, "_pipe", None)
+            if inner is not None:
+                # Move components to CPU first to make sure offloaded
+                # weights actually leave the GPU.
+                try:
+                    inner.to("cpu")
+                except Exception:
+                    pass
+                setattr(gen, "_pipe", None)
+            self._image_gen = None
+            import gc, torch
+            gc.collect()
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+            logger.info("Storyboard: released FLUX-schnell pipeline before Kontext")
+        except Exception as e:
+            logger.warning(f"Storyboard: image_gen release failed: {e}")
+
+    def _ensure_backends(self) -> None:
+        if self._image_gen is None:
+            # Default: same FLUX-schnell weights Draw uses
+            self._image_gen = DiffusersImageGen(
+                model="black-forest-labs/FLUX.1-schnell",
+            )
+        if self._image_edit is None:
+            self._image_edit = DiffusersImageEdit()
+
+    async def execute_streaming(self, **kwargs: Any):
+        """Async generator that yields progress events as panels render.
+
+        Yields dicts of shape:
+          {"type": "breakdown", "plan": {...}}
+          {"type": "panel", "index": int, "file_id": str,
+           "scene_action": str, "panel_text": str,
+           "character_names_in_scene": [str, ...]}
+          {"type": "done", "panel_count": int, "panel_file_ids": [str, ...]}
+          {"type": "error", "message": str}
+
+        Used by the /storyboard/generate SSE endpoint. The non-streaming
+        `execute()` consumes this same generator under the hood.
+        """
+        story = (kwargs.get("story") or "").strip()
+        if not story:
+            yield {"type": "error", "message": "`story` is required"}
+            return
+        if self._file_store is None:
+            yield {
+                "type": "error",
+                "message": "Storyboard is not wired to a FileStore.",
+            }
+            return
+
+        panels = max(1, min(12, int(kwargs.get("panels") or 6)))
+        style = (kwargs.get("style") or "").strip()
+        size = kwargs.get("size") or "1024x1024"
+        seed = kwargs.get("seed")
+        self._ensure_backends()
+
+        # Surface a "started" event before the slow LLM breakdown call
+        # so the SSE connection isn't idle for ~30-90 s — the React
+        # client (and proxies) treat long idle streams as broken.
+        yield {
+            "type": "started",
+            "message": (
+                f"Analyzing script and extracting cast for "
+                f"{panels} panels..."
+            ),
+        }
+
+        # 1) Breakdown
+        plan = await self._breakdown_story(story, panels, style)
+        plan_panels = plan.get("panels") or []
+        if not plan_panels:
+            yield {"type": "error", "message": "story produced no panels"}
+            return
+        yield {"type": "breakdown", "plan": plan}
+
+        # 2) Panel 1 — Draw (text→image; only in-scene characters
+        #    so FLUX-schnell doesn't hallucinate off-scene cast).
+        gen_kwargs: dict[str, Any] = {"size": size}
+        if seed is not None:
+            gen_kwargs["seed"] = int(seed)
+        prompt1 = self._panel_prompt(plan, plan_panels[0])
+        try:
+            png1 = await self._image_gen.generate(prompt1, **gen_kwargs)
+        except Exception as e:
+            logger.exception("Storyboard panel 1 failed")
+            yield {"type": "error", "message": f"panel 1 failed: {e}"}
+            return
+        rec1 = self._save_panel(
+            png1, 1, plan_panels[0].get("scene_action", ""),
+        )
+        yield {
+            "type": "panel",
+            "index": 1,
+            "file_id": rec1.id,
+            **{k: plan_panels[0].get(k, "") for k in (
+                "scene_action", "panel_text", "character_names_in_scene",
+            )},
+        }
+        # Fix 1 (anti-drift): every subsequent panel keys off PANEL 1
+        # — never the immediately previous panel — so the canonical
+        # look is at most 1 hop away from any panel.
+        anchor_bytes = png1
+        ids: list[str] = [rec1.id]
+
+        # Free the FLUX-schnell pipeline before Kontext loads. See
+        # `execute()` above for the full rationale — accelerate
+        # offload hooks collide otherwise.
+        self._release_image_gen()
+
+        # 3) Panels 2..N — Kontext, anchored on panel 1
+        for i, p in enumerate(plan_panels[1:], start=2):
+            panel_prompt = self._panel_prompt(
+                plan, p, include_full_cast=True,
+            )
+            instruction = (
+                f"Same characters (faces / outfits), same art style, "
+                f"same lighting and palette as the source image. "
+                f"New scene: {panel_prompt}"
+            )
+            try:
+                png_n = await self._image_edit.edit(
+                    image_bytes=anchor_bytes,
+                    prompt=instruction,
+                    mode="edit",
+                    size=size,
+                )
+            except Exception as e:
+                logger.exception(f"Storyboard panel {i} failed")
+                yield {
+                    "type": "error",
+                    "message": f"panel {i} failed: {e}",
+                }
+                yield {
+                    "type": "done",
+                    "panel_count": len(ids),
+                    "panel_file_ids": ids,
+                }
+                return
+            rec_n = self._save_panel(png_n, i, p.get("scene_action", ""))
+            ids.append(rec_n.id)
+            yield {
+                "type": "panel",
+                "index": i,
+                "file_id": rec_n.id,
+                **{k: p.get(k, "") for k in (
+                    "scene_action", "panel_text", "character_names_in_scene",
+                )},
+            }
+            # Note: deliberately NOT updating anchor_bytes — keeps
+            # panel 1 as the persistent style/character anchor.
+
+        yield {
+            "type": "done",
+            "panel_count": len(ids),
+            "panel_file_ids": ids,
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        story = (kwargs.get("story") or "").strip()
+        if not story:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`story` is required",
+            )
+        if self._file_store is None:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="Storyboard is not wired to a FileStore.",
+            )
+
+        panels = max(1, min(12, int(kwargs.get("panels") or 6)))
+        style = (kwargs.get("style") or "").strip()
+        size = kwargs.get("size") or "1024x1024"
+        seed = kwargs.get("seed")
+
+        self._ensure_backends()
+
+        # 1) Structured breakdown — art style, cast, panels
+        plan = await self._breakdown_story(story, panels, style)
+        plan_panels = plan.get("panels") or []
+        if not plan_panels:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="story produced no panels",
+            )
+
+        # 2) Panel 1 — Draw with full structured prompt
+        gen_kwargs: dict[str, Any] = {"size": size}
+        if seed is not None:
+            gen_kwargs["seed"] = int(seed)
+        prompt1 = self._panel_prompt(plan, plan_panels[0])
+        try:
+            png1 = await self._image_gen.generate(prompt1, **gen_kwargs)
+        except Exception as e:
+            logger.exception("Storyboard panel 1 failed")
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"panel 1 generation failed: {e}",
+            )
+        # Fix 1: pin the anchor to panel 1 so subsequent panels can't
+        # drift more than 1 hop from the canonical look.
+        anchor_bytes = png1
+        records: list[tuple[dict[str, Any], Any]] = [(
+            plan_panels[0],
+            self._save_panel(png1, 1, plan_panels[0].get("scene_action", "")),
+        )]
+
+        # Fix: free the FLUX-schnell pipeline before loading Kontext.
+        # When both pipelines are resident with `enable_sequential_
+        # cpu_offload`, accelerate's offload hooks can collide and
+        # one pipeline's scheduler reads the other's sigma array,
+        # causing "index N out of bounds for size N" mid-denoise on
+        # panel 2. We won't need Draw again in this storyboard, so
+        # release it.
+        self._release_image_gen()
+
+        # 3) Panels 2..N — Kontext keyed on PANEL 1 (not previous)
+        for i, p in enumerate(plan_panels[1:], start=2):
+            panel_prompt = self._panel_prompt(plan, p, include_full_cast=True)
+            instruction = (
+                f"Same characters (faces / outfits), same art style, "
+                f"same lighting and palette as the source image. "
+                f"New scene: {panel_prompt}"
+            )
+            try:
+                png_n = await self._image_edit.edit(
+                    image_bytes=anchor_bytes,
+                    prompt=instruction,
+                    mode="edit",
+                    size=size,
+                )
+            except Exception as e:
+                logger.exception(f"Storyboard panel {i} failed")
+                break
+            records.append((
+                p,
+                self._save_panel(png_n, i, p.get("scene_action", "")),
+            ))
+            # anchor_bytes stays = panel 1 (no chain accumulation)
+
+        # 4) Render gallery markdown
+        gallery: list[str] = [
+            f"**Storyboard — {len(records)} panel(s)**",
+            f"*Style:* {plan.get('art_style', '')}",
+        ]
+        if plan.get("characters"):
+            gallery.append("*Cast:* " + ", ".join(
+                f"**{c['name']}** ({c['visual_description'][:60]}…)"
+                for c in plan["characters"]
+            ))
+        gallery.append("")
+        ids: list[str] = []
+        for i, (p, rec) in enumerate(records, start=1):
+            url = f"http://127.0.0.1:8000/files/{rec.id}/content"
+            viewer = f"http://127.0.0.1:8000/artifact/{rec.id}"
+            beat = p.get("scene_action") or p.get("panel_text") or ""
+            short = beat[:160] + ("…" if len(beat) > 160 else "")
+            gallery.append(f"**Panel {i}.** {short}")
+            gallery.append(f"![{short}]({url})")
+            gallery.append(f"[📄 viewer]({viewer})")
+            gallery.append("")
+            ids.append(rec.id)
+
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(gallery),
+            metadata={
+                "panel_count": len(records),
+                "panel_file_ids": ids,
+                "art_style": plan.get("art_style"),
+                "characters": plan.get("characters"),
+                "panels": [
+                    {
+                        "panel_text": p.get("panel_text", ""),
+                        "scene_action": p.get("scene_action", ""),
+                        "character_names_in_scene": p.get(
+                            "character_names_in_scene", []
+                        ),
+                        "file_id": rec.id,
+                    }
+                    for p, rec in records
+                ],
+            },
+        )
+
+    def _save_panel(self, png: bytes, idx: int, beat: str) -> Any:
+        """Save panel bytes to FileStore and return the FileRecord."""
+        with tempfile.NamedTemporaryFile(
+            suffix=".png", delete=False,
+        ) as tmp:
+            tmp.write(png)
+            tmp_path = Path(tmp.name)
+        try:
+            slug = "".join(
+                c for c in beat[:30]
+                if c.isalnum() or c in " _-"
+            ).strip().replace(" ", "_") or "panel"
+            return self._file_store.upload(
+                tmp_path, filename=f"panel_{idx:02d}_{slug}.png",
+            )
+        finally:
+            tmp_path.unlink(missing_ok=True)