visual-parser 1.0.1__tar.gz → 2.0.0__tar.gz

{visual_parser-1.0.1 → visual_parser-2.0.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: visual-parser
-Version: 1.0.1
-Summary: Standalone Visual-RAG PDF Parser — text extraction + Vision-LLM figure descriptions → JSONL
-License: MIT
+Version: 2.0.0
+Summary: Standalone Visual-RAG PDF Parser - text extraction and Vision-LLM figure descriptions to JSONL
+License: Apache-2.0
 Project-URL: Homepage, https://github.com/SmartLabNuclear/RADIANT_LLM
 Project-URL: Repository, https://github.com/SmartLabNuclear/RADIANT_LLM
 Project-URL: Docker Hub, https://hub.docker.com/r/zev94/radiant-llm
@@ -11,7 +11,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Text Processing :: Markup
@@ -30,6 +30,8 @@ Requires-Dist: openai==1.78.1
 Requires-Dist: google-generativeai==0.8.5
 Requires-Dist: python-dotenv==1.1.0
 Requires-Dist: tqdm==4.67.1
+Requires-Dist: nltk>=3.8
+Requires-Dist: python-Levenshtein>=0.20
 Provides-Extra: ocr
 Requires-Dist: pytesseract==0.3.13; extra == "ocr"
 Provides-Extra: dev
@@ -71,7 +73,7 @@ Prebuilt images are on **[zev94/radiant-llm](https://hub.docker.com/r/zev94/radi
 
 | Tag | Description |
 |-----|-------------|
-| `visual-parser-1.0` | Pinned release |
+| `visual-parser-2.0` | Pinned release (v2.0) |
 | `visual-parser-latest` | Latest visual-parser build |
 
 ### 1) Install Docker
@@ -79,7 +81,7 @@ Prebuilt images are on **[zev94/radiant-llm](https://hub.docker.com/r/zev94/radi
 
 ### 2) Pull the image
 ```bash
-docker pull zev94/radiant-llm:visual-parser-1.0
+docker pull zev94/radiant-llm:visual-parser-2.0
 ```
 
 ### 3) Run (input + output on the same mounted folder)
@@ -87,7 +89,7 @@ Windows PowerShell:
 ```powershell
 docker run --rm --env-file .env `
   -v "C:\path\to\pdfs:/data" `
-  zev94/radiant-llm:visual-parser-1.0 `
+  zev94/radiant-llm:visual-parser-2.0 `
   --input-dir /data --output-dir /data
 ```
 
@@ -95,7 +97,7 @@ Linux / WSL:
 ```bash
 docker run --rm --env-file .env \
   -v "/path/to/pdfs:/data" \
-  zev94/radiant-llm:visual-parser-1.0 \
+  zev94/radiant-llm:visual-parser-2.0 \
   --input-dir /data --output-dir /data
 ```
 
@@ -105,7 +107,7 @@ Windows PowerShell:
 docker run --rm --env-file .env `
   -v "C:\path\to\pdfs:/data" `
   -v "C:\path\to\out:/out" `
-  zev94/radiant-llm:visual-parser-1.0 `
+  zev94/radiant-llm:visual-parser-2.0 `
   --input-dir /data --output-dir /out
 ```
 
@@ -122,7 +124,7 @@ Default vision model is **GPT-5.5** when using `--vision-provider gpt`. Override
 
 ```powershell
 docker run --rm --env-file .env -v "C:\path\to\pdfs:/data" `
-  zev94/radiant-llm:visual-parser-1.0 `
+  zev94/radiant-llm:visual-parser-2.0 `
   --input-dir /data --output-dir /data --vision-model gpt-5.4
 ```
 
@@ -138,7 +140,7 @@ python visual-parser.py --input-dir "C:\path\to\pdfs"
 After pulling the image, run:
 
 ```bash
-docker run --rm zev94/radiant-llm:visual-parser-1.0 --help
+docker run --rm zev94/radiant-llm:visual-parser-2.0 --help
 ```
 
 For copy-paste **Docker** examples (vision presets, text modes, workers, rebuild), see [`docker-usage-examples.md`](docker-usage-examples.md).

{visual_parser-1.0.1 → visual_parser-2.0.0}/README.md

@@ -32,7 +32,7 @@ Prebuilt images are on **[zev94/radiant-llm](https://hub.docker.com/r/zev94/radi
 
 | Tag | Description |
 |-----|-------------|
-| `visual-parser-1.0` | Pinned release |
+| `visual-parser-2.0` | Pinned release (v2.0) |
 | `visual-parser-latest` | Latest visual-parser build |
 
 ### 1) Install Docker
@@ -40,7 +40,7 @@ Prebuilt images are on **[zev94/radiant-llm](https://hub.docker.com/r/zev94/radi
 
 ### 2) Pull the image
 ```bash
-docker pull zev94/radiant-llm:visual-parser-1.0
+docker pull zev94/radiant-llm:visual-parser-2.0
 ```
 
 ### 3) Run (input + output on the same mounted folder)
@@ -48,7 +48,7 @@ Windows PowerShell:
 ```powershell
 docker run --rm --env-file .env `
   -v "C:\path\to\pdfs:/data" `
-  zev94/radiant-llm:visual-parser-1.0 `
+  zev94/radiant-llm:visual-parser-2.0 `
   --input-dir /data --output-dir /data
 ```
 
@@ -56,7 +56,7 @@ Linux / WSL:
 ```bash
 docker run --rm --env-file .env \
   -v "/path/to/pdfs:/data" \
-  zev94/radiant-llm:visual-parser-1.0 \
+  zev94/radiant-llm:visual-parser-2.0 \
   --input-dir /data --output-dir /data
 ```
 
@@ -66,7 +66,7 @@ Windows PowerShell:
 docker run --rm --env-file .env `
   -v "C:\path\to\pdfs:/data" `
   -v "C:\path\to\out:/out" `
-  zev94/radiant-llm:visual-parser-1.0 `
+  zev94/radiant-llm:visual-parser-2.0 `
   --input-dir /data --output-dir /out
 ```
 
@@ -83,7 +83,7 @@ Default vision model is **GPT-5.5** when using `--vision-provider gpt`. Override
 
 ```powershell
 docker run --rm --env-file .env -v "C:\path\to\pdfs:/data" `
-  zev94/radiant-llm:visual-parser-1.0 `
+  zev94/radiant-llm:visual-parser-2.0 `
   --input-dir /data --output-dir /data --vision-model gpt-5.4
 ```
 
@@ -99,7 +99,7 @@ python visual-parser.py --input-dir "C:\path\to\pdfs"
 After pulling the image, run:
 
 ```bash
-docker run --rm zev94/radiant-llm:visual-parser-1.0 --help
+docker run --rm zev94/radiant-llm:visual-parser-2.0 --help
 ```
 
 For copy-paste **Docker** examples (vision presets, text modes, workers, rebuild), see [`docker-usage-examples.md`](docker-usage-examples.md).

{visual_parser-1.0.1 → visual_parser-2.0.0}/pyproject.toml

@@ -1,14 +1,14 @@
 [build-system]
-requires      = ["setuptools>=61", "wheel"]
+requires = ["setuptools>=61", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name        = "visual-parser"
-version     = "1.0.1"
-description = "Standalone Visual-RAG PDF Parser — text extraction + Vision-LLM figure descriptions → JSONL"
-readme      = "README.md"
+name = "visual-parser"
+version = "2.0.0"
+description = "Standalone Visual-RAG PDF Parser - text extraction and Vision-LLM figure descriptions to JSONL"
+readme = "README.md"
 requires-python = ">=3.10"
-license     = { text = "MIT" }
+license = { text = "Apache-2.0" }
 
 keywords = [
     "pdf", "rag", "nougat", "vision-llm", "ocr",
@@ -20,7 +20,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
-    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Text Processing :: Markup",
@@ -40,16 +40,18 @@ dependencies = [
     "google-generativeai==0.8.5",
     "python-dotenv==1.1.0",
     "tqdm==4.67.1",
+    "nltk>=3.8",
+    "python-Levenshtein>=0.20",
 ]
 
 [project.optional-dependencies]
-ocr = ["pytesseract==0.3.13"]   # requires Tesseract binary installed separately
+ocr = ["pytesseract==0.3.13"]
 dev = ["pytest", "ruff", "mypy"]
 
 [project.urls]
-Homepage      = "https://github.com/SmartLabNuclear/RADIANT_LLM"
-Repository    = "https://github.com/SmartLabNuclear/RADIANT_LLM"
-"Docker Hub"  = "https://hub.docker.com/r/zev94/radiant-llm"
+Homepage = "https://github.com/SmartLabNuclear/RADIANT_LLM"
+Repository = "https://github.com/SmartLabNuclear/RADIANT_LLM"
+"Docker Hub" = "https://hub.docker.com/r/zev94/radiant-llm"
 
 [project.scripts]
 visual-parser = "visual_parser.cli_main:main"

{visual_parser-1.0.1 → visual_parser-2.0.0}/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__ = "1.0.1"
+__version__ = "2.0.0"

{visual_parser-1.0.1 → visual_parser-2.0.0}/visual_parser/cli.py

@@ -17,8 +17,8 @@ import sys
 USAGE_EXAMPLES = """
 Examples
 --------
-# Nougat (default) + GPT-5.5 vision
-python visual-parser.py --input-dir ./my_pdfs
+# Nougat (default) + GPT-5.4 vision
+python visual-parser.py --input-dir ./my_pdfs
 
 # Fast lightweight extraction + Gemini
 python visual-parser.py --input-dir ./my_pdfs \\
@@ -47,7 +47,7 @@ def _build_arg_parser() -> argparse.ArgumentParser:
             "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"
+            "  02_visuals_kb.jsonl  visual descriptions\n"
             "  03_metadata_kb.jsonl document metadata"
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -108,20 +108,20 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         choices=["gpt", "gemini"],
         default="gpt",
         help=(
-            "gpt    — OpenAI GPT-5.5  (set OPENAI_API_KEY in .env).\n"
-            "gemini — Google Gemini   (set GEMINI_API_KEY in .env)."
-        ),
-    )
+            "gpt    — OpenAI GPT-5.4  (set OPENAI_API_KEY in .env).\n"
+            "gemini — Google Gemini   (set GEMINI_API_KEY in .env)."
+        ),
+    )
     vision_group.add_argument(
         "--vision-model",
         default=None,
         metavar="MODEL_NAME",
-        help=(
-            "Vision model name. Omit to use the latest for each provider:\n"
-            "  gpt    → gpt-5.5            (also: gpt-5.4, gpt-5.3-chat-latest, gpt-5.2, gpt-5.1, gpt-5, gpt-4o, gpt-4.1)\n"
-            "  gemini → gemini-3-pro-preview (also: gemini-2.5-flash, gemini-1.5-pro)"
-        ),
-    )
+        help=(
+            "Vision model name. Omit to use the latest for each provider:\n"
+            "  gpt    → gpt-5.4            (also: gpt-5.5, gpt-5.3-chat-latest, gpt-5.2, gpt-5.1, gpt-5, gpt-4o, gpt-4.1)\n"
+            "  gemini → gemini-3-pro-preview (also: gemini-2.5-flash, gemini-1.5-pro)"
+        ),
+    )
     vision_group.add_argument(
         "--vision-detail",
         choices=["low", "high", "auto"],
@@ -134,17 +134,17 @@ def _build_arg_parser() -> argparse.ArgumentParser:
     )
     vision_group.add_argument(
         "--reasoning-effort",
-        choices=["minimal", "none", "low", "medium", "high", "xhigh"],
+        choices=["minimal", "none", "low", "medium", "high", "xhigh"],
         default="medium",
-        help=(
-            "Reasoning effort for GPT-5.x models (ignored for Gemini and older GPT).\n"
-            "  minimal/none — minimum reasoning, depending on model.\n"
-            "  low          — light reasoning.\n"
-            "  medium       — balanced (default).\n"
-            "  high         — deeper reasoning, slower.\n"
-            "  xhigh        — maximum depth (gpt-5.2, gpt-5.4, and gpt-5.5)."
-        ),
-    )
+        help=(
+            "Reasoning effort for GPT-5.x models (ignored for Gemini and older GPT).\n"
+            "  minimal/none — minimum reasoning, depending on model.\n"
+            "  low          — light reasoning.\n"
+            "  medium       — balanced (default).\n"
+            "  high         — deeper reasoning, slower.\n"
+            "  xhigh        — maximum depth (gpt-5.2, gpt-5.4, and gpt-5.5)."
+        ),
+    )
     vision_group.add_argument(
         "--metadata-pages",
         type=int,
@@ -173,6 +173,17 @@ def _build_arg_parser() -> argparse.ArgumentParser:
             "Use after changing prompts, chunking strategy, or switching models."
         ),
     )
+    misc_group.add_argument(
+        "--skip-text",
+        action="store_true",
+        help=(
+            "Skip text extraction (Step 1) and resume only the vision steps "
+            "(figure descriptions + metadata). Use when chunking already completed "
+            "but the run was interrupted mid-vision (e.g. API credit exhaustion). "
+            "PDFs already present in 02_visuals_kb.jsonl / 03_metadata_kb.jsonl "
+            "are skipped automatically — no duplicates."
+        ),
+    )
     misc_group.add_argument(
         "--log-level",
         choices=["DEBUG", "INFO", "WARNING", "ERROR"],
@@ -194,10 +205,10 @@ def main(argv=None) -> int:
     args   = parser.parse_args(argv)
 
     # Default vision model per provider when not explicitly set
-    if args.vision_model is None:
-        args.vision_model = (
-            "gpt-5.5" if args.vision_provider == "gpt" else "gemini-3-pro-preview"
-        )
+    if args.vision_model is None:
+        args.vision_model = (
+            "gpt-5.4" if args.vision_provider == "gpt" else "gemini-3-pro-preview"
+        )
 
     from visual_parser.config import ParserConfig
 
@@ -209,13 +220,14 @@ def main(argv=None) -> int:
         chunk_size            = args.chunk_size,
         chunk_overlap         = args.chunk_overlap,
         vision_provider       = args.vision_provider,
-        gpt_vision_model      = args.vision_model if args.vision_provider == "gpt"    else "gpt-5.5",
+        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-pro-preview",
         gpt_reasoning_effort  = args.reasoning_effort,
         vision_detail         = args.vision_detail,
         metadata_pages        = args.metadata_pages,
         max_workers           = args.max_workers,
         rebuild               = args.rebuild,
+        skip_text             = args.skip_text,
         log_level             = args.log_level,
     )
 

{visual_parser-1.0.1 → visual_parser-2.0.0}/visual_parser/cli_main.py

@@ -15,7 +15,7 @@ import sys
 USAGE_EXAMPLES = """
 Examples
 --------
-# Nougat (default) + GPT-5.5 vision
+# Nougat (default) + GPT-5.4 vision
 python visual-parser.py --input-dir ./my_pdfs
 
 # Fast lightweight extraction + Gemini
@@ -168,6 +168,17 @@ def _build_arg_parser() -> argparse.ArgumentParser:
             "Use after changing prompts, chunking strategy, or switching models."
         ),
     )
+    misc_group.add_argument(
+        "--skip-text",
+        action="store_true",
+        help=(
+            "Skip text extraction (Step 1) and resume only the vision steps "
+            "(figure descriptions + metadata). Use when chunking already completed "
+            "but the run was interrupted mid-vision (e.g. API credit exhaustion). "
+            "PDFs already present in 02_visuals_kb.jsonl / 03_metadata_kb.jsonl "
+            "are skipped automatically — no duplicates."
+        ),
+    )
     misc_group.add_argument(
         "--log-level",
         choices=["DEBUG", "INFO", "WARNING", "ERROR"],
@@ -206,6 +217,7 @@ def main(argv=None) -> int:
         metadata_pages=args.metadata_pages,
         max_workers=args.max_workers,
         rebuild=args.rebuild,
+        skip_text=args.skip_text,
         log_level=args.log_level,
     )
 

{visual_parser-1.0.1 → visual_parser-2.0.0}/visual_parser/config.py

@@ -121,6 +121,15 @@ class ParserConfig:
     rebuild: bool = False
     """If True, reprocess all PDFs even if already recorded in 04_processed_pdfs.txt."""
 
+    skip_text: bool = False
+    """
+    If True, skip text extraction (Step 1) entirely.
+    Use when chunking already completed but the vision steps (figures / metadata)
+    failed mid-run (e.g. API credit exhaustion).  All PDFs in input_dir are
+    re-queued for vision steps; PDFs already present in 02_visuals_kb.jsonl /
+    03_metadata_kb.jsonl are skipped automatically.
+    """
+
     log_level: str = "ERROR"
 
     # -------------------------------------------------------------------------
@@ -145,6 +154,7 @@ class ParserConfig:
             metadata_pages       = int(os.getenv("VISUAL_PARSER_METADATA_PAGES", "2")),
             max_workers          = int(os.getenv("VISUAL_PARSER_MAX_WORKERS", "4")),
             rebuild              = os.getenv("VISUAL_PARSER_REBUILD", "false").lower() == "true",
+            skip_text            = os.getenv("VISUAL_PARSER_SKIP_TEXT", "false").lower() == "true",
             log_level            = os.getenv("VISUAL_PARSER_LOG_LEVEL", "ERROR"),
         )
 

{visual_parser-1.0.1 → visual_parser-2.0.0}/visual_parser/figure_describer.py

@@ -8,7 +8,7 @@ function in PDFAnalyser.py.
 Output
 ------
 One record per figure (or per page that contains at least one figure) is
-appended to ``02_visuals_kb.jsonl`` in *output_dir*:
+appended to ``02_visuals_kb.jsonl`` in *output_dir*:
 
     {
         "source":        "myreport.pdf",
@@ -84,16 +84,16 @@ def describe_figures_for_new_pdfs(
     vision_detail: str = "low",
     raster_dpi: int = 200,
     figure_prompt: str = FIGURE_PROMPT,
-    reasoning_effort: Optional[str] = "medium",
-) -> None:
+    reasoning_effort: Optional[str] = "medium",
+) -> None:
     """
     For each PDF in *new_pdf_paths*, rasterise every page at *raster_dpi* DPI,
     call the Vision LLM page-by-page, parse the figure descriptions, and
-    append the results to ``02_visuals_kb.jsonl`` in *output_dir*.
+    append the results to ``02_visuals_kb.jsonl`` in *output_dir*.
 
     Args:
         new_pdf_paths:    Full paths of PDFs to describe.
-        output_dir:       Directory where ``02_visuals_kb.jsonl`` is written.
+        output_dir:       Directory where ``02_visuals_kb.jsonl`` is written.
         vision_provider:  ``'gpt'`` or ``'gemini'``.
         vision_api_key:   API key for the chosen provider.
         vision_model:     Vision model name string.
@@ -125,7 +125,7 @@ def describe_figures_for_new_pdfs(
 
     if not page_images:
         logger.info("No pages to describe (all PDFs failed to rasterise).")
-        return
+        return
 
     # -----------------------------------------------------------------------
     # Step 2 – Group page images by PDF name
@@ -135,16 +135,47 @@ def describe_figures_for_new_pdfs(
         pages_by_pdf[record["pdf"]].append(record)
 
     # -----------------------------------------------------------------------
-    # Step 3 – Call Vision LLM once per page
+    # Step 2.5 – Build set of (source, page) pairs already on disk so a
+    #            mid-run crash can be resumed at page granularity.
     # -----------------------------------------------------------------------
-    descriptions_by_page: Dict[tuple, List[str]] = {}
+    figures_path = os.path.join(output_dir, "02_visuals_kb.jsonl")
+    done_pages: set = set()
+    if os.path.exists(figures_path):
+        with open(figures_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", "")
+                    _pg  = _rec.get("page")
+                    if _src and _pg is not None:
+                        done_pages.add((_src, _pg))
+                except Exception:
+                    pass
+    if done_pages:
+        logger.info(
+            "Resuming: %d page(s) already in 02_visuals_kb.jsonl — will skip.",
+            len(done_pages),
+        )
+
+    # -----------------------------------------------------------------------
+    # Step 3 – Call Vision LLM per page; flush each page to disk immediately.
+    #          Figure records are independent so per-page atomicity is safe.
+    # -----------------------------------------------------------------------
+    total_written = 0
 
     for pdf_name, image_records in pages_by_pdf.items():
-        per_pdf_count = 0
+        pdf_written = 0
 
         for record in image_records:
-            page_number  = record["page"]
-            image_bytes  = record["bytes"]
+            page_number = record["page"]
+            image_bytes = record["bytes"]
+
+            if (pdf_name, page_number) in done_pages:
+                logger.debug("Skipping %s page %d (already in KB).", pdf_name, page_number)
+                continue
 
             try:
                 raw_response = call_vision_llm(
@@ -159,8 +190,6 @@ def describe_figures_for_new_pdfs(
 
                 captions = _parse_llm_response(raw_response, pdf_name, page_number)
 
-                # Normalise: the model should return a list, but sometimes
-                # returns a single dict for single-figure pages.
                 if isinstance(captions, dict):
                     captions = [captions]
 
@@ -171,15 +200,27 @@ def describe_figures_for_new_pdfs(
                     )
                     continue
 
-                for caption in captions:
+                document_id = make_document_id(pdf_name)
+                page_rows: List[Dict] = []
+                for fig_idx, caption in enumerate(captions):
                     if not isinstance(caption, dict):
                         continue
                     description = caption.get("description")
                     if description is None:
                         continue
-                    key = (pdf_name, page_number)
-                    descriptions_by_page.setdefault(key, []).append(description)
-                    per_pdf_count += 1
+                    page_rows.append({
+                        "source":       pdf_name,
+                        "page":         page_number,
+                        "document_id":  document_id,
+                        "figure_index": fig_idx,
+                        "figure_id":    f"{document_id}:p{page_number}:f{fig_idx}",
+                        "description":  description,
+                    })
+
+                if page_rows:
+                    append_to_jsonl(figures_path, page_rows)
+                    pdf_written   += len(page_rows)
+                    total_written += len(page_rows)
 
             except Exception as exc:
                 logger.error(
@@ -187,32 +228,12 @@ def describe_figures_for_new_pdfs(
                     pdf_name, page_number, exc,
                 )
 
-        logger.info("[FIGURES] %s: %d figure(s) extracted.", pdf_name, per_pdf_count)
-
-    total = sum(len(v) for v in descriptions_by_page.values())
-    logger.info("Total figures captured: %d across %d PDF(s).", total,
-                len({k[0] for k in descriptions_by_page}))
+        if pdf_written:
+            logger.info("[FIGURES] %s: %d figure(s) written.", pdf_name, pdf_written)
+        else:
+            logger.info("[FIGURES] %s: no new figures (all pages done or none detected).", pdf_name)
 
-    # -----------------------------------------------------------------------
-    # Step 4 – Write figure descriptions to 02_visuals_kb.jsonl
-    # -----------------------------------------------------------------------
-    figure_rows: List[Dict] = []
-
-    for (pdf_name, page_number), descriptions in descriptions_by_page.items():
-        document_id = make_document_id(pdf_name)
-        for fig_idx, description in enumerate(descriptions):
-            figure_rows.append({
-                "source":        pdf_name,
-                "page":          page_number,
-                "document_id":   document_id,
-                "figure_index":  fig_idx,
-                "figure_id":     f"{document_id}:p{page_number}:f{fig_idx}",
-                "description":   description,
-            })
-
-    if figure_rows:
-        figures_path = os.path.join(output_dir, "02_visuals_kb.jsonl")
-        append_to_jsonl(figures_path, figure_rows)
-        print(f"[FIGURES] Wrote {len(figure_rows)} figure record(s) to 02_visuals_kb.jsonl.")
+    if total_written:
+        print(f"[FIGURES] Wrote {total_written} figure record(s) to 02_visuals_kb.jsonl.")
     else:
-        logger.info("No figures detected — 02_visuals_kb.jsonl not updated.")
+        logger.info("No new figures written — all pages already processed or none detected.")