visual-parser 2.2.0__py3-none-any.whl → 2.2.2__py3-none-any.whl

visual_parser/__init__.py

@@ -17,4 +17,4 @@ from visual_parser.config import ParserConfig
 from visual_parser.pipeline import run_pipeline
 
 __all__ = ["ParserConfig", "run_pipeline"]
-__version__ = "2.2.0"
+__version__ = "2.2.2"

visual_parser/cli.py

@@ -44,11 +44,13 @@ def _build_arg_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog="visual-parser",
         description=(
-            "Visual-RAG PDF Parser — detects new PDFs, extracts text and "
-            "figure descriptions, and writes three JSONL knowledge bases:\n"
-            "  01_chunks_kb.jsonl   text chunks\n"
-            "  02_visuals_kb.jsonl  visual descriptions\n"
-            "  03_metadata_kb.jsonl document metadata"
+            "Visual-RAG PDF Parser — detects new PDFs and standalone images, "
+            "extracts text and figure/image descriptions, and writes JSONL "
+            "knowledge bases:\n"
+            "  01_chunks_kb.jsonl       text chunks\n"
+            "  02_visuals_kb.jsonl      PDF figure descriptions\n"
+            "  03_metadata_kb.jsonl     document metadata\n"
+            "  image_descriptions.jsonl standalone image descriptions"
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=USAGE_EXAMPLES,
@@ -67,8 +69,9 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         "--input-dir", "-i",
         required=False,
         metavar="DIR",
-        help="Directory to scan for PDF files (searched recursively). "
-             "Required unless --list-models is given.",
+        help="Directory to scan for PDF files and standalone images "
+             "(searched recursively, auto-detected by extension -- a single "
+             "directory may mix both). Required unless --list-models is given.",
     )
     io_group.add_argument(
         "--output-dir", "-o",
@@ -108,6 +111,15 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         metavar="N",
         help="Overlap characters between adjacent chunks (default: 100).",
     )
+    text_group.add_argument(
+        "--nougat-crop-margin",
+        action="store_true",
+        help=(
+            "Let Nougat autocrop whitespace margins (its own default). "
+            "Off by default -- autocropping can silently crop into real "
+            "content on unusual page layouts."
+        ),
+    )
 
     # ---- Vision LLM ---------------------------------------------------------
     vision_group = p.add_argument_group("Vision LLM (figure descriptions & metadata)")
@@ -204,8 +216,22 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         "--rebuild",
         action="store_true",
         help=(
-            "Reprocess ALL PDFs, ignoring the 04_processed_pdfs.txt registry. "
-            "Use after changing prompts, chunking strategy, or switching models."
+            "Clear and reprocess every PDF/image currently in --input-dir. "
+            "Use after changing prompts, chunking strategy, or switching models. "
+            "No duplicate rows -- old entries are removed before reprocessing."
+        ),
+    )
+    misc_group.add_argument(
+        "--redo",
+        action="append",
+        default=None,
+        metavar="NAME",
+        help=(
+            "Clear ALL existing KB rows and registry entries for this PDF or "
+            "image basename (case-sensitive, path-stripped), then let normal "
+            "discovery reprocess it in this same run -- no duplicates. "
+            "Repeatable: --redo doc1.pdf --redo diagram2.png. Combine with "
+            "--rebuild to clear+reprocess everything in --input-dir instead."
         ),
     )
     misc_group.add_argument(
@@ -226,6 +252,19 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         help="Verbosity level written to 05_pipeline.log (default: ERROR).",
     )
 
+    # ---- Image processing ----------------------------------------------------
+    image_group = p.add_argument_group("Image processing")
+    image_group.add_argument(
+        "--skip-images",
+        action="store_true",
+        help=(
+            "Skip standalone-image processing entirely, even if image files "
+            "(.png/.jpg/.jpeg/.tif/.tiff/.bmp) are found in --input-dir. "
+            "Reuses --vision-provider/--vision-model/--vision-detail/"
+            "--reasoning-effort/--max-workers -- no separate image vision flags."
+        ),
+    )
+
     return p
 
 
