Skip to content

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

UN-2646 [FIX] Set the image-mode page cap to 90 so it matches the byte budget (#2323)

Praveen Kumara3f8705a97fd
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 1ae959b6d..49873ba0b 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
@@ -44,14 +44,47 @@ from unstract.sdk1.file_storage import FileStorage
logger = logging.getLogger(__name__)
-# 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
+# THE single source of truth for the image-mode page cap. Above it a document
+# is rejected rather than windowed, because this path answers in a single
+# call. It is read through configured_page_cap() by both the extraction-time
+# pre-check and the answer-time consumer, so they cannot disagree.
+#
+# Keep the value HERE. PAGE_CAP_ENV exists only as an emergency override and
+# is deliberately not set in any Helm chart: the cap is coupled to the byte
+# budget below, and TestCapMatchesBudget can only check the pair when both
+# live in this file. A deployment-level override silently bypasses that
+# check — e.g. raising the cap to 300 in a chart while the budget still holds
+# ~90 pages reopens the billed-then-rejected window described below.
+#
+# RAISING THIS ABOVE 999 ALSO NEEDS LLMWHISPERER CHANGES. Image mode's pages
+# come from LLMWhisperer's /pdf-to-images endpoint, which:
+# - hardcodes a 999-page maximum (PDFToImagesConverter.MAX_PAGES, tied to
+# the page_001..page_999 file naming) with no env override — a cap above
+# 999 here still fails there, with LLMWhisperer's less specific error.
+# Increases up to 999 need no service change;
+# - bills per converted page, so a document the cap admits but the byte
+# budget then rejects is still charged for every page.
+# Coordinate anything above 999 with the LLMWhisperer service. For ANY
+# increase, raise the byte budget and this cap together (or add windowing) —
+# never the cap alone.
+#
+# 90 is derived from DEFAULT_MAX_TOTAL_BYTES below, not chosen independently:
+# at the ~165-379KB per page measured from LLMWhisperer's 150 DPI renders, a
+# 14MB budget holds roughly 38-89 pages (90 is the round number at the top
+# of that range; the page sizes are approximate, measured from archive
+# sizes on two test documents — see TestCapMatchesBudget).
+# A higher cap is effectively unreachable — and worse, it defeats the
+# extraction-time pre-check, which only knows the page COUNT: a 200-page
+# document would pass a 300 cap, be converted and billed per page, then
+# fail at answer time on the byte budget. Keeping the cap at the top of
+# what the budget allows means a document over the cap is refused before
+# any conversion is billed.
+#
+# It also sits under every provider's other ceilings: the strictest image
+# count (100 per request on Anthropic's 200K-context models) and context
+# window (~90 x 1,500 tokens per page = ~135K tokens). Raising it materially
+# needs windowing across multiple calls, not a bigger number.
+DEFAULT_PAGE_CAP = 90
# 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
@@ -64,6 +97,11 @@ DEFAULT_PAGE_CAP = 300
# 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.
+#
+# Like DEFAULT_PAGE_CAP above, keep the value HERE rather than in a Helm
+# chart: the two are a coupled pair, checked together by
+# TestCapMatchesBudget. VLM_IMAGE_ANSWER_MAX_TOTAL_MB is an emergency
+# override only.
DEFAULT_MAX_TOTAL_BYTES = 14 * 1024 * 1024
_PAGE_NAME_RE = re.compile(ImageOutputConstants.PAGE_NUMBER_REGEX)
diff --git a/unstract/sdk1/tests/test_page_image_loader.py b/unstract/sdk1/tests/test_page_image_loader.py
index 2428cd57e..d8242d11f 100644
--- a/unstract/sdk1/tests/test_page_image_loader.py
+++ b/unstract/sdk1/tests/test_page_image_loader.py
@@ -358,3 +358,48 @@ class TestByteBudgetMessage:
msg = str(excinfo.value)
assert "VLM_IMAGE_ANSWER_MAX_TOTAL_MB" in msg
assert "pages to extract" not in msg
+
+
+class TestCapMatchesBudget:
+ """The page cap must stay within what the byte budget can deliver.
+
+ The extraction-time pre-check only knows the page COUNT. If the cap
+ allows more pages than the byte budget can carry, a document between the
+ two passes the pre-check, is converted and billed per page, and then
+ fails at answer time — billed for something that can never be answered.
+ """
+
+ # Lightest page render measured from LLMWhisperer at its default 150 DPI:
+ # a 50-page PDF produced an 8,233,339-byte pdf-to-images archive.
+ #
+ # This is the ARCHIVE size, not the sum of extracted PNG bytes that
+ # load_page_images counts — an approximation, and deliberately treated
+ # as one. PNG data is already deflate-compressed, so zipping it saves
+ # little, and per-entry headers are ~100 bytes; the archive should be
+ # within a few percent of the image bytes, which is a couple of pages
+ # either side at this cap. So the guard below allows that much slack
+ # rather than asserting an exact page count it cannot back up. Measuring
+ # extracted bytes on real documents is the proper calibration.
+ _APPROX_LIGHT_PAGE_BYTES = 8_233_339 // 50 # ~164,666 bytes
+
+ # Pages of slack for the archive-vs-extracted-bytes measurement error.
+ _MEASUREMENT_SLACK_PAGES = 2
+
+ def test_cap_stays_near_what_the_budget_can_carry(self) -> None:
+ # At the lightest measured page size the 14MB budget holds ~89 pages;
+ # 90 is the round product number at the top of that. This fails if
+ # the cap and the budget drift apart by more than the measurement
+ # slack — e.g. the cap raised back to 300, or the budget cut without
+ # lowering the cap — which is the drift that reopens the
+ # billed-then-rejected window.
+ from unstract.sdk1.adapters.x2text.page_image_loader import (
+ DEFAULT_MAX_TOTAL_BYTES,
+ )
+
+ capacity = DEFAULT_MAX_TOTAL_BYTES // self._APPROX_LIGHT_PAGE_BYTES
+ assert DEFAULT_PAGE_CAP <= capacity + self._MEASUREMENT_SLACK_PAGES
+
+ def test_cap_is_under_the_strictest_provider_image_count(self) -> None:
+ # Anthropic accepts at most 100 images per request on its
+ # 200K-context models — the lowest image-count limit we target.
+ assert DEFAULT_PAGE_CAP <= 100