visual-parser 2.2.2__tar.gz → 2.2.4__tar.gz

{visual_parser-2.2.2/visual_parser.egg-info → visual_parser-2.2.4}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: visual-parser
-Version: 2.2.2
-Summary: Standalone Visual-RAG PDF Parser - text extraction and Vision-LLM figure descriptions to JSONL
+Version: 2.2.4
+Summary: Standalone Visual-RAG PDF & Image Parser - text extraction and Vision-LLM figure/image descriptions to JSONL
 Author: Zavier N. Ndum
 Author-email: zavier.ndum@tamu.edu
 License-Expression: 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
-Keywords: pdf,rag,nougat,vision-llm,ocr,document-parsing,jsonl,knowledge-base
+Keywords: pdf,image,rag,nougat,vision-llm,ocr,document-parsing,jsonl,knowledge-base
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -43,17 +43,17 @@ Requires-Dist: ruff; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Dynamic: license-file
 
-# visual-parser (Standalone Visual-RAG PDF Ingestion)
+# visual-parser (Standalone Visual-RAG PDF & Image Ingestion)
 
 ![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-brightgreen.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-2.1%2B-ee4c2c.svg)
 ![LangChain](https://img.shields.io/badge/LangChain-0.1%2B-1C3C3C.svg)
 ![CUDA](https://img.shields.io/badge/CUDA-optional-76B900.svg)
 
-`visual-parser` converts PDFs (and standalone images alongside them) into a multi-modal JSONL knowledge base (text chunks, figure descriptions, standalone image descriptions, metadata). It was extracted from [RADIANT-LLM](https://github.com/SmartLabNuclear/RADIANT_LLM) as a standalone PDF-ingestion tool, independent of any chatbot.
+`visual-parser` converts PDFs (and standalone images alongside them) into a multi-modal JSONL knowledge base (text chunks, figure descriptions, standalone image descriptions, metadata). It was extracted from [RADIANT-LLM](https://github.com/SmartLabNuclear/RADIANT_LLM) as a standalone PDF-and-image ingestion tool, independent of any chatbot.
 
-1) Run `visual-parser` on curated PDFs to generate JSONL KB files.
-2) Point any downstream RAG system at the generated KB — RADIANT-LLM, AutoSAM, and AutoFLUKA all consume the identical JSONL/registry format, so the same KB works with any of them without re-parsing.
+1) Run `visual-parser` on a directory of curated PDFs and/or standalone images to generate JSONL KB files.
+2) Point any downstream RAG system at the generated KB — [RADIANT-LLM](https://github.com/SmartLabNuclear/RADIANT_LLM), [AutoSAM](https://github.com/SmartLabNuclear/AutoSAM), and [AutoFLUKA](https://github.com/SmartLabNuclear/AutoFLUKA) all consume the identical JSONL/registry format, so the same KB works with any of them without re-parsing.
 
 ## Table of Contents
 
@@ -74,10 +74,14 @@ By default, the pipeline writes:
 - `01_chunks_kb.jsonl`: chunked text extracted from PDFs (Nougat by default).
 - `02_visuals_kb.jsonl`: figure/page visual descriptions (Vision LLM), one row per figure found in a PDF.
 - `03_metadata_kb.jsonl`: document metadata rows (title/author/etc.).
-- `image_descriptions.jsonl`: one holistic description per **standalone image** file found alongside your PDFs in `--input-dir` (not a PDF's own figures) — auto-detected by extension, no separate flag needed; disable with `--skip-images`.
+- `image_descriptions_kb.jsonl`: one holistic description per **standalone image** file found alongside your PDFs in `--input-dir` (not a PDF's own figures) — auto-detected by extension, no separate flag needed; disable with `--skip-images`.
 
 Alongside the KB, the pipeline also writes bookkeeping files: `04_processed_pdfs.txt` / `parsed_images.txt` (track which PDFs/images have already been processed, so re-runs skip them unless `--rebuild` or `--redo NAME`) and `05_pipeline.log` (run log at the verbosity set by `--log-level`, default `ERROR`).
 
+> **New in 2.2.4 (additive, no existing field or ID changed):** every `02_visuals_kb.jsonl` and `image_descriptions_kb.jsonl` row now carries `vision_provider`/`vision_model`, and every `03_metadata_kb.jsonl` row carries a `parser` block (`visual_parser` version, `parsed_at`, `text_engine`, `text_fallback`, the resolved `vision_model`, and the run's chunking/context settings) — recording which engine and model actually produced that document's rows, since the configured settings aren't always what ran (Nougat can fail and fall back to lightweight; a local Ollama model can be auto-selected at run time). Older rows simply lack these fields. Figure description also now actively guards against a mixed-model document: if a PDF already has figures described under a different `vision_model` than the current run's, its remaining pages are skipped entirely (not partially re-described under the new model) and its basename is reported back — reprocess it with `--redo NAME` to redescribe it consistently under the new model.
+
+> **Breaking change in 2.2.3:** the standalone-image KB file was renamed from `image_descriptions.jsonl` to `image_descriptions_kb.jsonl` (matching the `NN_name_kb.jsonl` convention used by the other three KB files). Upgrading from an older version does **not** migrate existing data automatically — the resume check only looks at the new filename, so already-described images in an old `image_descriptions.jsonl` would otherwise appear "new" again and get re-described. If you have existing data, rename the file yourself before re-running: `image_descriptions.jsonl` → `image_descriptions_kb.jsonl`.
+
 ## API Keys (.env)
 
 Provide at least one provider:

{visual_parser-2.2.2 → visual_parser-2.2.4}/README.md

@@ -1,14 +1,14 @@
-# visual-parser (Standalone Visual-RAG PDF Ingestion)
+# visual-parser (Standalone Visual-RAG PDF & Image Ingestion)
 
 ![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-brightgreen.svg)
 ![PyTorch](https://img.shields.io/badge/PyTorch-2.1%2B-ee4c2c.svg)
 ![LangChain](https://img.shields.io/badge/LangChain-0.1%2B-1C3C3C.svg)
 ![CUDA](https://img.shields.io/badge/CUDA-optional-76B900.svg)
 
-`visual-parser` converts PDFs (and standalone images alongside them) into a multi-modal JSONL knowledge base (text chunks, figure descriptions, standalone image descriptions, metadata). It was extracted from [RADIANT-LLM](https://github.com/SmartLabNuclear/RADIANT_LLM) as a standalone PDF-ingestion tool, independent of any chatbot.
+`visual-parser` converts PDFs (and standalone images alongside them) into a multi-modal JSONL knowledge base (text chunks, figure descriptions, standalone image descriptions, metadata). It was extracted from [RADIANT-LLM](https://github.com/SmartLabNuclear/RADIANT_LLM) as a standalone PDF-and-image ingestion tool, independent of any chatbot.
 
-1) Run `visual-parser` on curated PDFs to generate JSONL KB files.
-2) Point any downstream RAG system at the generated KB — RADIANT-LLM, AutoSAM, and AutoFLUKA all consume the identical JSONL/registry format, so the same KB works with any of them without re-parsing.
+1) Run `visual-parser` on a directory of curated PDFs and/or standalone images to generate JSONL KB files.
+2) Point any downstream RAG system at the generated KB — [RADIANT-LLM](https://github.com/SmartLabNuclear/RADIANT_LLM), [AutoSAM](https://github.com/SmartLabNuclear/AutoSAM), and [AutoFLUKA](https://github.com/SmartLabNuclear/AutoFLUKA) all consume the identical JSONL/registry format, so the same KB works with any of them without re-parsing.
 
 ## Table of Contents
 
@@ -29,10 +29,14 @@ By default, the pipeline writes:
 - `01_chunks_kb.jsonl`: chunked text extracted from PDFs (Nougat by default).
 - `02_visuals_kb.jsonl`: figure/page visual descriptions (Vision LLM), one row per figure found in a PDF.
 - `03_metadata_kb.jsonl`: document metadata rows (title/author/etc.).
-- `image_descriptions.jsonl`: one holistic description per **standalone image** file found alongside your PDFs in `--input-dir` (not a PDF's own figures) — auto-detected by extension, no separate flag needed; disable with `--skip-images`.
+- `image_descriptions_kb.jsonl`: one holistic description per **standalone image** file found alongside your PDFs in `--input-dir` (not a PDF's own figures) — auto-detected by extension, no separate flag needed; disable with `--skip-images`.
 
 Alongside the KB, the pipeline also writes bookkeeping files: `04_processed_pdfs.txt` / `parsed_images.txt` (track which PDFs/images have already been processed, so re-runs skip them unless `--rebuild` or `--redo NAME`) and `05_pipeline.log` (run log at the verbosity set by `--log-level`, default `ERROR`).
 
+> **New in 2.2.4 (additive, no existing field or ID changed):** every `02_visuals_kb.jsonl` and `image_descriptions_kb.jsonl` row now carries `vision_provider`/`vision_model`, and every `03_metadata_kb.jsonl` row carries a `parser` block (`visual_parser` version, `parsed_at`, `text_engine`, `text_fallback`, the resolved `vision_model`, and the run's chunking/context settings) — recording which engine and model actually produced that document's rows, since the configured settings aren't always what ran (Nougat can fail and fall back to lightweight; a local Ollama model can be auto-selected at run time). Older rows simply lack these fields. Figure description also now actively guards against a mixed-model document: if a PDF already has figures described under a different `vision_model` than the current run's, its remaining pages are skipped entirely (not partially re-described under the new model) and its basename is reported back — reprocess it with `--redo NAME` to redescribe it consistently under the new model.
+
+> **Breaking change in 2.2.3:** the standalone-image KB file was renamed from `image_descriptions.jsonl` to `image_descriptions_kb.jsonl` (matching the `NN_name_kb.jsonl` convention used by the other three KB files). Upgrading from an older version does **not** migrate existing data automatically — the resume check only looks at the new filename, so already-described images in an old `image_descriptions.jsonl` would otherwise appear "new" again and get re-described. If you have existing data, rename the file yourself before re-running: `image_descriptions.jsonl` → `image_descriptions_kb.jsonl`.
+
 ## API Keys (.env)
 
 Provide at least one provider:

{visual_parser-2.2.2 → visual_parser-2.2.4}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "visual-parser"
-version = "2.2.2"
-description = "Standalone Visual-RAG PDF Parser - text extraction and Vision-LLM figure descriptions to JSONL"
+version = "2.2.4"
+description = "Standalone Visual-RAG PDF & Image Parser - text extraction and Vision-LLM figure/image descriptions to JSONL"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "Apache-2.0"
@@ -17,7 +17,7 @@ authors = [
 ]
 
 keywords = [
-    "pdf", "rag", "nougat", "vision-llm", "ocr",
+    "pdf", "image", "rag", "nougat", "vision-llm", "ocr",
     "document-parsing", "jsonl", "knowledge-base",
 ]
 

{visual_parser-2.2.2 → visual_parser-2.2.4}/tests/test_figure_describer.py

@@ -201,3 +201,152 @@ def test_resume_skips_already_done_pages_under_concurrency(tmp_path, monkeypatch
     assert sorted(r["page"] for r in rows) == [1, 2, 3]
     descriptions_by_page = {r["page"]: r["description"] for r in rows}
     assert descriptions_by_page[2] == "already done"  # untouched, not re-described
+
+
+def test_rows_record_vision_provider_and_model(tmp_path):
+    pdf_path = _make_pdf(tmp_path / "doc.pdf", num_pages=1)
+
+    figure_describer.describe_figures_for_new_pdfs(
+        new_pdf_paths=[pdf_path],
+        output_dir=str(tmp_path),
+        vision_provider="gpt",
+        vision_api_key="sk-test",
+        vision_model="gpt-5.4",
+        max_workers=1,
+        context_pages=0,
+    )
+
+    rows = _read_jsonl(tmp_path / "02_visuals_kb.jsonl")
+    assert len(rows) == 1
+    assert rows[0]["vision_provider"] == "gpt"
+    assert rows[0]["vision_model"] == "gpt-5.4"
+
+
+def test_resume_with_different_vision_model_skips_document_not_mixed(tmp_path, monkeypatch):
+    """Regression test for active prevention: a document already has a page
+    described under one vision_model; resuming with a different one must not
+    silently mix the two under one document. The document is skipped in full
+    (not partially re-described) and its basename is reported back."""
+    figures_path = tmp_path / "02_visuals_kb.jsonl"
+    pdf_path = _make_pdf(tmp_path / "doc.pdf", num_pages=2)
+
+    figures_path.write_text(
+        json.dumps({
+            "source": "doc.pdf", "page": 1, "document_id": "x", "figure_index": 0,
+            "figure_id": "x:p1:f0", "description": "old",
+            "vision_provider": "gpt", "vision_model": "gpt-5.4",
+        }) + "\n",
+        encoding="utf-8",
+    )
+
+    called = []
+
+    def fake(images, prompt, provider, api_key, model, detail, reasoning_effort):
+        called.append(True)
+        return json.dumps([{"description": "new"}])
+
+    monkeypatch.setattr(figure_describer, "call_vision_llm", fake)
+
+    skipped = figure_describer.describe_figures_for_new_pdfs(
+        new_pdf_paths=[pdf_path],
+        output_dir=str(tmp_path),
+        vision_provider="gpt",
+        vision_api_key="sk-test",
+        vision_model="gpt-5.5",  # different from the existing row's gpt-5.4
+        max_workers=1,
+        context_pages=0,
+    )
+
+    assert skipped == ["doc.pdf"]
+    assert called == []  # page 2 was never even attempted
+    rows = _read_jsonl(figures_path)
+    assert len(rows) == 1  # only the original row -- nothing added, nothing mixed in
+    assert rows[0]["vision_model"] == "gpt-5.4"
+
+
+def test_resume_with_same_vision_model_proceeds_normally(tmp_path, monkeypatch):
+    figures_path = tmp_path / "02_visuals_kb.jsonl"
+    pdf_path = _make_pdf(tmp_path / "doc.pdf", num_pages=2)
+
+    figures_path.write_text(
+        json.dumps({
+            "source": "doc.pdf", "page": 1, "document_id": "x", "figure_index": 0,
+            "figure_id": "x:p1:f0", "description": "old",
+            "vision_provider": "gpt", "vision_model": "gpt-5.4",
+        }) + "\n",
+        encoding="utf-8",
+    )
+
+    skipped = figure_describer.describe_figures_for_new_pdfs(
+        new_pdf_paths=[pdf_path],
+        output_dir=str(tmp_path),
+        vision_provider="gpt",
+        vision_api_key="sk-test",
+        vision_model="gpt-5.4",  # same as the existing row
+        max_workers=1,
+        context_pages=0,
+    )
+
+    assert skipped == []
+    rows = _read_jsonl(figures_path)
+    assert sorted(r["page"] for r in rows) == [1, 2]
+
+
+def test_resume_with_no_recorded_model_does_not_block(tmp_path):
+    """Pre-upgrade rows have no vision_model field at all -- that must be
+    treated as unknown provenance, not a mismatch, per HANDOFF's
+    compatibility note that a missing block just means 'details unknown'."""
+    figures_path = tmp_path / "02_visuals_kb.jsonl"
+    pdf_path = _make_pdf(tmp_path / "doc.pdf", num_pages=2)
+
+    figures_path.write_text(
+        json.dumps({
+            "source": "doc.pdf", "page": 1, "document_id": "x", "figure_index": 0,
+            "figure_id": "x:p1:f0", "description": "old",
+        }) + "\n",
+        encoding="utf-8",
+    )
+
+    skipped = figure_describer.describe_figures_for_new_pdfs(
+        new_pdf_paths=[pdf_path],
+        output_dir=str(tmp_path),
+        vision_provider="gpt",
+        vision_api_key="sk-test",
+        vision_model="gpt-5.5",
+        max_workers=1,
+        context_pages=0,
+    )
+
+    assert skipped == []
+    rows = _read_jsonl(figures_path)
+    assert sorted(r["page"] for r in rows) == [1, 2]
+
+
+def test_mismatch_in_one_document_does_not_block_others(tmp_path):
+    figures_path = tmp_path / "02_visuals_kb.jsonl"
+    mismatched_pdf = _make_pdf(tmp_path / "mismatched.pdf", num_pages=1)
+    clean_pdf = _make_pdf(tmp_path / "clean.pdf", num_pages=1)
+
+    figures_path.write_text(
+        json.dumps({
+            "source": "mismatched.pdf", "page": 1, "document_id": "x", "figure_index": 0,
+            "figure_id": "x:p1:f0", "description": "old",
+            "vision_provider": "gpt", "vision_model": "gpt-5.4",
+        }) + "\n",
+        encoding="utf-8",
+    )
+
+    skipped = figure_describer.describe_figures_for_new_pdfs(
+        new_pdf_paths=[mismatched_pdf, clean_pdf],
+        output_dir=str(tmp_path),
+        vision_provider="gpt",
+        vision_api_key="sk-test",
+        vision_model="gpt-5.5",
+        max_workers=2,
+        context_pages=0,
+    )
+
+    assert skipped == ["mismatched.pdf"]
+    rows = _read_jsonl(figures_path)
+    sources_written = {r["source"] for r in rows if r.get("vision_model") == "gpt-5.5"}
+    assert sources_written == {"clean.pdf"}

{visual_parser-2.2.2 → visual_parser-2.2.4}/tests/test_image_describer.py

@@ -145,7 +145,7 @@ def test_describe_images_skips_non_string_description(tmp_path, monkeypatch):
     )
 
     assert written == []
-    assert _read_jsonl(tmp_path / "image_descriptions.jsonl") == []
+    assert _read_jsonl(tmp_path / image_describer.IMAGE_DESCRIPTIONS_FILE) == []
 
 
 def test_describe_images_writes_rows_for_each_image(tmp_path, monkeypatch):
@@ -166,11 +166,13 @@ def test_describe_images_writes_rows_for_each_image(tmp_path, monkeypatch):
     )
 
     assert set(written) == {"a.png", "b.png"}
-    rows = _read_jsonl(tmp_path / "image_descriptions.jsonl")
+    rows = _read_jsonl(tmp_path / image_describer.IMAGE_DESCRIPTIONS_FILE)
     assert {r["source"] for r in rows} == {"a.png", "b.png"}
     for row in rows:
         assert row["title"] == "Something"
         assert len(row["image_id"]) == 16
+        assert row["vision_provider"] == "gpt"
+        assert row["vision_model"] == "gpt-5.4"
 
 
 def test_failed_image_is_not_marked_written(tmp_path, monkeypatch):
@@ -195,7 +197,7 @@ def test_failed_image_is_not_marked_written(tmp_path, monkeypatch):
     )
 
     assert written == ["good.png"]
-    rows = _read_jsonl(tmp_path / "image_descriptions.jsonl")
+    rows = _read_jsonl(tmp_path / image_describer.IMAGE_DESCRIPTIONS_FILE)
     assert {r["source"] for r in rows} == {"good.png"}
 
 
@@ -223,7 +225,7 @@ def test_vision_call_exception_is_not_marked_written(tmp_path, monkeypatch):
     )
 
     assert len(written) == 1
-    rows = _read_jsonl(tmp_path / "image_descriptions.jsonl")
+    rows = _read_jsonl(tmp_path / image_describer.IMAGE_DESCRIPTIONS_FILE)
     assert len(rows) == 1
 
 
@@ -231,7 +233,7 @@ def test_resume_skips_already_done_images(tmp_path, monkeypatch):
     img1 = _make_png(tmp_path / "a.png")
     img2 = _make_png(tmp_path / "b.png")
 
-    descriptions_path = tmp_path / "image_descriptions.jsonl"
+    descriptions_path = tmp_path / image_describer.IMAGE_DESCRIPTIONS_FILE
     descriptions_path.write_text(
         json.dumps({"source": "a.png", "image_id": "x", "title": "Old", "description": "already done"}) + "\n",
         encoding="utf-8",

visual_parser-2.2.4/tests/test_pdf_tracker.py

@@ -0,0 +1,102 @@
+import os
+
+from visual_parser.pdf_tracker import (
+    find_new_pdfs,
+    load_processed_pdfs,
+    mark_as_processed,
+    unmark_as_processed,
+)
+
+
+def test_unmark_removes_a_match(tmp_path):
+    registry = tmp_path / "04_processed_pdfs.txt"
+    mark_as_processed(str(registry), ["a.pdf", "b.pdf"])
+
+    removed = unmark_as_processed(str(registry), ["a.pdf"])
+
+    assert removed == 1
+    assert load_processed_pdfs(str(registry)) == ["b.pdf"]
+
+
+def test_unmark_is_case_sensitive(tmp_path):
+    """Matches load_processed_pdfs/mark_as_processed's own convention --
+    these are what actually govern registry contents."""
+    registry = tmp_path / "04_processed_pdfs.txt"
+    mark_as_processed(str(registry), ["Doc.PDF"])
+
+    removed = unmark_as_processed(str(registry), ["doc.pdf"])
+
+    assert removed == 0
+    assert load_processed_pdfs(str(registry)) == ["Doc.PDF"]
+
+
+def test_unmark_noop_on_missing_registry(tmp_path):
+    registry = tmp_path / "04_processed_pdfs.txt"
+    assert unmark_as_processed(str(registry), ["a.pdf"]) == 0
+    assert not registry.exists()
+
+
+def test_unmark_does_not_rewrite_when_nothing_matches(tmp_path, monkeypatch):
+    registry = tmp_path / "04_processed_pdfs.txt"
+    mark_as_processed(str(registry), ["a.pdf"])
+
+    import visual_parser.pdf_tracker as pdf_tracker
+
+    def fail_if_called(*a, **k):
+        raise AssertionError("save_processed_pdfs should not be called when nothing matched")
+
+    monkeypatch.setattr(pdf_tracker, "save_processed_pdfs", fail_if_called)
+
+    removed = unmark_as_processed(str(registry), ["not-in-registry.pdf"])
+    assert removed == 0
+
+
+def test_find_new_pdfs_uses_explicit_registry_path_when_given(tmp_path):
+    """Regression test for the input_dir/output_dir registry mismatch: when
+    output_dir differs from input_dir, the registry actually lives in
+    output_dir, so an explicit registry_path must be honored instead of the
+    input_dir-joined default."""
+    input_dir = tmp_path / "in"
+    output_dir = tmp_path / "out"
+    input_dir.mkdir()
+    output_dir.mkdir()
+    (input_dir / "a.pdf").write_bytes(b"stub")
+
+    real_registry = output_dir / "04_processed_pdfs.txt"
+    mark_as_processed(str(real_registry), ["a.pdf"])
+
+    new_pdfs = find_new_pdfs(str(input_dir), registry_path=str(real_registry))
+
+    assert new_pdfs == []
+
+
+def test_find_new_pdfs_default_registry_path_unchanged(tmp_path):
+    """Backward compatibility: omitting registry_path must keep resolving the
+    registry against input_dir, exactly as before -- this is what RADIANT-LLM
+    and any other same-folder caller relies on."""
+    input_dir = tmp_path / "in"
+    input_dir.mkdir()
+    (input_dir / "a.pdf").write_bytes(b"stub")
+
+    registry_in_input_dir = input_dir / "04_processed_pdfs.txt"
+    mark_as_processed(str(registry_in_input_dir), ["a.pdf"])
+
+    new_pdfs = find_new_pdfs(str(input_dir))
+
+    assert new_pdfs == []
+
+
+def test_find_new_pdfs_rebuild_ignores_registry_path(tmp_path):
+    input_dir = tmp_path / "in"
+    output_dir = tmp_path / "out"
+    input_dir.mkdir()
+    output_dir.mkdir()
+    pdf_path = input_dir / "a.pdf"
+    pdf_path.write_bytes(b"stub")
+
+    real_registry = output_dir / "04_processed_pdfs.txt"
+    mark_as_processed(str(real_registry), ["a.pdf"])
+
+    new_pdfs = find_new_pdfs(str(input_dir), rebuild=True, registry_path=str(real_registry))
+
+    assert new_pdfs == [str(pdf_path)]