@@ -336,6 +375,7 @@ def main(argv=None) -> int:
         nougat_model          = args.nougat_model,
         chunk_size            = args.chunk_size,
         chunk_overlap         = args.chunk_overlap,
+        nougat_crop_margin    = args.nougat_crop_margin,
         vision_provider       = args.vision_provider,
         gpt_vision_model      = args.vision_model if args.vision_provider == "gpt"    else "gpt-5.4",
         gemini_vision_model   = args.vision_model if args.vision_provider == "gemini" else "gemini-3.8-flash",
@@ -346,7 +386,9 @@ def main(argv=None) -> int:
         vision_context_pages  = args.vision_context_pages,
         max_workers           = args.max_workers,
         rebuild               = args.rebuild,
+        redo_names            = args.redo or [],
         skip_text             = args.skip_text,
+        skip_images           = args.skip_images,
         log_level             = args.log_level,
     )
 

visual_parser/cli_main.py

@@ -42,11 +42,13 @@ def _build_arg_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="visual-parser",
         description=(
-            "Visual-RAG PDF Parser - detects new PDFs, extracts text and "
-            "figure descriptions, and writes three JSONL knowledge bases:\n"
-            "  01_chunks_kb.jsonl   text chunks\n"
-            "  02_visuals_kb.jsonl  visual descriptions\n"
-            "  03_metadata_kb.jsonl document metadata"
+            "Visual-RAG PDF Parser - detects new PDFs and standalone images, "
+            "extracts text and figure/image descriptions, and writes JSONL "
+            "knowledge bases:\n"
+            "  01_chunks_kb.jsonl       text chunks\n"
+            "  02_visuals_kb.jsonl      PDF figure descriptions\n"
+            "  03_metadata_kb.jsonl     document metadata\n"
+            "  image_descriptions.jsonl standalone image descriptions"
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=USAGE_EXAMPLES,
@@ -65,8 +67,9 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         "-i",
         required=False,
         metavar="DIR",
-        help="Directory to scan for PDF files (searched recursively). "
-             "Required unless --list-models is given.",
+        help="Directory to scan for PDF files and standalone images "
+             "(searched recursively, auto-detected by extension -- a single "
+             "directory may mix both). Required unless --list-models is given.",
     )
     io_group.add_argument(
         "--output-dir",
@@ -106,6 +109,15 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         metavar="N",
         help="Overlap characters between adjacent chunks (default: 100).",
     )
+    text_group.add_argument(
+        "--nougat-crop-margin",
+        action="store_true",
+        help=(
+            "Let Nougat autocrop whitespace margins (its own default). "
+            "Off by default -- autocropping can silently crop into real "
+            "content on unusual page layouts."
+        ),
+    )
 
     vision_group = parser.add_argument_group("Vision LLM (figure descriptions & metadata)")
     vision_group.add_argument(
@@ -174,6 +186,18 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         help="Number of front pages sent to the vision LLM for metadata extraction (default: 2).",
     )
 
