chunksmith-cli 0.4.0__py3-none-any.whl

chunksmith_cli/pipelines/multi_indexing_prompts.py

@@ -0,0 +1,375 @@
+"""Prompts for the unified multi-indexing CLI wizard (JSON + TOON, MVL/notebook parity)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.prompt import Confirm, Prompt
+
+from chunksmith_cli.core.paths import cli_runs_dir, normalize_path_string, resolve_pdf_candidate
+from chunksmith_cli.partition_prefs import PdfPartitionPreferences
+
+
+def prompt_element_source(console: Console) -> tuple[str, bool]:
+    """
+    Returns ``(mode, partition)`` where ``mode`` is ``json`` | ``partition``.
+
+    Multi-indexing packages use Unstructured **API** only (no local partition).
+    """
+    console.print(
+        "\n[bold cyan]Step 2 — Elements[/bold cyan]\n"
+        "  [cyan]1[/cyan] — Load existing [bold]Unstructured JSON[/bold] (array of elements)\n"
+        "  [cyan]2[/cyan] — [bold]Partition PDF via Unstructured API[/bold] "
+        "[dim](``UNSTRUCTURED_API_KEY`` in ``.env``)[/dim]\n"
+    )
+    src = Prompt.ask("Element source", choices=["1", "2"], default="2", show_choices=True)
+    if src == "1":
+        return "json", False
+    return "partition", True
+
+
+def prompt_unstructured_ocr_language(console: Console, *, default: str = "eng") -> str:
+    console.print(
+        "\n[bold]OCR / partition language[/bold]\n"
+        "  [dim]Unstructured ``languages`` (e.g. eng, deu, spa). Comma-separated for multiple.[/dim]\n"
+    )
+    raw = Prompt.ask("[bold]Language code(s)[/bold]", default=default).strip()
+    return raw or default
+
+
+def preflight_unstructured_api(console: Console, preflight_api_partition) -> bool:
+    """Run package preflight and print Rich-friendly errors."""
+    ok, msg = preflight_api_partition()
+    if ok:
+        console.print(f"[green]{msg}[/green]")
+        return True
+    console.print(f"[bold red]{msg}[/bold red]")
+    return False
+
+
+def prompt_partition_chunking(
+    console: Console, *, default_pages: int = 10, default_concurrent: int = 2
+) -> tuple[int, int]:
+    console.print(
+        "\n[bold]Partition chunking[/bold]\n"
+        "  [dim]``pages_per_chunk``: pages per API request (default 10). Use [bold]0[/bold] for one full-PDF call.[/dim]\n"
+        "  [dim]``max_concurrent``: parallel chunk requests (default 2).[/dim]\n"
+    )
+    ppc_raw = Prompt.ask("Pages per chunk", default=str(default_pages)).strip()
+    mc_raw = Prompt.ask("Max concurrent chunks", default=str(default_concurrent)).strip()
+    try:
+        pages_per_chunk = int(ppc_raw)
+    except ValueError:
+        pages_per_chunk = default_pages
+    try:
+        max_concurrent = int(mc_raw)
+    except ValueError:
+        max_concurrent = default_concurrent
+    return max(0, pages_per_chunk), max(1, max_concurrent)
+
+
+def prompt_mapping_method(
+    console: Console,
+    *,
+    mapping_methods: frozenset[str],
+    use_group_by_title: bool,
+    add_anchor: bool,
+) -> str:
+    options = sorted(mapping_methods)
+    console.print("\n[bold]Mapper method[/bold] [dim](combined index layout)[/dim]\n")
+    for i, name in enumerate(options, start=1):
+        note = ""
+        if name == "group_indexing" and not use_group_by_title:
+            note = " [red](requires group-by-title)[/red]"
+        if name == "anchor_indexing" and not add_anchor:
+            note = " [red](requires add_anchor)[/red]"
+        console.print(f"  [cyan]{i}[/cyan] — [bold]{name}[/bold]{note}")
+    default = "group_indexing" if use_group_by_title and "group_indexing" in mapping_methods else options[0]
+    default_idx = str(options.index(default) + 1) if default in options else "1"
+    choice = Prompt.ask("Mapping method", choices=[str(i) for i in range(1, len(options) + 1)], default=default_idx)
+    return options[int(choice) - 1]
+
+
+def prompt_group_by_title_prefs(
+    console: Console,
+    GroupByTitlePrefs: type,
+    default_factory,
+    prefs: PdfPartitionPreferences,
+) -> object:
+    """Chunking limits for ``group_elements_by_title`` (also updates ``prefs``)."""
+    d = default_factory()
+    console.print(
+        "\n[bold cyan]Group-by-title chunking[/bold cyan]\n"
+        "[dim]Controls how Unstructured elements are merged into ``TitleChunk`` sections.[/dim]\n"
+    )
+    max_characters = int(
+        Prompt.ask("[bold]max_characters[/bold] per chunk", default=str(d.max_characters)).strip()
+        or str(d.max_characters)
+    )
+    new_after = int(
+        Prompt.ask("[bold]new_after_n_chars[/bold]", default=str(d.new_after_n_chars)).strip()
+        or str(d.new_after_n_chars)
+    )
+    combine_under = int(
+        Prompt.ask(
+            "[bold]combine_text_under_n_chars[/bold]",
+            default=str(d.combine_text_under_n_chars),
+        ).strip()
+        or str(d.combine_text_under_n_chars)
+    )
+    multipage = Confirm.ask("[bold]multipage_sections[/bold]", default=bool(d.multipage_sections))
+    prefs.max_characters = max_characters
+    prefs.new_after_n_chars = new_after
+    prefs.combine_text_under_n_chars = combine_under
+    prefs.chunksmith_group_multipage_sections = multipage
+    return GroupByTitlePrefs(
+        max_characters=max_characters,
+        new_after_n_chars=new_after,
+        combine_text_under_n_chars=combine_under,
+        multipage_sections=multipage,
+    )
+
+
+_ELEMENT_XML_PRESETS: dict[str, frozenset[str]] = {
+    "all": frozenset(
+        (
+            "FigureCaption",
+            "Footer",
+            "Formula",
+            "Header",
+            "Image",
+            "ListItem",
+            "NarrativeText",
+            "Table",
+            "Text",
+            "Title",
+        )
+    ),
+    "core": frozenset(("Title", "NarrativeText", "Text", "ListItem", "Table", "Image", "Header", "Footer")),
+    "minimal": frozenset(("Title", "NarrativeText", "Table", "Image")),
+    "none": frozenset(),
+}
+
+
+def _element_xml_from_preset(
+    element_xml_types: tuple[str, ...],
+    preset: str,
+) -> dict[str, bool]:
+    if preset == "all":
+        return dict.fromkeys(element_xml_types, True)
+    enabled = _ELEMENT_XML_PRESETS.get(preset, frozenset())
+    return {t: (t in enabled) for t in element_xml_types}
+
+
+def _prompt_element_xml_per_type(
+    console: Console,
+    element_xml_types: tuple[str, ...],
+    defaults: dict[str, bool],
+) -> dict[str, bool]:
+    """Yes/no for each canonical element type."""
+    console.print(
+        "\n[bold]Per-type XML wrappers[/bold]\n"
+        "[dim]``y`` = emit ``<Type>…</Type>`` around that element; "
+        "``n`` = include text without a type tag.[/dim]\n"
+    )
+    element_xml: dict[str, bool] = {}
+    for i, name in enumerate(element_xml_types, start=1):
+        default_on = bool(defaults.get(name, False))
+        element_xml[name] = Confirm.ask(
+            f"  [cyan]{i:2d}[/cyan] [bold]{name}[/bold]",
+            default=default_on,
+        )
+    enabled = [t for t, on in element_xml.items() if on]
+    console.print(
+        f"\n[dim]Enabled ({len(enabled)}/{len(element_xml_types)}):[/dim] "
+        + (", ".join(enabled) if enabled else "(none)")
+    )
+    return element_xml
+
+
+def prompt_coded_formate_options(
+    console: Console,
+    CodedFormateOptions: type,
+    default_factory,
+    element_xml_types: tuple[str, ...],
+    *,
+    use_group_by_title: bool,
+) -> tuple[object, str, dict[str, bool] | None]:
+    """XML wrapper toggles for ``title_chunks_to_coded_formate`` / ``elements_to_coded_formate``."""
+    defaults = default_factory()
+    default_map = dict(defaults.element_xml)
+    console.print(
+        "\n[bold cyan]Step — Coded format (markup)[/bold cyan]\n"
+        "[dim]Builds the string sent to the page-index LLM. "
+        "Saved after the run as[/dim] "
+        "[cyan]text/{stem}_{stamp}_title_coded_formate.txt[/cyan]\n"
+    )
+    add_page_xml = Confirm.ask(
+        "[bold]Page wrappers[/bold] [dim](``<Page_P_Start>`` … ``<Page_P_End>``)[/dim]",
+        default=bool(defaults.add_page_xml),
+    )
+    add_group_xml = bool(defaults.add_group_by_title_xml)
+    if use_group_by_title:
+        add_group_xml = Confirm.ask(
+            "[bold]Grouped-title wrappers[/bold] [dim](``<Grouped_Title_k>``)[/dim]",
+            default=bool(defaults.add_group_by_title_xml),
+        )
+
+    console.print(
+        "\n[bold]Element XML wrappers[/bold] [dim](which Unstructured types get tags)[/dim]\n"
+        "  [cyan]1[/cyan] — All types on\n"
+        "  [cyan]2[/cyan] — Core (Title, NarrativeText, Text, ListItem, Table, Image, Header, Footer)\n"
+        "  [cyan]3[/cyan] — Minimal (Title, NarrativeText, Table, Image)\n"
+        "  [cyan]4[/cyan] — None (no per-element tags)\n"
+        "  [cyan]5[/cyan] — Customize each type (y/n per line)\n"
+        "  [cyan]6[/cyan] — Keep package / ``.env`` defaults\n"
+    )
+    default_all_on = all(default_map.get(t, False) for t in element_xml_types)
+    default_choice = "1" if default_all_on else "6"
+    if not default_all_on and any(default_map.get(t) for t in element_xml_types):
+        default_choice = "6"
+    mode = Prompt.ask(
+        "Element XML mode",
+        choices=["1", "2", "3", "4", "5", "6"],
+        default=default_choice,
+        show_choices=True,
+    )
+    xml_mode = "all"
+    xml_custom: dict[str, bool] | None = None
+    if mode == "1":
+        element_xml = _element_xml_from_preset(element_xml_types, "all")
+        xml_mode = "all"
+    elif mode == "2":
+        element_xml = _element_xml_from_preset(element_xml_types, "core")
+        xml_mode = "core"
+    elif mode == "3":
+        element_xml = _element_xml_from_preset(element_xml_types, "minimal")
+        xml_mode = "minimal"
+    elif mode == "4":
+        element_xml = _element_xml_from_preset(element_xml_types, "none")
+        xml_mode = "none"
+    elif mode == "5":
+        element_xml = _prompt_element_xml_per_type(console, element_xml_types, default_map)
+        xml_mode = "custom"
+        xml_custom = dict(element_xml)
+    else:
+        element_xml = {t: bool(default_map.get(t, False)) for t in element_xml_types}
+        xml_mode = "custom"
+        xml_custom = dict(element_xml)
+
+    enabled = [t for t in element_xml_types if element_xml.get(t)]
+    console.print(f"[dim]Selected tags:[/dim] {', '.join(enabled) if enabled else '(none)'}")
+    coded = CodedFormateOptions(
+        add_page_xml=add_page_xml,
+        add_group_by_title_xml=add_group_xml,
+        element_xml=element_xml,
+    )
+    return coded, xml_mode, xml_custom
+
+
+def prompt_partition_prefs_base(console: Console) -> PdfPartitionPreferences:
+    """Notebook/MVL defaults for partition + group-by-title limits."""
+    return PdfPartitionPreferences()
+
+
+def prompt_partition_api_settings(console: Console, prefs: PdfPartitionPreferences) -> None:
+    prefs.languages = prompt_unstructured_ocr_language(console, default=prefs.languages)
+    prefs.extract_images = Confirm.ask("Extract images from PDF?", default=prefs.extract_images)
+    prefs.extract_tables = Confirm.ask("Extract tables from PDF?", default=prefs.extract_tables)
+    pages_per_chunk, max_concurrent = prompt_partition_chunking(
+        console,
+        default_pages=prefs.pages_per_chunk,
+        default_concurrent=prefs.max_concurrent,
+    )
+    prefs.pages_per_chunk = pages_per_chunk
+    prefs.max_concurrent = max_concurrent
+
+
+def apply_coded_prefs(
+    prefs: PdfPartitionPreferences,
+    coded: object,
+    xml_mode: str,
+    xml_custom: dict[str, bool] | None,
+) -> None:
+    prefs.chunksmith_coded_add_page_xml = bool(getattr(coded, "add_page_xml", True))
+    prefs.chunksmith_coded_add_group_by_title_xml = bool(getattr(coded, "add_group_by_title_xml", True))
+    prefs.chunksmith_coded_element_xml_mode = xml_mode
+    prefs.chunksmith_coded_element_xml_custom = xml_custom
+
+
+def apply_indexer_prefs(
+    prefs: PdfPartitionPreferences,
+    indexer_options: object,
+    *,
+    summarize_outline_nodes: bool | None = None,
+) -> None:
+    prefs.chunksmith_pageindex_add_anchor = bool(getattr(indexer_options, "add_anchor", False))
+    prefs.chunksmith_pageindex_use_embedded_pdf_toc = bool(getattr(indexer_options, "use_embedded_pdf_toc", True))
+    prefs.chunksmith_pageindex_off_llm_parsing = bool(getattr(indexer_options, "off_llm_parsing", False))
+    if prefs.chunksmith_probe_first_excerpt is None:
+        prefs.chunksmith_probe_first_excerpt = bool(getattr(indexer_options, "probe_first_excerpt", False))
+    if prefs.chunksmith_probe_merged_reflection is None:
+        prefs.chunksmith_probe_merged_reflection = bool(getattr(indexer_options, "probe_merged_reflection", False))
+    if summarize_outline_nodes is not None:
+        prefs.summarize_outline_nodes = summarize_outline_nodes
+        prefs.chunksmith_pageindex_add_outline_summaries = bool(getattr(indexer_options, "add_summary", True))
+    gen = getattr(indexer_options, "generate_doc_summary", None)
+    if gen is not None:
+        prefs.chunksmith_pageindex_generate_doc_summary = bool(gen)
+
+
+def prompt_indexer_options(console: Console, IndexerOptions: type, default_factory) -> object:
+    """Yes/no prompts for each IndexerOptions field (defaults from config + env)."""
+    defaults = default_factory()
+    console.print(
+        "\n[bold cyan]Step — Page index (LLM) options[/bold cyan]\n"
+        "[dim]Model and token limits come from ``.env`` (``PAGEINDEX_MODEL``, Azure vars, etc.).[/dim]\n"
+    )
+
+    def _bool(label: str, attr: str) -> bool:
+        current = getattr(defaults, attr)
+        return Confirm.ask(f"{label}", default=bool(current))
+
+    return IndexerOptions(
+        add_summary=_bool("Add per-section summaries", "add_summary"),
+        add_anchor=_bool("Add anchor tags in outline", "add_anchor"),
+        generate_doc_summary=_bool("Generate document description", "generate_doc_summary"),
+        use_embedded_pdf_toc=_bool("Use embedded PDF table of contents", "use_embedded_pdf_toc"),
+        off_llm_parsing=_bool("TOC-only (skip LLM outline parsing)", "off_llm_parsing"),
+        probe_first_excerpt=_bool("Probe first excerpt (extra LLM call)", "probe_first_excerpt"),
+        probe_merged_reflection=_bool("Probe merged-outline reflection", "probe_merged_reflection"),
+    )
+
+
+def prompt_artifact_root(console: Console, pdf_path: Path) -> Path | None:
+    console.print(
+        "\n[bold]Artifact folder[/bold]\n"
+        "  [dim]Optional run folder under ``cli/data/runs/{pdf-stem}/`` "
+        "(json/, text/, etc.). Enter = save flat under ``cli/data/legacy`` only.[/dim]\n"
+    )
+    raw = Prompt.ask(
+        "Artifact root [dim](Enter for legacy flat save)[/dim]",
+        default="",
+        show_default=False,
+    ).strip()
+    if not raw:
+        return None
+    p = resolve_pdf_candidate(normalize_path_string(raw))
+    if p.is_dir():
+        return p.resolve()
+    if not p.is_absolute():
+        alt = (Path.cwd() / p).resolve()
+        if alt.is_dir():
+            return alt
+    p.mkdir(parents=True, exist_ok=True)
+    return p.resolve()
+
+
+def prompt_runs_artifact_default(console: Console, pdf_path: Path) -> Path:
+    root = cli_runs_dir() / pdf_path.stem
+    root.mkdir(parents=True, exist_ok=True)
+    console.print(f"[dim]Default artifact root:[/dim] [cyan]{root}[/cyan]")
+    if Confirm.ask("Use this folder for this run?", default=True):
+        return root.resolve()
+    return prompt_artifact_root(console, pdf_path) or root.resolve()

chunksmith_cli/pipelines/multi_indexing_runtime.py

@@ -0,0 +1,38 @@
+"""PyPI library bindings for the multi-indexing CLI wizard."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from chunksmith_multimodal import MAPPING_METHODS, IndexerOptions, run_multi_indexing_with_preferences
+from chunksmith_multimodal.coded_formate import CodedFormateOptions, ELEMENT_XML_TYPES
+from chunksmith_multimodal.config.config import (
+    default_coded_formate_options,
+    default_group_by_title_prefs,
+    default_indexer_options,
+)
+from chunksmith_multimodal.helpers import GroupByTitlePrefs
+from chunksmith_multimodal.unstructured import preflight_api_partition
+
+Encoding = Literal["json", "toon"]
+
+
+@dataclass(frozen=True)
+class MultiIndexingModules:
+    encoding: Encoding
+    package: str = "chunksmith_multimodal"
+    IndexerOptions: type = IndexerOptions
+    default_indexer_options: Any = default_indexer_options
+    default_coded_formate_options: Any = default_coded_formate_options
+    default_group_by_title_prefs: Any = default_group_by_title_prefs
+    CodedFormateOptions: type = CodedFormateOptions
+    GroupByTitlePrefs: type = GroupByTitlePrefs
+    ELEMENT_XML_TYPES: tuple[str, ...] = ELEMENT_XML_TYPES
+    preflight_api_partition: Any = preflight_api_partition
+    MAPPING_METHODS: frozenset[str] = frozenset(MAPPING_METHODS)
+    run_multi_indexing_with_preferences: Any = run_multi_indexing_with_preferences
+
+
+def load_multi_indexing(encoding: Encoding) -> MultiIndexingModules:
+    return MultiIndexingModules(encoding=encoding)

