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] 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.pyindex 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 FileStoragelogger = 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.pyindex 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 msgassert "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