+    image_group = parser.add_argument_group("Image processing")
+    image_group.add_argument(
+        "--skip-images",
+        action="store_true",
+        help=(
+            "Skip standalone-image processing entirely, even if image files "
+            "(.png/.jpg/.jpeg/.tif/.tiff/.bmp) are found in --input-dir. "
+            "Reuses --vision-provider/--vision-model/--vision-detail/"
+            "--reasoning-effort/--max-workers -- no separate image vision flags."
+        ),
+    )
+
     perf_group = parser.add_argument_group("Performance")
     perf_group.add_argument(
         "--max-workers",
@@ -199,8 +223,22 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         "--rebuild",
         action="store_true",
         help=(
-            "Reprocess ALL PDFs, ignoring the 04_processed_pdfs.txt registry. "
-            "Use after changing prompts, chunking strategy, or switching models."
+            "Clear and reprocess every PDF/image currently in --input-dir. "
+            "Use after changing prompts, chunking strategy, or switching models. "
+            "No duplicate rows -- old entries are removed before reprocessing."
+        ),
+    )
+    misc_group.add_argument(
+        "--redo",
+        action="append",
+        default=None,
+        metavar="NAME",
+        help=(
+            "Clear ALL existing KB rows and registry entries for this PDF or "
+            "image basename (case-sensitive, path-stripped), then let normal "
+            "discovery reprocess it in this same run -- no duplicates. "
+            "Repeatable: --redo doc1.pdf --redo diagram2.png. Combine with "
+            "--rebuild to clear+reprocess everything in --input-dir instead."
         ),
     )
     misc_group.add_argument(
@@ -253,6 +291,7 @@ def main(argv=None) -> int:
         nougat_model=args.nougat_model,
         chunk_size=args.chunk_size,
         chunk_overlap=args.chunk_overlap,
+        nougat_crop_margin=args.nougat_crop_margin,
         vision_provider=args.vision_provider,
         gpt_vision_model=args.vision_model if args.vision_provider == "gpt" else "gpt-5.4",
         gemini_vision_model=(
@@ -265,7 +304,9 @@ def main(argv=None) -> int:
         vision_context_pages=args.vision_context_pages,
         max_workers=args.max_workers,
         rebuild=args.rebuild,
+        redo_names=args.redo or [],
         skip_text=args.skip_text,
+        skip_images=args.skip_images,
         log_level=args.log_level,
     )
 

visual_parser/config.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 import os
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Literal, Optional
+from typing import List, Literal, Optional
 
 from dotenv import load_dotenv
 
@@ -79,6 +79,14 @@ class ParserConfig:
     nougat_model: str = "facebook/nougat-small"
     """HuggingFace model identifier for Nougat."""
 
+    nougat_crop_margin: bool = False
+    """
+    Passed through to Nougat's image processor as do_crop_margin. False
+    (default) matches this package's long-standing behavior -- autocropping
+    whitespace margins can silently crop into real content on unusual page
+    layouts. Set True to opt into Nougat's own autocrop behavior instead.
+    """
+
     chunk_size: int = 500
     """Target character count per text chunk."""
 
@@ -139,7 +147,23 @@ class ParserConfig:
 
     # --- Misc ----------------------------------------------------------------
     rebuild: bool = False
-    """If True, reprocess all PDFs even if already recorded in 04_processed_pdfs.txt."""
+    """
+    If True, clear and reprocess every PDF/image currently in input_dir,
+    regardless of the registries -- implemented via kb_redo.redo_entries()
+    (clear KB rows + registry entries first, then let normal discovery pick
+    everything back up as new), so this produces no duplicate rows.
+    """
+
+    redo_names: List[str] = field(default_factory=list)
+    """
+    PDF or image basenames (case-sensitive, path-stripped) to clear from
+    every KB JSONL file and both registries before this run's discovery
+    step, via kb_redo.redo_entries() -- so the normal pipeline naturally
+    reprocesses them cleanly in this same run, with no duplicate rows,
+    unlike blindly reprocessing over an already-populated KB. A name that's
+    no longer present in input_dir degrades gracefully to a clean removal
+    (nothing left to reprocess).
+    """
 
     skip_text: bool = False
     """
@@ -150,6 +174,14 @@ class ParserConfig:
     03_metadata_kb.jsonl are skipped automatically.
     """
 
+    skip_images: bool = False
+    """
+    If True, skip standalone-image processing entirely, even if image files
+    are found in input_dir. Mirrors skip_text's opt-out pattern -- an escape
+    hatch for existing PDF-only workflows that don't want stray image files
+    sitting in input_dir to suddenly start being processed.
+    """
+
     log_level: str = "ERROR"
 
     # -------------------------------------------------------------------------
@@ -162,6 +194,7 @@ class ParserConfig:
             output_dir           = os.getenv("VISUAL_PARSER_OUTPUT_DIR", ""),
             text_mode            = os.getenv("VISUAL_PARSER_TEXT_MODE", "nougat"),           # type: ignore[arg-type]
             nougat_model         = os.getenv("VISUAL_PARSER_NOUGAT_MODEL", "facebook/nougat-small"),
+            nougat_crop_margin   = os.getenv("VISUAL_PARSER_NOUGAT_CROP_MARGIN", "false").lower() == "true",
             chunk_size           = int(os.getenv("VISUAL_PARSER_CHUNK_SIZE", "500")),
             chunk_overlap        = int(os.getenv("VISUAL_PARSER_CHUNK_OVERLAP", "100")),
             vision_provider      = os.getenv("VISUAL_PARSER_VISION_PROVIDER", "gpt"),        # type: ignore[arg-type]
@@ -176,7 +209,9 @@ class ParserConfig:
             vision_context_pages = int(os.getenv("VISUAL_PARSER_VISION_CONTEXT_PAGES", "0")),
             max_workers          = int(os.getenv("VISUAL_PARSER_MAX_WORKERS", "4")),
             rebuild              = os.getenv("VISUAL_PARSER_REBUILD", "false").lower() == "true",
+            redo_names           = [n.strip() for n in os.getenv("VISUAL_PARSER_REDO_NAMES", "").split(",") if n.strip()],
             skip_text            = os.getenv("VISUAL_PARSER_SKIP_TEXT", "false").lower() == "true",
+            skip_images          = os.getenv("VISUAL_PARSER_SKIP_IMAGES", "false").lower() == "true",
             log_level            = os.getenv("VISUAL_PARSER_LOG_LEVEL", "ERROR"),
         )
 