chunksmith_cli/pipelines/multi_indexing_storage.py

@@ -0,0 +1,157 @@
+"""Persist pickle, PNG, TOON, and slim JSON for multi-indexing CLI runs."""
+
+from __future__ import annotations
+
+import base64
+import copy
+import json
+import pickle
+from pathlib import Path
+from typing import Any
+
+from chunksmith_cli.core.artifact_layout import ArtifactLayout, ensure_artifact_layout
+from chunksmith_cli.core.media_preview import export_media_images_to_folder
+
+
+def _element_image_base64(el: dict[str, Any]) -> str | None:
+    md = el.get("metadata")
+    if isinstance(md, dict) and isinstance(md.get("image_base64"), str):
+        return md["image_base64"]
+    b64 = el.get("image_base64")
+    return b64 if isinstance(b64, str) else None
+
+
+def export_element_images_to_folder(
+    elements: list[dict[str, Any]],
+    dest_dir: Path,
+    *,
+    max_files: int = 10_000,
+) -> list[Path]:
+    """Write ``elem_{i}__p{page}__img0.png`` from Unstructured ``image_base64`` fields."""
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for i, el in enumerate(elements):
+        if len(written) >= max_files:
+            break
+        if not isinstance(el, dict):
+            continue
+        b64 = _element_image_base64(el)
+        if not b64 or not b64.strip():
+            continue
+        try:
+            raw = base64.b64decode(b64, validate=False)
+        except Exception:
+            continue
+        md = el.get("metadata") if isinstance(el.get("metadata"), dict) else {}
+        page = md.get("page_number", el.get("page_number", 0))
+        try:
+            page_num = int(page) if page is not None else 0
+        except (TypeError, ValueError):
+            page_num = 0
+        out = dest_dir / f"elem_{i:04d}__p{page_num}__img0.png"
+        try:
+            out.write_bytes(raw)
+            written.append(out)
+        except OSError:
+            continue
+    return written
+
+
+def unstructured_json_without_base64(elements: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """JSON-safe element list with ``image_base64`` stripped (paths added when PNGs exist)."""
+    rows: list[dict[str, Any]] = []
+    for el in elements:
+        if not isinstance(el, dict):
+            continue
+        row = copy.deepcopy(el)
+        row.pop("image_base64", None)
+        md = row.get("metadata")
+        if isinstance(md, dict):
+            md = dict(md)
+            md.pop("image_base64", None)
+            row["metadata"] = md
+        rows.append(row)
+    return rows
+
+
+def save_raw_elements_pickle(elements: list[dict[str, Any]], path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("wb") as f:
+        pickle.dump(elements, f, protocol=pickle.HIGHEST_PROTOCOL)
+    return path.resolve()
+
+
+def save_toon_artifacts(
+    layout: ArtifactLayout,
+    *,
+    stamp: str,
+    title_outline: dict[str, Any],
+) -> dict[str, Path]:
+    """Write ``.toon`` files under ``text/`` when present on the outline dict."""
+    paths: dict[str, Path] = {}
+    flat = title_outline.get("flat_rows_toon")
+    if isinstance(flat, str) and flat.strip():
+        p = layout.text_dir / f"{layout.pdf_stem}_{stamp}_flat_rows.toon"
+        p.write_text(flat, encoding="utf-8")
+        paths["flat_rows_toon"] = p.resolve()
+    struct = title_outline.get("structure_toon")
+    if isinstance(struct, str) and struct.strip():
+        p = layout.text_dir / f"{layout.pdf_stem}_{stamp}_structure.toon"
+        p.write_text(struct, encoding="utf-8")
+        paths["structure_toon"] = p.resolve()
+    trace = title_outline.get("outline_thinking")
+    if isinstance(trace, dict):
+        llm_trace = trace.get("llm_toon_trace")
+        if isinstance(llm_trace, list) and llm_trace:
+            p = layout.text_dir / f"{layout.pdf_stem}_{stamp}_llm_toon_trace.json"
+            p.write_text(json.dumps(llm_trace, ensure_ascii=False, indent=2), encoding="utf-8")
+            paths["llm_toon_trace"] = p.resolve()
+    return paths
+
+
+def persist_multi_indexing_artifacts(
+    *,
+    artifact_root: Path,
+    pdf_stem: str,
+    stamp: str,
+    elements: list[dict[str, Any]] | None,
+    title_coded_formate: str | None,
+    title_outline: dict[str, Any] | None,
+    media_by_node: dict[str, Any] | None = None,
+) -> dict[str, Path]:
+    """
+    Write pickle, PNG, TOON, and coded text under ``artifact_root``.
+
+    JSON files are written by :func:`cli.core.paths.archive_multi_indexing_cli_outputs`.
+    """
+    layout = ensure_artifact_layout(artifact_root, pdf_stem)
+    paths: dict[str, Path] = {"artifact_root": layout.root}
+
+    if elements:
+        pkl = save_raw_elements_pickle(elements, layout.pickle_path(stamp=stamp))
+        paths["pickle"] = pkl
+        pngs = export_element_images_to_folder(elements, layout.image_dir)
+        if pngs:
+            paths["image_dir"] = layout.image_dir
+        slim = unstructured_json_without_base64(elements)
+        for i, row in enumerate(slim):
+            if i < len(pngs):
+                row["image_path"] = str(pngs[i].resolve())
+        uj = layout.unstructured_json_path(stamp=stamp)
+        uj.write_text(json.dumps(slim, ensure_ascii=False, indent=2), encoding="utf-8")
+        paths["unstructured_elements"] = uj.resolve()
+
+    if isinstance(title_coded_formate, str) and title_coded_formate.strip():
+        coded_path = layout.text_dir / f"{layout.pdf_stem}_{stamp}_title_coded_formate.txt"
+        coded_path.write_text(title_coded_formate, encoding="utf-8")
+        paths["title_coded_formate"] = coded_path.resolve()
+
+    if isinstance(title_outline, dict):
+        paths.update(save_toon_artifacts(layout, stamp=stamp, title_outline=title_outline))
+
+    if isinstance(media_by_node, dict) and media_by_node:
+        extra = export_media_images_to_folder(media_by_node, layout.image_dir, max_files=10_000)
+        if extra:
+            paths["image_dir"] = layout.image_dir
+
+    return paths