LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
UN-2646 [FIX] Raise the image-mode page cap to 300 and make its failures legible (#2322)
Praveen Kumar2a6c02f7dfbb
diff --git a/unstract/sdk1/src/unstract/sdk1/adapters/x2text/llm_whisperer_v2/src/helper.py b/unstract/sdk1/src/unstract/sdk1/adapters/x2text/llm_whisperer_v2/src/helper.pyindex 17c027822..92245b703 100644--- a/unstract/sdk1/src/unstract/sdk1/adapters/x2text/llm_whisperer_v2/src/helper.py+++ b/unstract/sdk1/src/unstract/sdk1/adapters/x2text/llm_whisperer_v2/src/helper.py@@ -38,6 +38,7 @@ from unstract.sdk1.adapters.x2text.llm_whisperer_v2.src.constants import (from unstract.sdk1.adapters.x2text.llm_whisperer_v2.src.dto import (WhispererRequestParams,)+from unstract.sdk1.adapters.x2text.page_image_loader import configured_page_capfrom unstract.sdk1.constants import MimeTypefrom unstract.sdk1.exceptions import FileOperationErrorfrom unstract.sdk1.file_storage import FileStorage, FileStorageProvider@@ -908,6 +909,25 @@ class LLMWhispererHelper:fs = FileStorage(provider=FileStorageProvider.LOCAL)input_bytes = fs.read(path=input_file_path, mode="rb")++ # Reject an over-cap document BEFORE submitting: pdf-to-images bills+ # per converted page, and the answer-time cap would reject the result+ # anyway — so without this check the caller pays to convert a document+ # that can never be answered. Best-effort by design: a PDF whose count+ # cannot be read locally falls through and is caught at answer time.+ expected_page_count = LLMWhispererHelper._safe_pdf_page_count(input_bytes)+ page_cap = configured_page_cap()+ if expected_page_count is not None and expected_page_count > page_cap:+ raise ExtractorError(+ f"Document exceeds the {page_cap}-page limit for image output "+ f"mode ({expected_page_count} pages). Image mode answers a "+ "prompt in one request containing every page image, so a "+ "larger document cannot be answered. Split the document, or "+ "select a text output mode instead. Nothing was converted or "+ "billed.",+ status_code=400,+ )+whisper_hash = LLMWhispererHelper.submit_pdf_to_images(config,BytesIO(input_bytes),@@ -921,9 +941,8 @@ class LLMWhispererHelper:)# Verify the returned image count against the input PDF's own page count- # (derived locally) BEFORE persisting, so nothing is written on a- # truncated/over-produced archive.- expected_page_count = LLMWhispererHelper._safe_pdf_page_count(input_bytes)+ # (derived locally above, before submission) BEFORE persisting, so+ # nothing is written on a truncated/over-produced archive.LLMWhispererHelper.verify_page_count(pages, expected_page_count)page_store_dir = LLMWhispererHelper.build_page_store_dir(diff --git a/unstract/sdk1/src/unstract/sdk1/adapters/x2text/page_image_loader.py b/unstract/sdk1/src/unstract/sdk1/adapters/x2text/page_image_loader.pyindex 39fa60e4d..1ae959b6d 100644--- a/unstract/sdk1/src/unstract/sdk1/adapters/x2text/page_image_loader.py+++ b/unstract/sdk1/src/unstract/sdk1/adapters/x2text/page_image_loader.py@@ -34,6 +34,7 @@ full rationale.import base64import logging+import osimport refrom dataclasses import dataclassfrom pathlib import PurePosixPath@@ -43,19 +44,61 @@ from unstract.sdk1.file_storage import FileStoragelogger = logging.getLogger(__name__)-# Conservative default; effective value is supplied by the caller-# (platform-configured), this is only the fallback.-DEFAULT_PAGE_CAP = 20+# Effective value is supplied by the caller (platform-configured); this is+# only the fallback. 300 is the product limit agreed for image mode — above+# it a document is rejected rather than windowed, because this path answers+# in a single call. Note that a model's own per-request image limit can be+# lower than this (e.g. 100 images on a 200K-context model), which is why+# provider rejections are mapped to a typed error by the caller rather than+# being prevented by this cap alone.+DEFAULT_PAGE_CAP = 300# Aggregate raw-byte budget across all loaded pages. The page cap bounds the# COUNT of images, not their size — without a byte budget, unusually large-# renders would grow worker memory and the provider request unbounded-# (base64 adds ~33% on top). 50MB raw comfortably exceeds any normal-# LLMWhisperer render while staying inside provider request limits.-DEFAULT_MAX_TOTAL_BYTES = 50 * 1024 * 1024+# renders would grow worker memory and the provider request unbounded.+#+# Sized from the SMALLEST request limit across the providers this path can+# target (Amazon Bedrock and Gemini inline both cap a request at 20MB;+# Anthropic direct allows 32MB, Google Cloud 30MB), minus base64's ~33%+# inflation: 20MB / 1.34 ≈ 14MB of raw image bytes. A larger budget would+# let the provider reject the request before this check ever fires, which+# costs the caller a full read + encode and surfaces a raw provider error+# instead of the actionable one below.+DEFAULT_MAX_TOTAL_BYTES = 14 * 1024 * 1024_PAGE_NAME_RE = re.compile(ImageOutputConstants.PAGE_NUMBER_REGEX)+# Platform override for the page cap. Defined here — next to the default and+# the enforcement — so the two sites that need it agree: the extraction-time+# pre-check (adapter, before the per-page-billed conversion is submitted) and+# the answer-time enforcement (cloud consumer plugin).+PAGE_CAP_ENV = "VLM_IMAGE_ANSWER_PAGE_CAP"+++def configured_page_cap() -> int:+ """The effective page cap: ``PAGE_CAP_ENV`` or ``DEFAULT_PAGE_CAP``.++ An absent variable is the normal case and returns the default silently.+ A present-but-unusable value is an operator mistake: log it and fall back+ rather than failing extraction over a malformed env var.+ """+ raw = os.getenv(PAGE_CAP_ENV)+ if raw is None:+ return DEFAULT_PAGE_CAP+ try:+ value = int(raw)+ if value <= 0:+ raise ValueError("must be positive")+ except (TypeError, ValueError):+ logger.warning(+ "Invalid %s value %r; using default %d",+ PAGE_CAP_ENV,+ raw,+ DEFAULT_PAGE_CAP,+ )+ return DEFAULT_PAGE_CAP+ return value+class PageImageLoadError(Exception):"""Base error for page-image discovery/loading failures."""@@ -238,10 +281,13 @@ def load_page_images(discovered = discover_page_images(fs, page_store_dir)if page_cap is not None and len(discovered) > page_cap:raise PageCapExceededError(- f"Document exceeds {page_cap} pages for image output mode "- f"({len(discovered)} pages found). Reduce the page range (e.g. "- "via the adapter's 'pages to extract' setting) or raise the "- "configured page cap.",+ f"Document exceeds the {page_cap}-page limit for image output "+ f"mode ({len(discovered)} pages found). Image mode answers a "+ "prompt in one request containing every page image, so a larger "+ "document cannot be answered. Split the document, or extract it "+ "in a text output mode instead. (This limit is set by the "+ "platform via VLM_IMAGE_ANSWER_PAGE_CAP — it is not the "+ "adapter's 'pages to extract' setting.)",page_store_dir=page_store_dir,page_count=len(discovered),page_cap=page_cap,@@ -278,9 +324,11 @@ def load_page_images(raise PageImageSetTooLargeError(f"Page images total more than "f"{max_total_bytes // (1024 * 1024)}MB by page {page_number} "- f"of {len(discovered)} — too large to send to the LLM in "- "one request. Reduce the page range (e.g. via the adapter's "- "'pages to extract' setting).",+ f"of {len(discovered)} — larger than an LLM provider accepts "+ "in one request, so this document cannot be answered in "+ "image mode however many pages it has. Split the document, "+ "or extract it in a text output mode instead. (This budget "+ "is set by the platform via VLM_IMAGE_ANSWER_MAX_TOTAL_MB.)",page_store_dir=page_store_dir,total_bytes=total_bytes,max_total_bytes=max_total_bytes,diff --git a/unstract/sdk1/tests/test_llmw_image_helper.py b/unstract/sdk1/tests/test_llmw_image_helper.pyindex 6293578c2..559ef8369 100644--- a/unstract/sdk1/tests/test_llmw_image_helper.py+++ b/unstract/sdk1/tests/test_llmw_image_helper.py@@ -404,3 +404,70 @@ class TestImageOutputWrite:summary = H.build_image_output_summary(refs)assert "1 page image" in summaryassert "page_001.png" not in summary # references never inlined+++class TestPreSubmitPageCap:+ """The cap is checked BEFORE pdf-to-images is submitted.++ pdf-to-images bills every converted page, and the answer-time cap would+ reject the result anyway — so an over-cap document must fail before the+ conversion is paid for, converting nothing.+ """++ @staticmethod+ def _fs_with_pdf(monkeypatch: MonkeyPatch, page_count: int | None) -> MagicMock:+ """FileStorage whose input PDF reports ``page_count`` pages."""+ monkeypatch.setattr(+ H, "_safe_pdf_page_count", staticmethod(lambda _b: page_count)+ )+ fs = MagicMock(name="FileStorage")+ fs.read.return_value = b"%PDF-1.7 fake"+ return fs++ def test_over_cap_fails_before_submitting(self, monkeypatch: MonkeyPatch) -> None:+ monkeypatch.setenv("VLM_IMAGE_ANSWER_PAGE_CAP", "20")+ fs = self._fs_with_pdf(monkeypatch, 164)+ submit = MagicMock(name="submit_pdf_to_images")+ monkeypatch.setattr(H, "submit_pdf_to_images", staticmethod(submit))++ with pytest.raises(ExtractorError) as excinfo:+ H.get_page_images({}, "/in/doc.pdf", "/out/doc.txt", fs=fs)++ msg = str(excinfo.value)+ assert "exceeds the 20-page limit" in msg+ assert "164 pages" in msg+ assert "Nothing was converted or billed" in msg+ # The billed call never happened.+ submit.assert_not_called()++ def test_within_cap_proceeds_to_submit(self, monkeypatch: MonkeyPatch) -> None:+ monkeypatch.setenv("VLM_IMAGE_ANSWER_PAGE_CAP", "20")+ fs = self._fs_with_pdf(monkeypatch, 3)+ submit = MagicMock(name="submit", return_value="hash-1")+ monkeypatch.setattr(H, "submit_pdf_to_images", staticmethod(submit))+ monkeypatch.setattr(H, "poll_pdf_to_images_status", staticmethod(MagicMock()))+ pages = [(n, minimal_png()) for n in (1, 2, 3)]+ monkeypatch.setattr(H, "_download_and_extract", staticmethod(lambda **_k: pages))+ monkeypatch.setattr(H, "persist_page_images", staticmethod(lambda *_a: []))++ whisper_hash, _ = H.get_page_images({}, "/in/doc.pdf", "/out/doc.txt", fs=fs)++ assert whisper_hash == "hash-1"+ submit.assert_called_once()++ def test_unreadable_page_count_still_submits(self, monkeypatch: MonkeyPatch) -> None:+ # Best-effort by design: a PDF we cannot count locally must not be+ # blocked at extraction — the answer-time cap remains the backstop.+ monkeypatch.setenv("VLM_IMAGE_ANSWER_PAGE_CAP", "1")+ fs = self._fs_with_pdf(monkeypatch, None)+ submit = MagicMock(name="submit", return_value="hash-2")+ monkeypatch.setattr(H, "submit_pdf_to_images", staticmethod(submit))+ monkeypatch.setattr(H, "poll_pdf_to_images_status", staticmethod(MagicMock()))+ monkeypatch.setattr(+ H, "_download_and_extract", staticmethod(lambda **_k: [(1, minimal_png())])+ )+ monkeypatch.setattr(H, "persist_page_images", staticmethod(lambda *_a: []))++ H.get_page_images({}, "/in/doc.pdf", "/out/doc.txt", fs=fs)++ submit.assert_called_once()diff --git a/unstract/sdk1/tests/test_page_image_loader.py b/unstract/sdk1/tests/test_page_image_loader.pyindex 73f9650f6..2428cd57e 100644--- a/unstract/sdk1/tests/test_page_image_loader.py+++ b/unstract/sdk1/tests/test_page_image_loader.py@@ -12,12 +12,14 @@ from pathlib import Pathimport pytestfrom unstract.sdk1.adapters.x2text.page_image_loader import (DEFAULT_PAGE_CAP,+ PAGE_CAP_ENV,LoadedPageImage,PageCapExceededError,PageImageSetIncompleteError,PageImageSetTooLargeError,PageImagesNotFoundError,build_vision_message_content,+ configured_page_cap,discover_page_images,load_page_images,)@@ -112,7 +114,13 @@ class TestPageCap:err = excinfo.valueassert err.page_count == 5assert err.page_cap == 4- assert "exceeds 4 pages" in str(err)+ assert "exceeds the 4-page limit" in str(err)+ # Names the platform knob, and explicitly rules out the adapter's+ # "pages to extract" setting — pointing at that one sent a tester+ # hunting through a field they had never set (UN-2646 follow-up).+ assert "VLM_IMAGE_ANSWER_PAGE_CAP" in str(err)+ assert "not the adapter's 'pages to extract' setting" in str(err)+ assert "Reduce the page range" not in str(err)def test_cap_check_precedes_reads(self) -> None:# Fail-fast: no image bytes are read for an oversized document.@@ -263,7 +271,8 @@ class TestByteBudget:# the recorded total is budget + 1, and page 3 was never touched.assert err.total_bytes == 51assert err.max_total_bytes == 50- assert "pages to extract" in str(err)+ assert "VLM_IMAGE_ANSWER_MAX_TOTAL_MB" in str(err)+ assert "pages to extract" not in str(err)def test_single_oversized_page_reads_are_bounded(self) -> None:# A single pathological object must never be fully allocated: each@@ -306,9 +315,46 @@ class TestByteBudget:fs = _store({1: b"a" * 100})assert len(load_page_images(fs, _DIR, max_total_bytes=None)) == 1- def test_default_budget_is_generous(self) -> None:+ def test_default_budget_fits_the_strictest_provider_request_limit(+ self,+ ) -> None:+ # Bedrock and Gemini-inline both cap a request at 20MB; base64+ # inflates the payload ~33%, so the raw budget must leave room for+ # that. A budget above this lets the provider reject the request+ # before our own check fires.from unstract.sdk1.adapters.x2text.page_image_loader import (DEFAULT_MAX_TOTAL_BYTES,)- assert DEFAULT_MAX_TOTAL_BYTES == 50 * 1024 * 1024+ assert DEFAULT_MAX_TOTAL_BYTES == 14 * 1024 * 1024+ assert DEFAULT_MAX_TOTAL_BYTES * 4 / 3 < 20 * 1024 * 1024+++class TestConfiguredPageCap:+ """The env override shared by the extraction pre-check and the consumer."""++ def test_absent_env_uses_default(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv(PAGE_CAP_ENV, raising=False)+ assert configured_page_cap() == DEFAULT_PAGE_CAP++ def test_env_overrides_default(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv(PAGE_CAP_ENV, "42")+ assert configured_page_cap() == 42++ @pytest.mark.parametrize("raw", ["not-a-number", "0", "-5", ""])+ def test_unusable_value_falls_back(+ self, raw: str, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ # An operator typo must not fail extraction outright.+ monkeypatch.setenv(PAGE_CAP_ENV, raw)+ assert configured_page_cap() == DEFAULT_PAGE_CAP+++class TestByteBudgetMessage:+ def test_over_budget_names_the_platform_knob(self) -> None:+ fs = _store({1: b"x" * 2048, 2: b"y" * 2048})+ with pytest.raises(PageImageSetTooLargeError) as excinfo:+ load_page_images(fs, _DIR, page_cap=None, max_total_bytes=1024)+ msg = str(excinfo.value)+ assert "VLM_IMAGE_ANSWER_MAX_TOTAL_MB" in msg+ assert "pages to extract" not in msgdiff --git a/workers/executor/executors/vlm_image_answer.py b/workers/executor/executors/vlm_image_answer.pyindex 08706b8db..665b25f64 100644--- a/workers/executor/executors/vlm_image_answer.py+++ b/workers/executor/executors/vlm_image_answer.py@@ -52,6 +52,10 @@ IMAGE_OUTPUT_REQUIRES_CLOUD = "IMAGE_OUTPUT_REQUIRES_CLOUD"IMAGE_OUTPUT_MISSING = "IMAGE_OUTPUT_MISSING"IMAGE_PAGE_CAP_EXCEEDED = "IMAGE_PAGE_CAP_EXCEEDED"IMAGE_PAGES_TOO_LARGE = "IMAGE_PAGES_TOO_LARGE"+# Distinct from IMAGE_PAGES_TOO_LARGE (our own budget, caught before the+# call): this one is the PROVIDER rejecting a request the local checks+# allowed, because the model's per-request limit is lower than the cap.+IMAGE_REQUEST_TOO_LARGE = "IMAGE_REQUEST_TOO_LARGE"IMAGE_OUTPUT_UNSUPPORTED_OPERATION = "IMAGE_OUTPUT_UNSUPPORTED_OPERATION"VISION_LLM_REQUIRED = "VISION_LLM_REQUIRED"diff --git a/workers/executor/tests/test_vlm_image_answer_bridge.py b/workers/executor/tests/test_vlm_image_answer_bridge.pyindex adc0fb4e2..ed3b915ea 100644--- a/workers/executor/tests/test_vlm_image_answer_bridge.py+++ b/workers/executor/tests/test_vlm_image_answer_bridge.py@@ -24,6 +24,7 @@ from executor.executors.vlm_image_answer import ( # noqa: E402IMAGE_OUTPUT_UNSUPPORTED_OPERATION,IMAGE_PAGE_CAP_EXCEEDED,IMAGE_PAGES_TOO_LARGE,+ IMAGE_REQUEST_TOO_LARGE,detect_image_mode_config,raise_if_image_mode_unsupported,run_vlm_image_answer,@@ -263,6 +264,19 @@ class TestPluginDispatch:_run(plugin=plugin)assert excinfo.value.error_code == IMAGE_PAGE_CAP_EXCEEDED+ def test_provider_size_rejection_keeps_its_plugin_code(self):+ # The plugin maps a provider's "request too large" rejection to its+ # own typed error; the bridge must pass that code through rather+ # than swallow it into a generic failure. Distinct from+ # IMAGE_PAGES_TOO_LARGE, which is our own pre-call budget.+ plugin = MagicMock()+ rejection = RuntimeError("`gpt-x` rejected this request as too large")+ rejection.error_code = IMAGE_REQUEST_TOO_LARGE+ plugin.run_with_metrics.side_effect = rejection+ with pytest.raises(VlmImageAnswerError) as excinfo:+ _run(plugin=plugin)+ assert excinfo.value.error_code == IMAGE_REQUEST_TOO_LARGE+def test_too_large_error_maps_to_pages_too_large_code(self):plugin = MagicMock()plugin.run_with_metrics.side_effect = PageImageSetTooLargeError(