visual_parser/figure_describer.py

@@ -117,6 +117,13 @@ def describe_figures_for_new_pdfs(
                           0 (default) reproduces the exact single-page
                           behavior this function had before this parameter
                           existed.
+
+    Always resumes from 02_visuals_kb.jsonl's existing content (page-level,
+    via the done_pages set below) -- callers that want a page redescribed
+    must first remove its existing row(s) (see kb_redo.redo_entries()) and
+    its basename from the processed-PDFs registry, then pass it in here as
+    if new; this function has no bypass of its own, so there is no path to
+    producing a duplicate row.
     """
     # -----------------------------------------------------------------------
     # Step 1 – Rasterise every page of every new PDF
@@ -249,7 +256,13 @@ def describe_figures_for_new_pdfs(
                 if not isinstance(caption, dict):
                     continue
                 description = caption.get("description")
-                if description is None:
+                if not isinstance(description, str):
+                    logger.warning(
+                        "Figure %d on %s page %d has a non-string 'description' "
+                        "(got %s) -- model likely returned a malformed/nested "
+                        "response; skipping.",
+                        fig_idx, pdf_name, page_number, type(description).__name__,
+                    )
                     continue
                 page_rows.append({
                     "source":       pdf_name,

visual_parser/image_describer.py

@@ -0,0 +1,329 @@
+"""
+image_describer.py — Send each standalone image to a Vision LLM for a
+                      holistic description, one call per image (no page
+                      rasterisation, no context window).
+
+Extracted-pattern sibling of figure_describer.py: same ThreadPoolExecutor +
+as_completed concurrency shape (worker only computes/returns; only the single-
+threaded completion loop calls append_to_jsonl), but for arbitrary user-
+supplied image files instead of PyMuPDF-rasterized PDF pages.
+
+Output
+------
+One record per image is appended to ``image_descriptions.jsonl`` in
+*output_dir*:
+
+    {
+        "source":      "diagram1.png",
+        "image_id":    "a1b2c3d4e5f6g7h8",
+        "title":       "Vertical Parabolic Gate Schematic",
+        "description": "**Subject:** ..."
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from io import BytesIO
+from typing import Any, Dict, List, Optional
+
+from PIL import Image
+
+from visual_parser.jsonl_writer import append_to_jsonl, make_document_id
+from visual_parser.prompts import IMAGE_DESCRIPTION_PROMPT
+from visual_parser.vision_llm import call_vision_llm
+
+logger = logging.getLogger(__name__)
+
+IMAGE_DESCRIPTIONS_FILE = "image_descriptions.jsonl"
+
+# Decoupled from figure_describer.py's context-window-scaled formula (10 min
+# for 1 image there): IMAGE_DESCRIPTION_PROMPT's "Verbatim Text Content"
+# requirement can demand much more generated output than FIGURE_PROMPT ever
+# needs, since it asks for full verbatim transcription rather than a bounded
+# structured description. Measured directly against this model/hardware: a
+# dense, text-heavy page took 594s (9.9 min) for a single, uncontended call --
+# real concurrent runs (multiple images via --max-workers) push slower still.
+# 900s (15 min) calibrated from that real baseline, not guessed.
+_OLLAMA_IMAGE_TIMEOUT_SECONDS = 900.0
+
+_SUBJECT_RE = re.compile(r"\*\*Subject:\*\*\s*(.*?)(?:\n|$)")
+
+
+# ---------------------------------------------------------------------------
+# JSON response parser
+# ---------------------------------------------------------------------------
+
+def _parse_single_image_response(raw: str, image_name: str) -> Optional[Dict]:
+    """
+    Parse the Vision LLM's single-JSON-object response for one image.
+
+    A sibling of figure_describer.py's _parse_llm_response: that function's
+    prose-recovery regex is list-shaped (looks for "[...]") and cannot
+    recover a bare "{...}" object wrapped in prose, which is the expected
+    shape here (one image always yields exactly one description, never a
+    list). Also defensively unwraps the inverse case -- a model that ignores
+    "NOT a list" and returns a single-element list anyway.
+    """
+    body = raw.strip()
+    for fence in ("```json", "```"):
+        body = body.replace(fence, "")
+
+    parsed: Any = None
+    try:
+        parsed = json.loads(body)
+    except json.JSONDecodeError:
+        # A regex (greedy or lazy) can't reliably find "the" {...} block: the
+        # prompt's own OUTPUT FORMAT section embeds a literal, syntactically
+        # valid example object, so a model that echoes it alongside its real
+        # answer produces two {...} blocks -- greedy spans both into one
+        # invalid blob, while lazy stops at the first literal '}' even if
+        # that's just a brace character sitting inside a string value (e.g.
+        # a description that quotes set notation like "{A, B, C}"). Properly
+        # JSON-aware: try decoding starting at each '{' in turn and take the
+        # first one that parses as valid JSON, which correctly treats braces
+        # inside quoted strings as plain characters, not structure.
+        decoder = json.JSONDecoder()
+        start = body.find("{")
+        while start != -1:
+            try:
+                parsed, _ = decoder.raw_decode(body, start)
+                break
+            except json.JSONDecodeError:
+                start = body.find("{", start + 1)
+
+    if isinstance(parsed, list) and len(parsed) == 1:
+        parsed = parsed[0]
+
+    if isinstance(parsed, dict):
+        return parsed
+
+    logger.warning("Could not parse JSON for image %s: %r", image_name, body[:200])
+    return None
+
+
+def _flatten_to_rgb(pil_image: Image.Image) -> Image.Image:
+    """
+    Convert *pil_image* to RGB, compositing any transparency onto a white
+    background first.
+
+    Image.convert("RGB") alone does NOT do this -- it just drops the alpha
+    channel and exposes whatever RGB values are stored underneath, which are
+    commonly zeroed by PNG encoders for fully-transparent pixels. A
+    transparent-background PNG (a very common export format for standalone
+    diagrams/logos/screenshots -- exactly this feature's target content)
+    would silently turn mostly/fully black with no exception or log, giving
+    the vision LLM a black image instead of a diagram on a light background.
+    """
+    has_alpha = pil_image.mode in ("RGBA", "LA") or (
+        pil_image.mode == "P" and "transparency" in pil_image.info
+    )
+    if not has_alpha:
+        return pil_image.convert("RGB")
+
+    rgba = pil_image.convert("RGBA")
+    background = Image.new("RGB", rgba.size, (255, 255, 255))
+    background.paste(rgba, mask=rgba.split()[-1])
+    return background
+
+
+def _derive_title(description: str) -> str:
+    """
+    Derive a concise title from *description*.
+
+    The prompt's heading 1 is always "**Subject:** [Title]" -- extract it
+    directly rather than truncating raw characters. Falls back to the first
+    sentence boundary, then a hard cut, if the model didn't follow the format.
+    """
+    match = _SUBJECT_RE.search(description)
+    if match:
+        subject = match.group(1).strip()
+        if subject:
+            return subject
+
+    sentence_end = description.find(". ")
+    if 0 < sentence_end <= 150:
+        return description[:sentence_end + 1].strip()
+
+    return description[:100].strip()
+
+
+# ---------------------------------------------------------------------------
+# Main function
+# ---------------------------------------------------------------------------
+
+def describe_images(
+    new_image_paths: List[str],
+    output_dir: str,
+    vision_provider: str,
+    vision_api_key: str,
+    vision_model: str,
+    vision_detail: str = "low",
+    image_prompt: str = IMAGE_DESCRIPTION_PROMPT,
+    reasoning_effort: Optional[str] = "medium",
+    max_workers: int = 4,
+) -> List[str]:
+    """
+    For each image in *new_image_paths*, call the Vision LLM once (no
+    context window -- a single standalone image per call), parse the
+    description, and append the result to ``image_descriptions.jsonl`` in
+    *output_dir*.
+
+    Returns the basenames actually written a row for -- NOT the full input
+    list. Unlike PyMuPDF-rasterized PDF pages (always well-formed), arbitrary
+    user-supplied image files can be corrupt, truncated, or unreadable, and a
+    failed vision call must not be marked as processed by the caller, or the
+    image would silently disappear from future find_new_images() output with
+    no row ever written.
+
+    Args:
+        new_image_paths:  Full paths of images to describe.
+        output_dir:       Directory where ``image_descriptions.jsonl`` is written.
+        vision_provider:  ``'gpt'``, ``'gemini'``, or ``'ollama'``.
+        vision_api_key:   API key for the chosen provider (unused for ollama).
+        vision_model:     Vision model name string.
+        vision_detail:    Image detail level (GPT/Ollama only).
+        image_prompt:     The instruction prompt sent with each image.
+        max_workers:      Thread-pool size for concurrent vision-LLM calls.
+
+    Always resumes from image_descriptions.jsonl's existing content (via the
+    done_images set below) -- callers that want an image redescribed must
+    first remove its existing row and its basename from the processed-
+    images registry (see kb_redo.redo_entries()), then pass it in here as if
+    new; this function has no bypass of its own, so there is no path to
+    producing a duplicate row.
+    """
+    descriptions_path = os.path.join(output_dir, IMAGE_DESCRIPTIONS_FILE)
+
+    # -------------------------------------------------------------------
+    # Build set of images already on disk (resume safety).
+    # -------------------------------------------------------------------
+    done_images: set = set()
+    if os.path.exists(descriptions_path):
+        with open(descriptions_path, encoding="utf-8") as _fh:
+            for _line in _fh:
+                _line = _line.strip()
+                if not _line:
+                    continue
+                try:
+                    _rec = json.loads(_line)
+                    _src = _rec.get("source", "")
+                    if _src:
+                        done_images.add(_src)
+                except Exception:
+                    pass
+    if done_images:
+        logger.info(
+            "Resuming: %d image(s) already in %s — will skip.",
+            len(done_images), IMAGE_DESCRIPTIONS_FILE,
+        )
+
+    tasks = [
+        {"path": path, "name": os.path.basename(path)}
+        for path in new_image_paths
+        if os.path.basename(path) not in done_images
+    ]
+
+    if not tasks:
+        logger.info("No new images to describe — all already processed.")
+        return []
+
+    # -------------------------------------------------------------------
+    # Call Vision LLM per task, concurrently. Each worker only computes
+    # and returns a result; only the single-threaded completion loop below
+    # calls append_to_jsonl, so the file is never written to from more
+    # than one thread at a time (writing it directly from workers would
+    # not be safe -- append_to_jsonl opens the file fresh per call).
+    # -------------------------------------------------------------------
+    def _describe_one(task: Dict[str, Any]) -> Dict[str, Any]:
+        image_name = task["name"]
+        try:
+            with open(task["path"], "rb") as fh:
+                raw_bytes = fh.read()
+            # Re-encode to PNG in memory, mirroring figure_describer.py's own
+            # pix.tobytes("png") step. Not cosmetic: OpenAI's vision API does
+            # not accept BMP or TIFF at all, regardless of what the data: URL
+            # claims, so a raw passthrough would fail outright for those.
+            pil_image = _flatten_to_rgb(Image.open(BytesIO(raw_bytes)))
+            buf = BytesIO()
+            pil_image.save(buf, format="PNG")
+            png_bytes = buf.getvalue()
+
+            raw_response = call_vision_llm(
+                images=[png_bytes],
+                prompt=image_prompt,
+                provider=vision_provider,
+                api_key=vision_api_key,
+                model=vision_model,
+                detail=vision_detail,
+                reasoning_effort=reasoning_effort,
+                ollama_timeout_seconds=_OLLAMA_IMAGE_TIMEOUT_SECONDS,
+            )
+
+            parsed = _parse_single_image_response(raw_response, image_name)
+            if parsed is None:
+                return {"image_name": image_name, "row": None}
+
+            description = parsed.get("description")
+            if not isinstance(description, str):
+                logger.warning(
+                    "'description' field for image %s is not a string (got %s) -- "
+                    "model likely returned a malformed/nested response; skipping.",
+                    image_name, type(description).__name__,
+                )
+                return {"image_name": image_name, "row": None}
+
+            row = {
+                "source":      image_name,
+                "image_id":    make_document_id(image_name),
+                "title":       _derive_title(description),
+                "description": description,
+            }
+            return {"image_name": image_name, "row": row}
+
+        except Exception as exc:
+            logger.error("Vision LLM failed for image %s: %s", image_name, exc)
+            return {"image_name": image_name, "row": None}
+
+    written_basenames: List[str] = []
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {executor.submit(_describe_one, task): task for task in tasks}
+        for future in as_completed(futures):
+            task = futures[future]
+            try:
+                result = future.result()
+            except Exception as exc:
+                logger.error("Error collecting result for image %s: %s", task["name"], exc)
+                continue
+
+            row = result["row"]
+            if row is not None:
+                # Only mark this basename "written" if the row actually
+                # landed on disk -- the caller uses this to persist
+                # parsed_images.txt, and unlike the PDF/figure side (which
+                # resumes by reading 02_visuals_kb.jsonl's own content back,
+                # self-healing after a transient write failure), the image
+                # registry is a separate file with no such self-correction.
+                # A silently-swallowed disk/permission error here previously
+                # still counted as "done" -- permanent data loss with no
+                # retry path short of --redo/--rebuild.
+                if append_to_jsonl(descriptions_path, [row]):
+                    written_basenames.append(result["image_name"])
+                else:
+                    logger.error(
+                        "Failed to write description for %s -- not marking processed, will retry next run.",
+                        result["image_name"],
+                    )
+
+    if written_basenames:
+        print(f"[IMAGES] Wrote {len(written_basenames)} image description(s) to {IMAGE_DESCRIPTIONS_FILE}.")
+    else:
+        logger.info("No new image descriptions written.")
+
+    return written_basenames