LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
"""Gating for the LLMWhisperer image output mode.
Image output mode produces per-page PNGs that are consumed by the VLM answer
plugin, which ships only with Unstract Cloud. On deployments without the
``plugins.vlm_image_answer`` package the mode is hidden from the adapter's
JSON schema and rejected at save/test time, so users cannot configure a
per-page billed extraction whose output nothing can consume.
"""
import copy
import logging
from typing import Any
from rest_framework.exceptions import ValidationError
from unstract.sdk1.adapters.x2text.constants import ImageOutputConstants
logger = logging.getLogger(__name__)
LLMWHISPERER_ADAPTER_PREFIX = "llmwhisperer|"
IMAGE_OUTPUT_REQUIRES_CLOUD = (
"The 'image' output mode is available only on Unstract Cloud."
)
def _consumer_plugin_available() -> bool:
"""True only when the package AND its backend hooks import.
A half-broken install (package present, ``backend_hooks`` failing to
import) must gate image mode off — fail-closed — rather than leave
the mode enabled while the re-extraction invalidation and deploy
validation hooks quietly stop existing.
"""
try:
import plugins.vlm_image_answer # noqa: F401
except ImportError:
return False
try:
import plugins.vlm_image_answer.backend_hooks # noqa: F401
except ImportError:
logger.error(
"plugins.vlm_image_answer is installed but backend_hooks "
"failed to import; disabling image output mode (fail-closed)"
)
return False
return True
IMAGE_OUTPUT_CONSUMER_AVAILABLE = _consumer_plugin_available()
def _is_image_mode_condition(block: dict[str, Any]) -> bool:
"""True if an ``allOf`` block is conditioned on the image output mode."""
const = (
block.get("if", {})
.get("properties", {})
.get(ImageOutputConstants.OUTPUT_MODE, {})
.get("const")
)
return const == ImageOutputConstants.IMAGE_MODE
def filter_image_output_mode(adapter_id: str, schema: dict[str, Any]) -> dict[str, Any]:
"""Strip the image output-mode option from an adapter's JSON schema.
No-op when the consumer plugin is available, for non-LLMWhisperer
adapters, or when the schema has no image option. Returns a filtered
deep copy otherwise (the SDK-provided schema is shared state).
"""
if IMAGE_OUTPUT_CONSUMER_AVAILABLE:
return schema
if not adapter_id.startswith(LLMWHISPERER_ADAPTER_PREFIX):
return schema
output_mode = schema.get("properties", {}).get(ImageOutputConstants.OUTPUT_MODE, {})
if ImageOutputConstants.IMAGE_MODE not in output_mode.get("enum", []):
return schema
schema = copy.deepcopy(schema)
output_mode = schema["properties"][ImageOutputConstants.OUTPUT_MODE]
idx = output_mode["enum"].index(ImageOutputConstants.IMAGE_MODE)
output_mode["enum"].pop(idx)
enum_names = output_mode.get("enumNames")
if enum_names and len(enum_names) > idx:
enum_names.pop(idx)
if "allOf" in schema:
schema["allOf"] = [
block for block in schema["allOf"] if not _is_image_mode_condition(block)
]
return schema
def validate_image_output_allowed(
adapter_metadata: dict[str, Any] | None, adapter_id: str | None = None
) -> None:
"""Reject image output mode when the consumer plugin is unavailable.
Backstop for the schema filtering above: covers adapters created or
updated via the API (bypassing the UI form) and test-connection calls.
When ``adapter_id`` is unknown (e.g. a metadata-only update) the check
falls back to the metadata alone — only the LLMWhisperer V2 adapter
exposes an ``image`` output mode.
"""
if IMAGE_OUTPUT_CONSUMER_AVAILABLE or not adapter_metadata:
return
if (
adapter_metadata.get(ImageOutputConstants.OUTPUT_MODE)
!= ImageOutputConstants.IMAGE_MODE
):
return
if adapter_id is not None and not adapter_id.startswith(LLMWHISPERER_ADAPTER_PREFIX):
return
logger.warning(
"Rejecting image output mode without the consumer plugin "
"(adapter_id=%s, output_mode=%s)",
adapter_id,
adapter_metadata.get(ImageOutputConstants.OUTPUT_MODE),
)
# Dict detail, not a bare string: this is raised from inside
# ``to_internal_value``, where DRF folds the detail into its per-field
# error mapping — a bare string there crashes error collection with a
# 500 instead of surfacing a clean 400.
raise ValidationError({"adapter_metadata": [IMAGE_OUTPUT_REQUIRES_CLOUD]})