Skip to content

LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows

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.py
index 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_cap
from unstract.sdk1.constants import MimeType
from unstract.sdk1.exceptions import FileOperationError
from 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.py
index 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 base64
import logging
+import os
import re
from dataclasses import dataclass
from pathlib import PurePosixPath
@@ -43,19 +44,61 @@ from unstract.sdk1.file_storage import FileStorage
logger = 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.py
index 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 summary
assert "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.py
index 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 Path
import pytest
from 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.value
assert err.page_count == 5
assert 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 == 51
assert 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 msg
diff --git a/workers/executor/executors/vlm_image_answer.py b/workers/executor/executors/vlm_image_answer.py
index 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.py
index 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: E402
IMAGE_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(